{ "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. To create the Account within an Organization, provide `unit.id` and omit `standalone`. To create a standalone Free Account, provide `standalone: true` and omit `unit`. Providing both fields is invalid. If you omit both fields, Cloudflare can determine the destination only when the User is an administrator of exactly one Organization. Cloudflare creates the Account in that Organization; otherwise, the request returns an error.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional key that identifies an Account-creation request. Free Account creation can require exactly one valid key, so API clients should send a key with every Account-creation request. Reuse the same key when retrying the same request.", "schema": { "type": "string", "maxLength": 128, "minLength": 1 } } ], "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": { "$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": { "$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": { "$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": { "$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": { "$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": { "$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": { "$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": { "$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": "tool-call-analytics" } }, "/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": "tool-call-analytics" } }, "/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-analytics" } }, "/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" }, "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" } }, "/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-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" }, "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-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" }, "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" } }, "/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-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" }, "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-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" } }, "/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. Dashboard sessions only: API token, OAuth, and service credentials are rejected with 403.", "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. Dashboard sessions only: API token, OAuth, and service credentials are rejected with 403.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "logpush": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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": "d33069ed", "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "logpush": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "logpush": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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", "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } }, "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": { "description": "Filter values.", "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": { "description": "Free-text search over log metadata.", "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": { "description": "Filter values.", "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": { "description": "Model filter.", "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", "minLength": 1 }, "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", "minLength": 1 } }, "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", "minLength": 1 }, "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", "minLength": 1 } }, "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", "minLength": 1 }, "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", "minLength": 1 } }, "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", "minLength": 1 }, "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", "minLength": 1 } }, "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", "minLength": 1 } }, "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", "minLength": 1 } }, "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", "minLength": 1 }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "logpush": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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": "b7707cff", "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "logpush": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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": "41a25eb6", "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "logpush": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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": "f1a47558", "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "logpush": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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": "878ad6d1", "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } }, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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": "Metadata filter unknown field.", "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": "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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": "Metadata filter unknown field.", "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": "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" ] } } } } }, "deprecated": true, "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.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.", "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" ] } } } } }, "deprecated": true, "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", "nullable": true, "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", "nullable": true, "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", "nullable": true, "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", "nullable": true, "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": "Metadata filter unknown field.", "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": "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": "Metadata filter unknown field.", "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": "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": "Metadata filter unknown field.", "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" ] } } } }, "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": "Metadata filter unknown field.", "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": "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": "Metadata filter unknown field.", "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": "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": "get-model-schema" } }, "/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": "run-model" } }, "/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": "to-markdown" } }, "/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" ] }, "x-auditable": true }, { "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}/billable/usage/billable-metrics": { "get": { "operationId": "billable-usage-v2-get-account-billable-metrics", "summary": "List Account Billable Metrics (Version 2, Alpha, Restricted)", "description": "Lists billable metrics available to the account through contracts and\nsubscriptions that overlap the requested period. Results are\ndeduplicated and ordered. If no qualifying contract exists, the\nresult is an empty array.\n\nWhen `from` and `to` are omitted, the period defaults to the start of\nthe current month 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 billable metrics were successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_v2_account_billable_metrics_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-billable-metrics" } }, "/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" }, "503": { "$ref": "#/components/responses/brex_ServiceUnavailable" } }, "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" }, "503": { "$ref": "#/components/responses/brex_ServiceUnavailable" } }, "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" }, "503": { "$ref": "#/components/responses/brex_ServiceUnavailable" } }, "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" }, "503": { "$ref": "#/components/responses/brex_ServiceUnavailable" } }, "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" }, "503": { "$ref": "#/components/responses/brex_ServiceUnavailable" } }, "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" }, "503": { "$ref": "#/components/responses/brex_ServiceUnavailable" } }, "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-extension/config/logs/extension-events/search": { "parameters": [ { "$ref": "#/components/parameters/brex_AccountId" } ], "post": { "operationId": "accounts-browser-extension-config-extension-events-search", "summary": "Search browser extension event logs", "description": "Searches browser extension event logs for an account. The request accepts\nonly supported fields and filters; raw SQL is not accepted.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ExtensionEventsSearchRequest" } } } }, "responses": { "200": { "description": "Browser extension event log search response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ExtensionEventsSearchResponse" } } } }, "400": { "$ref": "#/components/responses/brex_BadRequest" }, "401": { "$ref": "#/components/responses/brex_Unauthorized" }, "403": { "$ref": "#/components/responses/brex_Forbidden" }, "413": { "$ref": "#/components/responses/brex_BadRequest" }, "500": { "$ref": "#/components/responses/brex_InternalServerError" }, "502": { "$ref": "#/components/responses/brex_InternalServerError" }, "503": { "$ref": "#/components/responses/brex_InternalServerError" } }, "security": [ { "api_token": [] } ], "tags": [ "Browser Extension Config" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "browser-extension.config.logs.extension-events", "x-fern-sdk-method-name": "search", "x-stability": "beta" } }, "/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 script element into the page with the desired URL or content.", "type": "array", "items": { "additionalProperties": false, "properties": { "content": { "type": "string" }, "id": { "type": "string" }, "type": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "addStyleTag": { "description": "Adds a `` tag into the page with the desired URL or a `