{ "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": { "/_heartbeat": { "get": { "operationId": "getHeartbeat", "summary": "Heartbeat response", "description": "Used by Kubernetes readiness and liveness probes, and CI builder by executing test/staging.sh.", "responses": { "200": { "description": "Ok.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Service Unavailable." } }, "security": [ { "APIToken": [] } ], "tags": [ "health" ], "x-fern-sdk-group-name": "dns.domainconnect", "x-fern-sdk-method-name": "getHeartbeat" } }, "/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-ignore": true, "x-fern-sdk-group-name": "accounts.batch", "x-fern-sdk-method-name": "move" } }, "/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 against the account", "description": "List abuse reports made against domains or other content associated with the account. To list reports that the account submitted, use the submitted abuse reports endpoint instead.", "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": "search", "in": "query", "description": "Free-text search. Returns reports whose report ID starts with the term or whose domain contains the term, both case-insensitively. Surrounding whitespace is ignored, and an empty value is treated as absent. Combined with the other filters using AND.", "schema": { "type": "string", "maxLength": 255 }, "example": "example.com" }, { "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" ] } } } }, "400": { "description": "Invalid account or query parameters, including a search term longer than 255 characters." }, "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\n`Trust and Safety Read` or `Trust and Safety Write` permission for\nthis account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "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" } }, "/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.\nThe API token needs the `Trust and Safety Read` or\n`Trust and Safety Write` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "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" } }, "/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.\nThe API token needs the `Trust and Safety Read` or\n`Trust and Safety Write` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "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" } }, "/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.\nThe API token needs the `Trust and Safety Read` or\n`Trust and Safety Write` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "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" } }, "/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.\nReport-level appeals are currently available only for DMCA (copyright) reports. For other report types this operation returns the same `404 Report not found` response as a report that does not exist for 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": "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\n`Trust and Safety Read` or `Trust and Safety Write` permission for\nthis account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "404": { "description": "The report was not found for this account, or its type does not support report-level appeals (currently DMCA reports only).", "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" } }, "/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\n`Trust and Safety Read` or `Trust and Safety Write` permission for\nthis account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "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" } }, "/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\n`Trust and Safety Read` or `Trust and Safety Write` permission for\nthis account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "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" } }, "/accounts/{account_id}/abuse-reports/{report_id}/mitigations/appeal": { "post": { "operationId": "RequestReview", "summary": "Request review on mitigations", "description": "Request a review of mitigations applied because of an abuse report, or submit a report-level appeal.\n\n- To request a review of specific mitigations, send `appeals` with the mitigation IDs and reasons. Repeating a request for a mitigation with an unresolved appeal is idempotent and returns that mitigation in the in-review state.\n- To submit a report-level appeal, send `type` and, for a `counter_notice`, the counter-notice details in `data`. Report-level appeals are currently available only for DMCA (copyright) reports.", "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\n`Trust and Safety Write` permission for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "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" } }, "/accounts/{account_id}/abuse-reports/{report_param}": { "get": { "operationId": "GetAbuseReport", "summary": "Get an abuse report against the account", "description": "Retrieve the details of an abuse report made against a domain or other content associated with the account. To retrieve a report that the account submitted, use the submitted abuse report endpoint instead.", "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": "Public report ID.", "required": true, "schema": { "type": "string" }, "x-fern-parameter-name": "report-id" } ], "responses": { "200": { "description": "Abuse report found.", "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\n`Trust and Safety Read` or `Trust and Safety Write` permission for\nthis account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "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" }, "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 `Trust and Safety Write` permission. If the account\nis not entitled, the request is rejected with an HTTP `401` response\n(see below).\n\nDelegated reports: In limited circumstances, Cloudflare works with\nselect customers who have established abuse-handling programs. For\nthese customers, Cloudflare may forward abuse reports directly and in\nfull—including reporter contact information, comments, and supporting\nevidence—without redaction or preprocessing by Cloudflare. This allows\nthe customer to investigate and respond using their own policies and\nprocesses. For delegated reports, the report—including contact\ninformation and comments—will be forwarded to the customer in full\nregardless of the `host_notification` and `owner_notification` values.", "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" }, "x-fern-parameter-name": "report-type" } ], "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`Trust and Safety Write` permission. Entitlement failures\nreturn the message `Not entitled to use feature: Abuse Report API`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "403": { "description": "Cloudflare's API layer rejected the request because the API token or\nOAuth grant does not have the required Trust and Safety permission for\nthis account. The response uses error code `10000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" } } } }, "429": { "description": "The submitter is over an enforced intake rate limit; the report was not created", "headers": { "Retry-After": { "description": "Seconds to wait before the next submission can be accepted.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_RateLimitedErrorResponse" } } } }, "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-api-token-group": [ "Trust and Safety Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports", "x-fern-sdk-method-name": "create" } }, "/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 } }, { "name": "response_status", "in": "query", "description": "Response status to count; 'all' counts every status", "schema": { "description": "Response status to count; 'all' counts every status", "type": "string", "default": "success", "enum": [ "success", "error", "cached", "all" ] } } ], "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" ] }, "response_status": { "type": "string", "enum": [ "success", "error", "cached", "all" ] }, "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", "response_status", "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 } }, { "name": "response_status", "in": "query", "description": "Response status to count; 'all' counts every status", "schema": { "description": "Response status to count; 'all' counts every status", "type": "string", "default": "success", "enum": [ "success", "error", "cached", "all" ] } } ], "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" ] }, "response_status": { "type": "string", "enum": [ "success", "error", "cached", "all" ] }, "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", "response_status", "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 } }, { "name": "response_status", "in": "query", "description": "Response status to count; 'all' counts every status", "schema": { "description": "Response status to count; 'all' counts every status", "type": "string", "default": "success", "enum": [ "success", "error", "cached", "all" ] } } ], "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" ] }, "response_status": { "type": "string", "enum": [ "success", "error", "cached", "all" ] }, "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", "response_status", "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": { "description": "Hide this server's tools and prompts by default. To expose specific capabilities, set enabled: true for them in updated_tools or updated_prompts.", "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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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": "Hide this server's tools and prompts by default. To expose specific capabilities, set enabled: true for them in this server entry's updated_tools or updated_prompts fields when creating or updating 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": { "description": "Hide this server's tools and prompts by default. To expose specific capabilities, set enabled: true for them in updated_tools or updated_prompts.", "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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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": { "description": "Hide this server's tools and prompts by default. To expose specific capabilities, set enabled: true for them in updated_tools or updated_prompts.", "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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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": "Hide this server's tools and prompts by default. To expose specific capabilities, set enabled: true for them in this server entry's updated_tools or updated_prompts fields when creating or updating 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": { "description": "Hide this server's tools and prompts by default. To expose specific capabilities, set enabled: true for them in updated_tools or updated_prompts.", "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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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": "Credential configuration 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\":\"...\"}}`). For auth_type \"oauth\" with a pre-registered client, send a JSON-encoded object containing `auth_mode:\"manual\"`, `config.authorization_endpoint`, `config.token_endpoint`, and `registration_info.client_id`. Also provide `registration_info.redirect_uris` unless `is_shared_oauth_callback_enabled` is true. Optional fields include `config.issuer`, `config.revocation_endpoint`, `registration_info.scope`, and `registration_info.token_endpoint_auth_method`. Send the client secret in the separate `client_secret` field. Omit `auth_credentials` on update to preserve the existing configuration.", "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'. Required when creating a manual OAuth server or converting an existing server to manual mode. Omit it on update to preserve the existing secret; provide it to rotate the secret. 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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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": "Credential configuration 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\":\"...\"}}`). For auth_type \"oauth\" with a pre-registered client, send a JSON-encoded object containing `auth_mode:\"manual\"`, `config.authorization_endpoint`, `config.token_endpoint`, and `registration_info.client_id`. Also provide `registration_info.redirect_uris` unless `is_shared_oauth_callback_enabled` is true. Optional fields include `config.issuer`, `config.revocation_endpoint`, `registration_info.scope`, and `registration_info.token_endpoint_auth_method`. Send the client secret in the separate `client_secret` field. Omit `auth_credentials` on update to preserve the existing configuration.", "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'. Required when creating a manual OAuth server or converting an existing server to manual mode. Omit it on update to preserve the existing secret; provide it to rotate the secret. 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 }, "registered_at": { "description": "Timestamp of the most recent successful admin OAuth registration.", "type": "string", "format": "date-time", "nullable": true, "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-8" } } } }, "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-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-9" }, { "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-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-5" } } } }, "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.short-lived-certificates", "x-fern-sdk-method-name": "list" } }, "/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" }, "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-9" } } } }, "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-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-9" }, { "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-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.short-lived-certificates", "x-fern-sdk-method-name": "delete" }, "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-6" } } } }, "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.short-lived-certificates", "x-fern-sdk-method-name": "get" }, "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-6" } } } }, "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.short-lived-certificates", "x-fern-sdk-method-name": "create" } }, "/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-9" } } } }, "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": "deprecated", "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "list" }, "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-10" } } } }, "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": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "create" } }, "/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": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "delete" }, "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-10" } } } }, "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": "deprecated", "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "get" }, "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-10" } } } }, "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": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "update" } }, "/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-9" } } } }, "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.access.applications.policies", "x-fern-sdk-method-name": "make-reusable" } }, "/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-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-ignore": true, "x-fern-sdk-group-name": "zero-trust.access.applications.settings", "x-fern-sdk-method-name": "edit" }, "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" } }, "/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" } }, "/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-17" } } } }, "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.mfa.authenticator-catalog", "x-fern-sdk-method-name": "list" } }, "/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-15" } } } }, "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": "deprecated", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "list" } }, "/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": "deprecated", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "delete" }, "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-14" } } } }, "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": "deprecated", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "get" }, "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-14" } } } }, "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": "deprecated", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "create" }, "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-14" } } } }, "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": "deprecated", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "update" } }, "/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-6" } } } }, "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.mtls-certificates", "x-fern-sdk-method-name": "list" }, "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-7" } } } }, "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.mtls-certificates", "x-fern-sdk-method-name": "create" } }, "/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.mtls-certificates.settings", "x-fern-sdk-method-name": "get" }, "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.mtls-certificates.settings", "x-fern-sdk-method-name": "update" } }, "/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.mtls-certificates", "x-fern-sdk-method-name": "delete" }, "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-7" } } } }, "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.mtls-certificates", "x-fern-sdk-method-name": "get" }, "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-7" } } } }, "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.mtls-certificates", "x-fern-sdk-method-name": "update" } }, "/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-11" } } } }, "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" }, "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" } }, "/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" } }, "/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" }, "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-12" } } } }, "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" }, "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" } }, "/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-7" } } } }, "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.infrastructure.ssh-ca", "x-fern-sdk-method-name": "list" }, "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-8" } } } }, "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.infrastructure.ssh-ca", "x-fern-sdk-method-name": "create" } }, "/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.infrastructure.ssh-ca", "x-fern-sdk-method-name": "delete" } }, "/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.rule-groups", "x-fern-sdk-method-name": "list" }, "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.rule-groups", "x-fern-sdk-method-name": "create" } }, "/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.rule-groups", "x-fern-sdk-method-name": "delete" }, "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.rule-groups", "x-fern-sdk-method-name": "get" }, "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.rule-groups", "x-fern-sdk-method-name": "update" } }, "/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" }, "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" } }, "/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" }, "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" }, "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" } }, "/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" } }, "/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" } }, "/accounts/{account_id}/access/identity_providers/{identity_provider_id}/scim/groups/{group_id}": { "delete": { "operationId": "access-identity-providers-delete-scim-group-resource", "summary": "Delete a SCIM Group resource", "description": "Deletes a SCIM Group resource from the identity provider's SCIM population.", "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": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "204": { "description": "SCIM Group resource deleted." }, "4XX": { "description": "Failed to delete the SCIM Group resource.", "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.scim.groups", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "access-identity-providers-get-scim-group-resource", "summary": "Get a SCIM Group resource", "description": "Returns a SCIM Group resource, including its direct members, 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": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Returns a SCIM Group resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_group_response" } } } }, "4XX": { "description": "Indicates a failure to get a SCIM Group resource.", "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": "get" } }, "/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" } }, "/accounts/{account_id}/access/identity_providers/{identity_provider_id}/scim/users/{user_id}": { "delete": { "operationId": "access-identity-providers-delete-scim-user-resource", "summary": "Delete a SCIM User resource", "description": "Deletes a SCIM User resource from the identity provider's SCIM population.", "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": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "204": { "description": "SCIM User resource deleted." }, "4XX": { "description": "Failed to delete the SCIM User resource.", "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.scim.users", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "access-identity-providers-get-scim-user-resource", "summary": "Get a SCIM User resource", "description": "Returns a SCIM User resource 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": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Returns a SCIM User resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_user_response" } } } }, "4XX": { "description": "Indicates a failure to get a SCIM User resource.", "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": "get" } }, "/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.identity-providers.federation-grants", "x-fern-sdk-method-name": "list", "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.identity-providers.federation-grants", "x-fern-sdk-method-name": "create", "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.identity-providers.federation-grants", "x-fern-sdk-method-name": "delete" }, "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.identity-providers.federation-grants", "x-fern-sdk-method-name": "get", "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-13" } } } }, "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.signing-keys", "x-fern-sdk-method-name": "get" }, "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-13" } } } }, "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.signing-keys", "x-fern-sdk-method-name": "update" } }, "/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-13" } } } }, "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.signing-keys", "x-fern-sdk-method-name": "rotate" } }, "/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-12" } } } }, "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" } }, "/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-13" } } } }, "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" } }, "/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" } }, "/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" } }, "/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.organization", "x-fern-sdk-method-name": "get" }, "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" }, "disable_end_user_app_creation": { "$ref": "#/components/schemas/access_disable_end_user_app_creation" }, "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" }, "service_token_inactivity": { "$ref": "#/components/schemas/access_service_token_inactivity" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration" }, "strict_service_token_auth": { "$ref": "#/components/schemas/access_strict_service_token_auth" }, "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": { "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.organization", "x-fern-sdk-method-name": "create" }, "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" }, "disable_end_user_app_creation": { "$ref": "#/components/schemas/access_disable_end_user_app_creation" }, "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" }, "service_token_inactivity": { "$ref": "#/components/schemas/access_service_token_inactivity" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration" }, "strict_service_token_auth": { "$ref": "#/components/schemas/access_strict_service_token_auth" }, "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.organization", "x-fern-sdk-method-name": "update" } }, "/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.organization.doh", "x-fern-sdk-method-name": "get" }, "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.organization.doh", "x-fern-sdk-method-name": "update" } }, "/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.access.users", "x-fern-sdk-method-name": "revoke", "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-10" } } } }, "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" }, "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-11" } } } }, "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" } }, "/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" }, "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-11" } } } }, "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" }, "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-11" } } } }, "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" } }, "/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" } }, "/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" } }, "/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" } }, "/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-encryption-certificates", "x-fern-sdk-method-name": "list" } }, "/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-encryption-certificates", "x-fern-sdk-method-name": "get" } }, "/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-encryption-certificates", "x-fern-sdk-method-name": "get-pem" } }, "/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-encryption-certificates", "x-fern-sdk-method-name": "rotate" } }, "/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-14" } } } }, "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-4" } } } }, "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" }, "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" } }, "/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" }, "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" }, "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" } }, "/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" } }, "/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. If the service token was reported as leaked, this must not be in the future; the leaked secret is discarded immediately.", "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" } }, "/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-16" } } } }, "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" }, "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-15" } } } }, "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" } }, "/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" }, "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-15" } } } }, "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" }, "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-15" } } } }, "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" } }, "/accounts/{account_id}/access/user_populations": { "get": { "operationId": "access-user-populations-list-user-populations", "summary": "List user populations", "description": "Lists the user populations in an account.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$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 user populations response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-3" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user populations" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "access-user-populations-create-user-population", "summary": "Create a user population", "description": "Creates a user population in an account.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_user_population_request" } } } }, "responses": { "201": { "description": "Create user population response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-5" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user populations" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/access/user_populations/{user_population_id}": { "delete": { "operationId": "access-user-populations-delete-user-population", "summary": "Delete a user population", "description": "Deletes a user population that is not attached to an application.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" } ], "responses": { "202": { "description": "Delete user population response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user populations" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "access-user-populations-get-user-population", "summary": "Get a user population", "description": "Fetches a user population.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" } ], "responses": { "200": { "description": "Get user population response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-5" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user populations" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations", "x-fern-sdk-method-name": "get" }, "put": { "operationId": "access-user-populations-update-user-population", "summary": "Update a user population", "description": "Updates a user population's name.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_user_population_request" } } } }, "responses": { "200": { "description": "Update user population response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-5" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user populations" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/access/user_populations/{user_population_id}/users": { "get": { "operationId": "access-user-populations-list-users", "summary": "List users in a user population", "description": "Lists SCIM users in a user population.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" }, { "$ref": "#/components/parameters/access_filter" }, { "$ref": "#/components/parameters/access_startIndex" }, { "$ref": "#/components/parameters/access_count" }, { "$ref": "#/components/parameters/access_attributes" }, { "$ref": "#/components/parameters/access_excludedAttributes" } ], "responses": { "200": { "description": "List SCIM users response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_user_collection_response" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user population users" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations.users", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "access-user-populations-create-user", "summary": "Create a user population user", "description": "Creates a SCIM user in a user population.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_user" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/access_scim_user" } } } }, "responses": { "201": { "description": "Create SCIM user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_user_single_response" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user population users" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations.users", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/access/user_populations/{user_population_id}/users/{user_id}": { "delete": { "operationId": "access-user-populations-delete-user", "summary": "Delete a user population user", "description": "Deletes a SCIM user from a user population.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" }, { "$ref": "#/components/parameters/access_user_id" } ], "responses": { "204": { "description": "The SCIM user was deleted." }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user population users" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations.users", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "access-user-populations-get-user", "summary": "Get a user population user", "description": "Fetches a SCIM user from a user population.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" }, { "$ref": "#/components/parameters/access_user_id" }, { "$ref": "#/components/parameters/access_attributes" }, { "$ref": "#/components/parameters/access_excludedAttributes" } ], "responses": { "200": { "description": "Get SCIM user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_user_single_response" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user population users" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations.users", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "access-user-populations-update-user", "summary": "Update a user population user", "description": "Updates a SCIM user in a user population.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" }, { "$ref": "#/components/parameters/access_user_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_patch_request" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/access_scim_patch_request" } } } }, "responses": { "200": { "description": "Update SCIM user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_user_single_response" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user population users" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations.users", "x-fern-sdk-method-name": "update" }, "put": { "operationId": "access-user-populations-replace-user", "summary": "Replace a user population user", "description": "Replaces a SCIM user in a user population.", "parameters": [ { "$ref": "#/components/parameters/access_account_id" }, { "$ref": "#/components/parameters/access_user_population_id" }, { "$ref": "#/components/parameters/access_user_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_user" } }, "application/scim+json": { "schema": { "$ref": "#/components/schemas/access_scim_user" } } } }, "responses": { "200": { "description": "Replace SCIM user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_user_single_response" } } } }, "4XX": { "$ref": "#/components/responses/access_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access user population users" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.user-populations.users", "x-fern-sdk-method-name": "replace" } }, "/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-25" } } } }, "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" }, "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" } }, "/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" }, "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" }, "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" } }, "/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" } }, "/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" } }, "/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" } }, "/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" } }, "/accounts/{account_id}/access/users/{user_id}/mfa_authenticators/{authenticator_id}": { "delete": { "operationId": "zero-trust-users-delete-mfa-authenticator", "summary": "Delete a user's authenticator", "description": "Deletes a specific MFA device or passkey, including a PIV key or FIDO2 key enrollment, for a user. Admin deletion remains available when MFA is disabled. 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" } }, "/accounts/{account_id}/access/users/{user_id}/passkeys/{authenticator_id}": { "delete": { "operationId": "zero-trust-users-delete-passkey", "summary": "Delete a user's passkey", "description": "Alias of the authenticator deletion endpoint for passkey management. The identifier is the passkey's authenticator ID from the last-seen identity response. 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 passkey response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_delete_authenticator_response" } } } }, "4XX": { "description": "Delete passkey 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.passkeys", "x-fern-sdk-method-name": "delete" } }, "/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" }, "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": { "201": { "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" } }, "/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" }, "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" }, "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" } }, "/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" }, "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": { "201": { "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" } }, "/accounts/{account_id}/addressing/address_maps/{address_map_id}/ips": { "delete": { "operationId": "ip-address-management-address-maps-remove-multiple-ips-from-an-address-map", "summary": "Remove Multiple IPs from an Address Map", "description": "Remove multiple IPs from a particular address map.", "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": { "ips": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_ip_address" } } }, "required": [ "ips" ] } } } }, "responses": { "200": { "description": "Remove Multiple IPs from an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Remove Multiple IPs 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-bulk" }, "post": { "operationId": "ip-address-management-address-maps-add-multiple-ips-to-an-address-map", "summary": "Add Multiple IPs to an Address Map", "description": "Add multiple IPs to a particular address map.", "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": { "ips": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_ip_address" } } }, "required": [ "ips" ] } } } }, "responses": { "201": { "description": "Add Multiple IPs to an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Add Multiple IPs 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.ips", "x-fern-sdk-method-name": "update-bulk" } }, "/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" }, "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": { "201": { "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" } }, "/accounts/{account_id}/addressing/address_maps/{address_map_id}/zones": { "delete": { "operationId": "ip-address-management-address-maps-remove-multiple-zones-from-an-address-map", "summary": "Remove Multiple Zones from an Address Map", "description": "Remove multiple zones as members of a particular address map.", "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": { "zones": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_zone_identifier" } } }, "required": [ "zones" ] } } } }, "responses": { "200": { "description": "Remove Multiple Zones from an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Remove Multiple Zones 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-bulk" }, "post": { "operationId": "ip-address-management-address-maps-add-multiple-zones-to-an-address-map", "summary": "Add Multiple Zones to an Address Map", "description": "Add multiple zones as members of a particular address map.", "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": { "zones": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_zone_identifier" } } }, "required": [ "zones" ] } } } }, "responses": { "201": { "description": "Add Multiple Zones to an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Add Multiple Zones 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-bulk" } }, "/accounts/{account_id}/addressing/address_maps/{address_map_id}/zones/{member_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": "member_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" }, "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": "member_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": { "201": { "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" } }, "/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" } }, "/accounts/{account_id}/addressing/loa_documents": { "get": { "operationId": "ip-address-management-prefixes-list-loa-documents", "summary": "List LOA Documents", "description": "List all LOA documents uploaded under the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "List LOA Documents response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_loa_document_collection" } } } }, "4XX": { "description": "List LOA Documents response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_loa_document_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" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.loa-documents", "x-fern-sdk-method-name": "list" }, "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" } }, "/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" } }, "/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" }, "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" } }, "/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" }, "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" }, "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" } }, "/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" }, "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": { "201": { "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" } }, "/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" }, "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" }, "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" } }, "/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" }, "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" } }, "/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" }, "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" } }, "/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" }, "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" } }, "/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" }, "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": { "201": { "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" } }, "/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" } }, "/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" } }, "/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" } } }, "type": "object" } ] } } } }, "4XX": { "description": "Failure to list regions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "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" } }, "/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" } }, "/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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "credit-balance" } }, "/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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "invoice-history" } }, "/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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "invoice-preview" } }, "/accounts/{account_id}/ai-gateway/billing/spending-limit": { "delete": { "operationId": "aig-billing-delete-spending-limit", "summary": "Delete spending limit (deprecated)", "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": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.spending-limit", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "aig-billing-get-spending-limit", "summary": "Get spending limit (deprecated)", "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": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.spending-limit", "x-fern-sdk-method-name": "get" }, "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": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.spending-limit", "x-fern-sdk-method-name": "create" } }, "/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. Requires a dashboard session; API token, OAuth, and service credentials receive 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": "Top-up amount in cents (min 1000).", "type": "integer", "example": 5000, "minimum": 1000 }, "payment_method_id": { "description": "Payment method to charge instead of the customer's default payment method.", "type": "string", "example": "pm_123" } }, "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": [ "Billing Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.topup", "x-fern-sdk-method-name": "create", "x-forge-require-confirmation": "This purchases AI Gateway credits and charges the amount to the account's default payment method." } }, "/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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.topup.config", "x-fern-sdk-method-name": "delete" }, "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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.topup.config", "x-fern-sdk-method-name": "get" }, "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. Requests that add a payment method first return authentication details. The configuration is saved only after the authenticated setup is submitted. 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": { "anyOf": [ { "additionalProperties": false, "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 } }, "required": [ "threshold", "amount" ], "type": "object" }, { "additionalProperties": false, "properties": { "amount": { "description": "Auto top-up amount in cents (min 1000).", "type": "integer", "example": 5000, "minimum": 1000 }, "consent_version": { "description": "Version of the off-session auto-top-up consent accepted by the user.", "type": "string", "example": "auto-topup-v1", "maxLength": 100, "minLength": 1 }, "payment_method_id": { "description": "Card to authenticate for future automatic top-ups.", "type": "string", "example": "pm_123" }, "setup_idempotency_key": { "description": "Client-generated UUID that makes payment-method setup safe to retry.", "type": "string", "format": "uuid", "example": "f6af84c0-12d6-4c46-840d-2e4934df85e1" }, "setup_intent_id": { "description": "Successfully confirmed payment-method setup identifier.", "type": "string", "example": "seti_123" }, "threshold": { "description": "Balance threshold in cents that triggers auto top-up (min 500).", "type": "integer", "example": 500, "minimum": 500 } }, "required": [ "threshold", "amount", "payment_method_id", "setup_idempotency_key", "consent_version" ], "type": "object" } ] } } } }, "responses": { "200": { "description": "Auto top-up configuration saved, or card authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_SetTopupConfigResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "402": { "description": "Payment required — the payment method was declined during activation.", "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" } } } }, "409": { "description": "Card setup is incomplete or already used, the default payment method changed, or synchronous activation disabled auto top-up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "Billing Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.topup.config", "x-fern-sdk-method-name": "create" } }, "/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-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.topup", "x-fern-sdk-method-name": "eligibility" } }, "/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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.topup", "x-fern-sdk-method-name": "limits" } }, "/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 top-up identifier.", "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": "Top-up identifier 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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing.topup", "x-fern-sdk-method-name": "status" } }, "/accounts/{account_id}/ai-gateway/billing/usage-history": { "get": { "operationId": "aig-billing-get-usage-history", "summary": "Get usage history", "description": "Retrieve AI Gateway usage cost, in US dollars, aggregated by hour or day 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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "usage-history" } }, "/accounts/{account_id}/ai-gateway/custom-providers": { "get": { "operationId": "aig-config-list-account-provider", "summary": "List custom providers", "description": "Lists the custom providers configured for the account, ordered by position and then name.", "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": { "description": "JSON object of extra HTTP headers that AI Gateway sends to the provider. Values can contain credentials.", "type": "string", "maxLength": 8192, "x-sensitive": true }, "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 Custom 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.custom-providers", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "aig-config-create-account-provider", "summary": "Create a custom provider", "description": "Creates an account-level custom provider that forwards AI Gateway requests to the HTTPS base URL you supply. Requests reference the provider as `custom-{slug}`, so the slug must be unique within the account.", "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": { "description": "JSON object of extra HTTP headers that AI Gateway sends to the provider. Values can contain credentials.", "type": "string", "maxLength": 8192, "x-sensitive": true }, "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": { "description": "JSON object of extra HTTP headers that AI Gateway sends to the provider. Values can contain credentials.", "type": "string", "maxLength": 8192, "x-sensitive": true }, "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 Custom 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.custom-providers", "x-fern-sdk-method-name": "create", "x-forge-params": { "beta": { "hidden": true }, "curl_example": { "hidden": true }, "js_example": { "hidden": true }, "link": { "hidden": true }, "position": { "hidden": true } } } }, "/accounts/{account_id}/ai-gateway/custom-providers/costs": { "get": { "operationId": "aig-config-list-account-provider-cost", "summary": "List custom provider pricing rules", "description": "Lists the pricing rules for custom providers in the account, most recently modified first.", "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": { "description": "Only return pricing rules for this custom provider ID.", "type": "string", "format": "uuid" }, "x-fern-parameter-name": "custom-provider-id" }, { "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 Custom 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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.custom-providers.costs", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "aig-config-create-account-provider-cost", "summary": "Create a custom provider pricing rule", "description": "Creates a pricing rule that sets per-token costs for models matched on a custom provider. AI Gateway uses these rules to calculate request costs.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "account_provider_id": { "description": "ID of the custom provider that the pricing rule applies to.", "type": "string", "format": "uuid", "x-fern-property-name": "custom-provider-id" }, "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 Custom 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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.custom-providers.costs", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/ai-gateway/custom-providers/costs/{id}": { "delete": { "operationId": "aig-config-delete-account-provider-cost", "summary": "Delete a custom provider pricing rule", "description": "Deletes a custom provider pricing rule. Requests to the matched model stop using its prices.", "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 Custom 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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.custom-providers.costs", "x-fern-sdk-method-name": "delete", "x-forge-require-confirmation": "This permanently deletes the pricing rule. Cost calculations for the matched model will no longer use its prices." }, "get": { "operationId": "aig-config-fetch-account-provider-cost", "summary": "Get a custom provider pricing rule", "description": "Retrieves a custom provider pricing rule, including its model match rule and token prices.", "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 Custom 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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.custom-providers.costs", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "aig-config-update-account-provider-cost", "summary": "Update a custom provider pricing rule", "description": "Updates the specified fields of a custom provider pricing rule. Changes clear cached costs for the matched model.", "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 Custom 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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.custom-providers.costs", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/ai-gateway/custom-providers/{id}": { "delete": { "operationId": "aig-config-delete-account-provider", "summary": "Delete a custom provider", "description": "Deletes a custom provider and every pricing rule that belongs to it.", "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": { "description": "JSON object of extra HTTP headers that AI Gateway sends to the provider. Values can contain credentials.", "type": "string", "maxLength": 8192, "x-sensitive": true }, "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 Custom 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.custom-providers", "x-fern-sdk-method-name": "delete", "x-forge-require-confirmation": "This permanently deletes the custom provider and all of its pricing rules. Gateway requests that use `custom-{slug}` for this provider will stop routing." }, "get": { "operationId": "aig-config-fetch-account-provider", "summary": "Get a custom provider", "description": "Retrieves a custom provider, including its slug, base URL, and custom headers.", "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": { "description": "JSON object of extra HTTP headers that AI Gateway sends to the provider. Values can contain credentials.", "type": "string", "maxLength": 8192, "x-sensitive": true }, "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 Custom 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.custom-providers", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "aig-config-update-account-provider", "summary": "Update a custom provider", "description": "Updates the specified fields of a custom provider. Changes clear cached entries for the provider.", "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": { "description": "JSON object of extra HTTP headers that AI Gateway sends to the provider. Values can contain credentials.", "type": "string", "maxLength": 8192, "x-sensitive": true }, "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": { "description": "JSON object of extra HTTP headers that AI Gateway sends to the provider. Values can contain credentials.", "type": "string", "maxLength": 8192, "x-sensitive": true }, "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 Custom 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.custom-providers", "x-fern-sdk-method-name": "update", "x-forge-params": { "beta": { "hidden": true }, "curl_example": { "hidden": true }, "js_example": { "hidden": true }, "link": { "hidden": true }, "logo": { "hidden": true }, "position": { "hidden": true } } } }, "/accounts/{account_id}/ai-gateway/evaluation-types": { "get": { "operationId": "aig-config-list-evaluators", "summary": "List evaluator types (deprecated)", "description": "Lists the evaluator types that evaluations can use to score AI Gateway responses. Evaluations are deprecated and unavailable to new accounts.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.evaluation-types", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/ai-gateway/gateways": { "get": { "operationId": "aig-config-list-gateway", "summary": "List gateways", "description": "Lists the AI Gateways in the account. Use `search` to filter by gateway ID.", "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" } ] }, "fedramp_level": { "description": "FedRAMP compliance level: fedramp-medium or fedramp-high.", "type": "string", "enum": [ "fedramp-medium", "fedramp-high" ], "nullable": true, "x-auditable": true }, "fedramp_mode": { "description": "FedRAMP enforcement mode. \"prefer\" prioritizes compliant connectors but allows fallback. \"require\" strictly filters.", "type": "string", "enum": [ "prefer", "require" ], "nullable": true, "x-auditable": true }, "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": "Unique identifier of the AI Gateway within the account.", "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": "00000000", "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": { "description": "Secrets Store used by this gateway. Omit on update to keep the current store. Cannot be cleared while stored keys or secret references depend on it.", "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" }, "post": { "operationId": "aig-config-create-gateway", "summary": "Create a gateway", "description": "Creates an AI Gateway in the account with the specified caching, rate limiting, logging, and authentication settings. The gateway ID appears in request URLs and must be unique within the account.", "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 }, "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": "Unique identifier of the AI Gateway within the account.", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "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": "00000000", "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": { "description": "Secrets Store used by this gateway. Omit on update to keep the current store. Cannot be cleared while stored keys or secret references depend on it.", "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" ] } } } }, "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" } ] }, "fedramp_level": { "description": "FedRAMP compliance level: fedramp-medium or fedramp-high.", "type": "string", "enum": [ "fedramp-medium", "fedramp-high" ], "nullable": true, "x-auditable": true }, "fedramp_mode": { "description": "FedRAMP enforcement mode. \"prefer\" prioritizes compliant connectors but allows fallback. \"require\" strictly filters.", "type": "string", "enum": [ "prefer", "require" ], "nullable": true, "x-auditable": true }, "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": "Unique identifier of the AI Gateway within the account.", "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": "00000000", "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": { "description": "Secrets Store used by this gateway. Omit on update to keep the current store. Cannot be cleared while stored keys or secret references depend on it.", "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" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/custom-domains": { "get": { "operationId": "aig-config-list-custom-domain", "summary": "List custom domains", "description": "Lists the custom domains attached to an AI Gateway, including the certificate and validation status of each domain.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "hostname": { "description": "Custom hostname that you own, such as `ai.example.com`.", "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" }, "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": "Unique identifier of the AI Gateway within the account.", "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": "Custom hostname that you own, such as `ai.example.com`.", "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": "ID of the Cloudflare zone that contains 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" } }, "/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 a custom domain from an AI Gateway and removes its Cloudflare for SaaS custom hostname.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Custom hostname that you own, such as `ai.example.com`.", "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": "Unique identifier of the AI Gateway within the account.", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "hostname": { "description": "Custom hostname that you own, such as `ai.example.com`.", "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-require-confirmation": "This deletes the custom domain and its custom hostname. Requests to this hostname will stop reaching the gateway." }, "get": { "operationId": "aig-config-fetch-custom-domain", "summary": "Get a custom domain", "description": "Retrieves a custom domain attached to an AI Gateway, including its status and CNAME target.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Custom hostname that you own, such as `ai.example.com`.", "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": "Unique identifier of the AI Gateway within the account.", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "hostname": { "description": "Custom hostname that you own, such as `ai.example.com`.", "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" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/datasets": { "get": { "operationId": "aig-config-list-dataset", "summary": "List datasets (deprecated)", "description": "Lists the datasets defined for an AI Gateway. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "aig-config-create-dataset", "summary": "Create a dataset (deprecated)", "description": "Creates a dataset that selects gateway logs matching the specified filters for use in evaluations. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/datasets/{id}": { "delete": { "operationId": "aig-config-delete-dataset", "summary": "Delete a dataset (deprecated)", "description": "Deletes a dataset. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "aig-config-fetch-dataset", "summary": "Get a dataset (deprecated)", "description": "Retrieves a dataset and its log filters. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "get" }, "put": { "operationId": "aig-config-update-dataset", "summary": "Update a dataset (deprecated)", "description": "Replaces the name, log filters, and enabled state of a dataset. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/evaluations": { "get": { "operationId": "aig-config-list-evaluations", "summary": "List evaluations (deprecated)", "description": "Lists the evaluations run on an AI Gateway. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.evaluations", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "aig-config-create-evaluations", "summary": "Create an evaluation (deprecated)", "description": "Creates an evaluation that scores the logs in a dataset with the specified evaluator types. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.evaluations", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/evaluations/{id}": { "delete": { "operationId": "aig-config-delete-evaluations", "summary": "Delete an evaluation (deprecated)", "description": "Deletes an evaluation and its results. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.evaluations", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "aig-config-fetch-evaluations", "summary": "Get an evaluation (deprecated)", "description": "Retrieves an evaluation and its results. Evaluations and datasets are deprecated and unavailable to new accounts.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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": "deprecated", "x-fern-sdk-group-name": "ai-gateway.evaluations", "x-fern-sdk-method-name": "get" } }, "/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": "Unique identifier of the AI Gateway within the account.", "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-require-confirmation": "This permanently deletes every stored log entry on the gateway that matches the filters. Deleted logs cannot be recovered." }, "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": "Unique identifier of the AI Gateway within the account.", "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 }, "x-fern-parameter-name": "ai-gateway-provider" }, { "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" } }, "/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": "Unique identifier of the AI Gateway within the account.", "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", "nullable": true }, "request_head_complete": { "type": "boolean" }, "request_size": { "type": "integer" }, "request_type": { "type": "string" }, "response_content_type": { "type": "string" }, "response_head": { "type": "string", "nullable": true }, "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" }, "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": "Unique identifier of the AI Gateway within the account.", "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": "update" } }, "/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": "Unique identifier of the AI Gateway within the account.", "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": "get-request" } }, "/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": "Unique identifier of the AI Gateway within the account.", "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": "get-response" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/provider_configs": { "get": { "operationId": "aig-config-list-providers", "summary": "List provider keys", "description": "Lists the provider keys stored for an AI Gateway. Responses show a masked preview of each key, never the key itself.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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" }, "post": { "operationId": "aig-config-create-providers", "summary": "Store a provider key", "description": "Stores an upstream AI provider API key for an AI Gateway in the Secrets Store configured on the gateway, with an optional rate limit. Pass `secret` to store a new key, or omit it to use an existing Secrets Store secret.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": { "description": "Provider API key to store in the Secrets Store configured on the gateway.", "type": "string", "x-sensitive": true }, "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": "Unique identifier of the AI Gateway within the account.", "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" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/provider_configs/{id}": { "delete": { "operationId": "aig-config-delete-providers", "summary": "Delete a provider key", "description": "Deletes a provider key configuration from an AI Gateway and deletes its secret from the Secrets Store.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": "Unique identifier of the AI Gateway within the account.", "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-require-confirmation": "This deletes the stored provider key and its Secrets Store secret. Requests that rely on this key will stop authenticating with it." }, "get": { "operationId": "aig-config-fetch-providers", "summary": "Get a provider key", "description": "Retrieves a provider key configuration for an AI Gateway. The response shows a masked preview of the key, never the key itself.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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 a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "alias": { "type": "string" }, "default_config": { "type": "boolean" }, "gateway_id": { "description": "Unique identifier of the AI Gateway within the account.", "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-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": "get" }, "put": { "operationId": "aig-config-update-providers", "summary": "Rotate a provider key", "description": "Replaces the stored API key of a provider key configuration. Only the key can change.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "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": { "description": "Provider API key to store in the Secrets Store configured on the gateway.", "type": "string", "x-sensitive": true } }, "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": "Unique identifier of the AI Gateway within the account.", "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" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes": { "get": { "operationId": "aig-config-list-gateway-dynamic-routes", "summary": "List dynamic routes", "description": "Lists the dynamic routes configured on an AI Gateway.", "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "aig-config-post-gateway-dynamic-route", "summary": "Create a dynamic route", "description": "Creates a dynamic route on an AI Gateway from the specified routing elements. Clients call the route by using `dynamic/{name}` as the model name.", "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}": { "delete": { "operationId": "aig-config-delete-gateway-dynamic-route", "summary": "Delete a dynamic route", "description": "Deletes a dynamic route from an AI Gateway.", "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "aig-config-get-gateway-dynamic-route", "summary": "Get a dynamic route", "description": "Retrieves a dynamic route with its routing elements, active version, and current 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" } } ], "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "aig-config-update-gateway-dynamic-route", "summary": "Rename a dynamic route", "description": "Updates the name of a dynamic route. To change routing behaviour, create and deploy a new 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": { "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/deployments": { "get": { "operationId": "aig-config-list-gateway-dynamic-route-deployments", "summary": "List dynamic route deployments", "description": "Lists the deployment history of a 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": { "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing.deployments", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "aig-config-post-gateway-dynamic-route-deployment", "summary": "Deploy a dynamic route version", "description": "Deploys the specified version of a dynamic route so that it serves traffic. Deploy an earlier version to roll back.", "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing.deployments", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/versions": { "get": { "operationId": "aig-config-list-gateway-dynamic-route-versions", "summary": "List dynamic route versions", "description": "Lists the saved versions of a 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": { "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing.versions", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "aig-config-post-gateway-dynamic-route-version", "summary": "Create a dynamic route version", "description": "Creates a new version of a dynamic route from the specified routing elements. The version does not serve traffic until you deploy it.", "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing.versions", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/versions/{version_id}": { "get": { "operationId": "aig-config-get-gateway-dynamic-route-version", "summary": "Get a dynamic route version", "description": "Retrieves a saved version of a dynamic route, including its routing elements.", "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": "beta", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing.versions", "x-fern-sdk-method-name": "get" } }, "/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": "Unique identifier of the AI Gateway within the account.", "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" }, "x-fern-parameter-name": "ai-gateway-provider" } ], "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": "beta", "x-fern-sdk-group-name": "ai-gateway.gateways", "x-fern-sdk-method-name": "get-url" } }, "/accounts/{account_id}/ai-gateway/gateways/{id}": { "delete": { "operationId": "aig-config-delete-gateway", "summary": "Delete a gateway", "description": "Permanently deletes an AI Gateway, its configuration, and its stored logs.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "x-fern-parameter-name": "gateway-id" } ], "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" } ] }, "fedramp_level": { "description": "FedRAMP compliance level: fedramp-medium or fedramp-high.", "type": "string", "enum": [ "fedramp-medium", "fedramp-high" ], "nullable": true, "x-auditable": true }, "fedramp_mode": { "description": "FedRAMP enforcement mode. \"prefer\" prioritizes compliant connectors but allows fallback. \"require\" strictly filters.", "type": "string", "enum": [ "prefer", "require" ], "nullable": true, "x-auditable": true }, "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": "Unique identifier of the AI Gateway within the account.", "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": "00000000", "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": { "description": "Secrets Store used by this gateway. Omit on update to keep the current store. Cannot be cleared while stored keys or secret references depend on it.", "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-require-confirmation": "This permanently deletes the gateway, its configuration, and its stored logs. Requests sent to this gateway will fail. This action cannot be undone." }, "get": { "operationId": "aig-config-fetch-gateway", "summary": "Get a gateway", "description": "Retrieves the configuration of an AI Gateway.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "x-fern-parameter-name": "gateway-id" } ], "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" } ] }, "fedramp_level": { "description": "FedRAMP compliance level: fedramp-medium or fedramp-high.", "type": "string", "enum": [ "fedramp-medium", "fedramp-high" ], "nullable": true, "x-auditable": true }, "fedramp_mode": { "description": "FedRAMP enforcement mode. \"prefer\" prioritizes compliant connectors but allows fallback. \"require\" strictly filters.", "type": "string", "enum": [ "prefer", "require" ], "nullable": true, "x-auditable": true }, "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": "Unique identifier of the AI Gateway within the account.", "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": "00000000", "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": { "description": "Secrets Store used by this gateway. Omit on update to keep the current store. Cannot be cleared while stored keys or secret references depend on it.", "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" }, "put": { "operationId": "aig-config-update-gateway", "summary": "Update a gateway", "description": "Updates the configuration of an AI Gateway, such as its caching, rate limiting, logging, and authentication settings.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier of the AI Gateway within the account.", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "x-fern-parameter-name": "gateway-id" } ], "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": "00000000", "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": { "description": "Secrets Store used by this gateway. Omit on update to keep the current store. Cannot be cleared while stored keys or secret references depend on it.", "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" } ] }, "fedramp_level": { "description": "FedRAMP compliance level: fedramp-medium or fedramp-high.", "type": "string", "enum": [ "fedramp-medium", "fedramp-high" ], "nullable": true, "x-auditable": true }, "fedramp_mode": { "description": "FedRAMP enforcement mode. \"prefer\" prioritizes compliant connectors but allows fallback. \"require\" strictly filters.", "type": "string", "enum": [ "prefer", "require" ], "nullable": true, "x-auditable": true }, "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": "Unique identifier of the AI Gateway within the account.", "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": "00000000", "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": { "description": "Secrets Store used by this gateway. Omit on update to keep the current store. Cannot be cleared while stored keys or secret references depend on it.", "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" } }, "/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-ignore": 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-ignore": true, "x-fern-sdk-group-name": "ai-gateway.logging-state", "x-fern-sdk-method-name": "update", "x-forge-require-confirmation": "This irreversibly migrates AI Gateway logging for the entire account from Legacy Logs to Workers Observability. You cannot switch the account back to Legacy Logs." } }, "/accounts/{account_id}/ai-search/instances": { "get": { "operationId": "ai-search-list-instances", "summary": "List AI Search instances.", "description": "Lists all AI Search instances in the account.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{namespace}/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": "hostname", "in": "query", "description": "Return only instances with this exact Search for Agents hostname (case-insensitive).", "schema": { "description": "Return only instances with this exact Search for Agents hostname (case-insensitive).", "type": "string", "maxLength": 253, "minLength": 1 } }, { "name": "namespace", "in": "query", "description": "Return only instances in this namespace.", "schema": { "description": "Return only instances in this 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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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 have a maximum of 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. If type is omitted or null, a non-blank HTTP(S) source infers web-crawler and any other source infers r2; r2 sources must name an existing bucket. A missing or blank source without a type creates a managed upload-only instance.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{namespace}/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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "enable": { "type": "boolean", "x-auditable": true }, "engine_version": { "type": "number", "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "status": { "type": "string", "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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" ] } } } }, "409": { "description": "Search for agents hostname used by another namespace; Search for agents requires default namespace; Ai search instance deletion in progress.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7106 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7109 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7124 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Ai search temporarily unavailable.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "1" } } }, "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": "Deletes an AI Search instance and all its indexed data permanently.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{namespace}/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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "enable": { "type": "boolean", "x-auditable": true }, "engine_version": { "type": "number", "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "status": { "type": "string", "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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/{namespace}/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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "enable": { "type": "boolean", "x-auditable": true }, "engine_version": { "type": "number", "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "status": { "type": "string", "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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": "Updates the configuration of an AI Search instance.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{namespace}/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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "index_method": { "description": "Controls which storage backends indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "paused": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } } } } } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "enable": { "type": "boolean", "x-auditable": true }, "engine_version": { "type": "number", "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "status": { "type": "string", "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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" ] } } } }, "503": { "description": "Ai search temporarily unavailable.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "1" } } }, "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/{namespace}/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 this operation triggers. Accepts up to 2 string, number, or boolean entries. Reserved keys: 'ai-search', 'task', 'origin', and any key beginning with 'cf.'.", "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to 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": { "description": "Minimum similarity score a chunk must reach to be returned. When omitted, falls back to the instance-level score_threshold, then to 0.4.", "type": "number", "maximum": 1, "minimum": 0 }, "max_num_results": { "description": "Maximum number of results to return. When omitted, falls back to the instance-level max_num_results, then to 10.", "type": "integer", "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" ] }, "media_end_ms": { "description": "Audio/video transcript chunks only: end, in milliseconds from the start of the media (whole seconds), of the last transcript section the matched chunk covers. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "media_start_ms": { "description": "Audio/video transcript chunks only: start, in milliseconds from the start of the media (whole seconds), of the transcript section the matched chunk begins in. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "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 } } }, "source_media_type": { "description": "Audio/video transcript chunks only: type of the source media file. Omitted for all other chunks.", "type": "string", "enum": [ "audio", "video" ] }, "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" ] } } } }, "402": { "description": "Workers ai unified billing required.", "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" ] } } } }, "429": { "description": "Monthly query quota exceeded; Workers ai capacity temporarily exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7069 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7119 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "502": { "description": "Ai gateway exception; Workers ai upstream error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7033 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7120 ] }, "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/{namespace}/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/{namespace}/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; Ai search temporarily unavailable.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7017 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7125 ] }, "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/{namespace}/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": "Cancels an in-progress indexing job for an AI Search instance.\n\nDeprecated: use /accounts/{account_id}/ai-search/namespaces/{namespace}/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/{namespace}/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/{namespace}/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 this operation triggers. Accepts up to 2 string, number, or boolean entries. Reserved keys: 'ai-search', 'task', 'origin', and any key beginning with 'cf.'.", "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to 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": { "description": "Minimum similarity score a chunk must reach to be returned. When omitted, falls back to the instance-level score_threshold, then to 0.4.", "type": "number", "maximum": 1, "minimum": 0 }, "max_num_results": { "description": "Maximum number of results to return. When omitted, falls back to the instance-level max_num_results, then to 10.", "type": "integer", "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" ] }, "media_end_ms": { "description": "Audio/video transcript chunks only: end, in milliseconds from the start of the media (whole seconds), of the last transcript section the matched chunk covers. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "media_start_ms": { "description": "Audio/video transcript chunks only: start, in milliseconds from the start of the media (whole seconds), of the transcript section the matched chunk begins in. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "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 } } }, "source_media_type": { "description": "Audio/video transcript chunks only: type of the source media file. Omitted for all other chunks.", "type": "string", "enum": [ "audio", "video" ] }, "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" ] } } } }, "429": { "description": "Monthly query quota exceeded; Workers ai capacity temporarily exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7069 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7119 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "502": { "description": "Ai gateway exception; Workers ai upstream error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7033 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7120 ] }, "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/{namespace}/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 the API cannot compute status counts (e.g. the legacy stats query exceeded the D1 statement-size limit). The response omits counts 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": "Lists 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 belong to 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 reference an existing instance in this namespace, and the list must stay within 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])?$", "x-fern-property-name": "namespace" }, "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 belong to 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 reference an existing instance in this namespace, and the list must stay within 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 belong to 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 reference an existing instance in this namespace, and the list must stay within 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.", "positional": true } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/instances": { "get": { "operationId": "ai-search-namespace-list-instances", "summary": "List AI Search instances.", "description": "Lists all AI Search instances in the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" }, { "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": "hostname", "in": "query", "description": "Return only instances with this exact Search for Agents hostname (case-insensitive).", "schema": { "description": "Return only instances with this exact Search for Agents hostname (case-insensitive).", "type": "string", "maxLength": 253, "minLength": 1 } }, { "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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 have a maximum of 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": { "namespace": { "default": "default", "description": "Namespace to use for this operation." } } }, "post": { "operationId": "ai-search-namespace-create-instance", "summary": "Create an AI Search instance.", "description": "Create a new AI Search instance with the given configuration. If type is omitted or null, a non-blank HTTP(S) source infers web-crawler and any other source infers r2; r2 sources must name an existing bucket. A missing or blank source without a type creates a managed upload-only instance.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "enable": { "type": "boolean", "x-auditable": true }, "engine_version": { "type": "number", "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "status": { "type": "string", "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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" ] } } } }, "409": { "description": "Search for agents hostname used by another namespace; Search for agents requires default namespace; Ai search instance deletion in progress.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7106 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7109 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7124 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Ai search temporarily unavailable.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "1" } } }, "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 }, "namespace": { "default": "default", "description": "Namespace to use for this operation." }, "source": { "description": "R2 bucket name or HTTP(S) root website URL to index. When type is omitted, the source determines it." }, "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/{namespace}/instances/{id}": { "delete": { "operationId": "ai-search-namespace-delete-instance", "summary": "Delete an AI Search instance.", "description": "Deletes an AI Search instance and all its indexed data permanently.", "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" }, "x-fern-parameter-name": "instance-id" }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "enable": { "type": "boolean", "x-auditable": true }, "engine_version": { "type": "number", "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "status": { "type": "string", "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } }, "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" }, "x-fern-parameter-name": "instance-id" }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "enable": { "type": "boolean", "x-auditable": true }, "engine_version": { "type": "number", "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "status": { "type": "string", "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } }, "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": "namespace", "in": "path", "description": "Current namespace of the instance.", "required": true, "schema": { "description": "Current namespace of the instance.", "type": "string", "example": "production" }, "x-fern-parameter-name": "source-namespace" }, { "name": "id", "in": "path", "description": "Instance id.", "required": true, "schema": { "description": "Instance id.", "type": "string", "example": "my-blog" }, "x-fern-parameter-name": "instance-id" } ], "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])?$", "x-fern-property-name": "destination-namespace" } }, "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" ] } } } }, "409": { "description": "Instance modified concurrently please retry move; Ai search instance deletion in progress.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7108 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7124 ] }, "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." }, "namespace": { "default": "default", "description": "Namespace currently containing the instance." }, "new_namespace": { "description": "Namespace to move the instance into." } } }, "put": { "operationId": "ai-search-namespace-update-instance", "summary": "Update an AI Search instance.", "description": "Updates 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" }, "x-fern-parameter-name": "instance-id" }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "index_method": { "description": "Controls which storage backends indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "paused": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" } } } } } }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "enable": { "type": "boolean", "x-auditable": true }, "engine_version": { "type": "number", "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead. Defaults to true for new instances; set false to create a vector-only instance.", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 indexing uses. Defaults to vector and keyword indexing for new instances. When set, both vector and keyword are required.", "type": "object", "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean", "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "vector", "keyword" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "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" }, "created_from_emdash_plugin": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "native", "rest" ] }, "version": { "type": "string" } }, "required": [ "type", "version" ] }, "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", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 belong to a Verified zone on this account.", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 } }, "x-stainless-terraform-configurability": "computed_optional" }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } }, "x-stainless-terraform-configurability": "computed_optional" }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint.", "type": "boolean", "default": false } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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" ], "x-stainless-terraform-configurability": "computed_optional" }, "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to BM25 relevance. When omitted on an update, the existing stored value stays unchanged; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ], "x-stainless-terraform-configurability": "computed_optional" } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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, "x-stainless-terraform-configurability": "computed_optional" }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "description": "Minimum similarity score a chunk must reach to be returned. Defaults to 0.4.", "type": "number", "maximum": 1, "minimum": 0, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "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 have a limit of 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 have a limit of 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 through 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` because discover crawls only cover 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. The crawler stores and indexes only the matched HTML fragment. Omit the field to disable content selection; the API rejects empty arrays.", "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. Disallowed characters: ;, `, $, {, }, \\. Must target a single element; if multiple elements match, the crawler ignores the selector and uses the full page.", "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 use RFC-7230 token characters, excluding spaces, colons, and control characters. Values must use HTAB and printable ASCII only, excluding CR and 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 the crawler finds URLs. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to belong to a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "status": { "type": "string", "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). Defaults to 21600 (6h); instances crawling a domain outside the account may be set to 86400.", "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, "x-stainless-terraform-configurability": "computed_optional" }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "Source type. When omitted or null with a non-blank source, HTTP(S) URLs infer web-crawler and existing R2 bucket names infer r2. A missing or blank source without a type uses managed upload-only storage.", "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "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" ] } } } }, "503": { "description": "Ai search temporarily unavailable.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "1" } } }, "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." }, "source": { "description": "R2 bucket name or HTTP(S) root website URL to index." }, "source_params": { "description": "Optional data source settings as a JSON object." } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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 this operation triggers. Accepts up to 2 string, number, or boolean entries. Reserved keys: 'ai-search', 'task', 'origin', and any key beginning with 'cf.'.", "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to 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": { "description": "Minimum similarity score a chunk must reach to be returned. When omitted, falls back to the instance-level score_threshold, then to 0.4.", "type": "number", "maximum": 1, "minimum": 0 }, "max_num_results": { "description": "Maximum number of results to return. When omitted, falls back to the instance-level max_num_results, then to 10.", "type": "integer", "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" ] }, "media_end_ms": { "description": "Audio/video transcript chunks only: end, in milliseconds from the start of the media (whole seconds), of the last transcript section the matched chunk covers. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "media_start_ms": { "description": "Audio/video transcript chunks only: start, in milliseconds from the start of the media (whole seconds), of the transcript section the matched chunk begins in. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "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 } } }, "source_media_type": { "description": "Audio/video transcript chunks only: type of the source media file. Omitted for all other chunks.", "type": "string", "enum": [ "audio", "video" ] }, "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" ] } } } }, "402": { "description": "Workers ai unified billing required.", "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" ] } } } }, "429": { "description": "Monthly query quota exceeded; Workers ai capacity temporarily exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7069 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7119 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "502": { "description": "Ai gateway exception; Workers ai upstream error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7033 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7120 ] }, "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" }, { "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 items according to status priority, then last_seen_at. \"modified_at\" sorts items according to file modification time (most recent first), falling back to created_at.", "schema": { "description": "Sort order for items. \"status\" (default) sorts items according to status priority, then last_seen_at. \"modified_at\" sorts items according to 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": "Return only items with this source_id. Use \"builtin\" for uploaded files, or a source identifier like \"web-crawler:https://example.com\".", "schema": { "description": "Return only items with this 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": "Return only the item with this unique ID. Returns at most one item.", "schema": { "description": "Return only the item with this unique ID. Returns at most one item.", "type": "string", "maxLength": 64 } }, { "name": "key", "in": "query", "description": "Return only items with this exact key (object key / filename). Each key is unique within a source, so combine with `source` to disambiguate across data sources.", "schema": { "description": "Return only items with this exact key (object key / filename). Each key is unique within a source, so combine with `source` to disambiguate across data sources.", "type": "string", "maxLength": 1024 } } ], "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } }, "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 }, "x-fern-parameter-name": "instance-id" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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 before responding. After processing, vector-indexed instances use any time remaining in a 25s wait budget to confirm Vectorize ingestion. Processing itself continues uninterrupted and can exceed that budget. If confirmation times out, the response returns the current item state and background indexing continues. 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": "This operation requires a managed instance; Ai search is paused; File field is required; Filename exceeds maximum length; Unsupported file type; Invalid metadata format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7053 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7032 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7055 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7072 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7060 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7056 ] }, "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; Ai search managed resources unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7042 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7123 ] }, "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; Monthly ingestion quota exceeded; Monthly storage quota exceeded; Ai search instance overloaded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7095 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7116 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7112 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7114 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "499": { "description": "Client disconnected during upload.", "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } }, "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 }, "x-fern-parameter-name": "instance-id" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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 before responding. After processing, vector-indexed instances use any time remaining in a 25s wait budget to confirm Vectorize ingestion. Processing itself continues uninterrupted and can exceed that budget. If confirmation times out, the response returns the current item state and background indexing continues. 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" ] } } } }, "429": { "description": "Monthly ingestion quota exceeded; Monthly storage quota exceeded; Ai search instance overloaded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7116 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7112 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7114 ] }, "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." }, "next_action": { "default": "INDEX", "hidden": true } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 removes its indexed 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 }, "x-fern-parameter-name": "instance-id" }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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; Ai search is paused.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7053 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7032 ] }, "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" ] } } } }, "409": { "description": "Ai search managed resources unavailable.", "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": "AI Search instance overloaded. A retried DELETE may return 404 if the earlier attempt completed; treat that as deleted.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "1" } } }, "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." }, "item_id": { "description": "Indexed item ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } }, "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 }, "x-fern-parameter-name": "instance-id" }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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." }, "item_id": { "description": "Indexed item ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } }, "patch": { "operationId": "ai-search-namespace-instance-sync-item", "summary": "Sync Item.", "description": "Synchronizes 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 }, "x-fern-parameter-name": "instance-id" }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "next_action": { "type": "string", "enum": [ "INDEX" ] }, "wait_for_completion": { "description": "Wait for indexing before responding. After processing, vector-indexed instances use any time remaining in a 25s wait budget to confirm Vectorize ingestion. Processing itself continues uninterrupted and can exceed that budget. If confirmation times out, the response returns the current item state and background indexing continues. 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" ] } } } }, "429": { "description": "Monthly ingestion quota exceeded; Monthly storage quota exceeded; Ai search instance overloaded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7116 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7112 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7114 ] }, "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." }, "item_id": { "description": "Indexed item ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." }, "next_action": { "default": "INDEX", "hidden": true } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "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" ] }, "media_end_ms": { "description": "Audio/video transcript chunks only: end, in milliseconds from the start of the media (whole seconds), of the last transcript section the chunk covers.", "type": "integer", "minimum": 0 }, "media_start_ms": { "description": "Audio/video transcript chunks only: start, in milliseconds from the start of the media (whole seconds), of the transcript section the chunk begins in.", "type": "integer", "minimum": 0 }, "source_media_type": { "description": "Audio/video transcript chunks only: type of the source media file. Omitted for all other chunks.", "type": "string", "enum": [ "audio", "video" ] }, "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." }, "item_id": { "description": "Indexed item ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Raw file content.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "This operation requires a managed instance; Content download not available for external source items; Ai search is paused.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7053 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7059 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7032 ] }, "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" ] } } } }, "409": { "description": "Ai search managed resources unavailable.", "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." }, "item_id": { "description": "Indexed item ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 512 } } ], "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." }, "item_id": { "description": "Indexed item ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 0 } } ], "responses": { "200": { "description": "Returns a list of AI Search Jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "list", "x-forge-params": { "id": { "description": "AI Search instance ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } }, "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 }, "x-fern-parameter-name": "instance-id" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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; Ai search temporarily unavailable.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7017 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7125 ] }, "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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." }, "job_id": { "description": "Indexing job ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } }, "patch": { "operationId": "ai-search-namespace-instance-change-job-status", "summary": "Cancel an indexing job.", "description": "Cancels 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 }, "x-fern-parameter-name": "instance-id" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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." }, "job_id": { "description": "Indexing job ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } }, "x-forge-require-confirmation": "This operation cancels the running indexing job." } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "example": "my-namespace" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 500, "minimum": 0 } } ], "responses": { "200": { "description": "Returns a list of AI Search Job Logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "number" }, "id": { "type": "integer" }, "message": { "type": "string" }, "message_type": { "type": "integer" } }, "required": [ "id", "message", "message_type", "created_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "logs", "x-forge-params": { "id": { "description": "AI Search instance ID." }, "job_id": { "description": "Indexing job ID." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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" ] } } } }, "503": { "description": "Ai search temporarily unavailable.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "1" } } }, "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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 this operation triggers. Accepts up to 2 string, number, or boolean entries. Reserved keys: 'ai-search', 'task', 'origin', and any key beginning with 'cf.'.", "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to 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": { "description": "Minimum similarity score a chunk must reach to be returned. When omitted, falls back to the instance-level score_threshold, then to 0.4.", "type": "number", "maximum": 1, "minimum": 0 }, "max_num_results": { "description": "Maximum number of results to return. When omitted, falls back to the instance-level max_num_results, then to 10.", "type": "integer", "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" ] }, "media_end_ms": { "description": "Audio/video transcript chunks only: end, in milliseconds from the start of the media (whole seconds), of the last transcript section the matched chunk covers. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "media_start_ms": { "description": "Audio/video transcript chunks only: start, in milliseconds from the start of the media (whole seconds), of the transcript section the matched chunk begins in. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "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 } } }, "source_media_type": { "description": "Audio/video transcript chunks only: type of the source media file. Omitted for all other chunks.", "type": "string", "enum": [ "audio", "video" ] }, "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" ] } } } }, "429": { "description": "Monthly query quota exceeded; Workers ai capacity temporarily exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7069 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7119 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "502": { "description": "Ai gateway exception; Workers ai upstream error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7033 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7120 ] }, "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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." }, "query": { "description": "Text to search for.", "positional": true } } } }, "/accounts/{account_id}/ai-search/namespaces/{namespace}/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 }, "x-fern-parameter-name": "instance-id" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "namespace", "in": "path", "description": "Namespace name.", "required": true, "schema": { "type": "string", "default": "default", "x-stainless-terraform-configurability": "computed_optional" }, "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 the API cannot compute status counts (e.g. the legacy stats query exceeded the D1 statement-size limit). The response omits counts 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." }, "namespace": { "default": "default", "description": "Namespace to use for this operation." } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}": { "delete": { "operationId": "ai-search-delete-namespace", "summary": "Delete a namespace", "description": "Deletes a namespace permanently. The namespace must not contain any instances (instances whose deletion is still in progress do not count), 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" }, "x-fern-parameter-name": "namespace" } ], "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" ] } } } }, "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": "delete", "x-forge-params": { "name": { "description": "Namespace to delete." } }, "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" }, "x-fern-parameter-name": "namespace" } ], "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 belong to 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 reference an existing instance in this namespace, and the list must stay within 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." } } }, "put": { "operationId": "ai-search-update-namespace", "summary": "Update a namespace", "description": "Updates 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" }, "x-fern-parameter-name": "namespace" } ], "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 belong to 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 reference an existing instance in this namespace, and the list must stay within 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 belong to 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 reference an existing instance in this namespace, and the list must stay within 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." } } } }, "/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", "x-fern-parameter-name": "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 this operation triggers. Accepts up to 2 string, number, or boolean entries. Reserved keys: 'ai-search', 'task', 'origin', and any key beginning with 'cf.'.", "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to 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": { "description": "Minimum score a chunk must reach to be returned. When omitted, each instance's chunks are filtered by that instance's score_threshold, capped at the lower of the first instance's score_threshold and 0.4.", "type": "number", "maximum": 1, "minimum": 0 }, "max_num_results": { "description": "Maximum number of merged results to return. When omitted, defaults to the first instance's max_num_results, then 10.", "type": "integer", "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" ] }, "media_end_ms": { "description": "Audio/video transcript chunks only: end, in milliseconds from the start of the media (whole seconds), of the last transcript section the matched chunk covers. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "media_start_ms": { "description": "Audio/video transcript chunks only: start, in milliseconds from the start of the media (whole seconds), of the transcript section the matched chunk begins in. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "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 } } }, "source_media_type": { "description": "Audio/video transcript chunks only: type of the source media file. Omitted for all other chunks.", "type": "string", "enum": [ "audio", "video" ] }, "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" ] } } } }, "402": { "description": "Workers ai unified billing required.", "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" ] } } } }, "429": { "description": "Monthly query quota exceeded; Workers ai capacity temporarily exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7069 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7119 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "502": { "description": "Ai gateway exception; Workers ai upstream error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7033 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7120 ] }, "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." } } } }, "/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", "x-fern-parameter-name": "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 this operation triggers. Accepts up to 2 string, number, or boolean entries. Reserved keys: 'ai-search', 'task', 'origin', and any key beginning with 'cf.'.", "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 become candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term and ranks results according to 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": { "description": "Minimum score a chunk must reach to be returned. When omitted, each instance's chunks are filtered by that instance's score_threshold, capped at 0.4.", "type": "number", "maximum": 1, "minimum": 0 }, "max_num_results": { "description": "Maximum number of merged results to return. When omitted, defaults to the sum of the searched instances' max_num_results (each falling back to 10), up to 50.", "type": "integer", "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" ] }, "media_end_ms": { "description": "Audio/video transcript chunks only: end, in milliseconds from the start of the media (whole seconds), of the last transcript section the matched chunk covers. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "media_start_ms": { "description": "Audio/video transcript chunks only: start, in milliseconds from the start of the media (whole seconds), of the transcript section the matched chunk begins in. Describes the matched chunk before any context expansion, not the expanded `text`.", "type": "integer", "minimum": 0 }, "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 } } }, "source_media_type": { "description": "Audio/video transcript chunks only: type of the source media file. Omitted for all other chunks.", "type": "string", "enum": [ "audio", "video" ] }, "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" ] } } } }, "429": { "description": "Monthly query quota exceeded; Workers ai capacity temporarily exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "description": "Seconds to wait before retrying.", "type": "string", "example": "10" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7069 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7119 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } ] } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "502": { "description": "Ai gateway exception; Workers ai upstream error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "anyOf": [ { "properties": { "code": { "type": "number", "enum": [ 7033 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, { "properties": { "code": { "type": "number", "enum": [ 7120 ] }, "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." }, "query": { "description": "Text to search for.", "positional": true } } } }, "/accounts/{account_id}/ai-search/tokens": { "get": { "operationId": "ai-search-list-tokens", "summary": "List tokens", "description": "Lists 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", "x-fern-property-name": "api-token-id" }, "cf_api_key": { "type": "string", "example": "abc123", "writeOnly": true, "x-fern-property-name": "api-token", "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." }, "cf_api_key": { "description": "Cloudflare API token value." }, "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": "Deletes a stored AI Search credential permanently. 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" }, "x-fern-parameter-name": "token-id" } ], "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." } }, "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" }, "x-fern-parameter-name": "token-id" } ], "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." } } }, "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" }, "x-fern-parameter-name": "token-id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cf_api_id": { "type": "string", "example": "a1b2c3d4e5f6", "x-fern-property-name": "api-token-id" }, "cf_api_key": { "type": "string", "example": "abc123", "writeOnly": true, "x-fern-property-name": "api-token", "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." }, "cf_api_key": { "description": "Cloudflare API token value." }, "id": { "description": "Stored credential record 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 an AI model's input and output schemas", "description": "Retrieves the input and output JSON Schema definitions for an AI model. Use these definitions to determine the model-specific request fields and response format.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID used for this AI model request.", "required": true, "schema": { "description": "Cloudflare account ID used for this AI model request.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "model", "in": "query", "description": "AI model identifier, including its namespace and model name.", "required": true, "schema": { "description": "AI model identifier, including its namespace and model name.", "type": "string", "example": "@cf/meta/llama-3.1-8b-instruct" } } ], "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": "Run an AI model with request options", "description": "Runs an AI model using a JSON body containing model, input, and optional options fields. Unlike the model-specific URL endpoint, this endpoint takes the model identifier in the body and nests the model's inputs under input.\n\nUse options.extraHeaders to pass additional provider headers. Accepts Workers AI model identifiers and AI Gateway provider model identifiers.\n\nSee the [Workers AI model catalog](https://developers.cloudflare.com/workers-ai/models/) for Workers AI model inputs, or the provider's documentation for models accessed through AI Gateway.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "description": "Cloudflare account ID used for this AI model request.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "JSON object containing the selected model's input fields, such as prompt or messages. Do not include model or options inside this object.", "type": "object", "example": { "prompt": "Tell me a joke" } }, "model": { "description": "The AI model to execute (e.g., @cf/google/gemma-4-26b-a4b-it, 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" } }, "/accounts/{account_id}/ai/run/{model_name}": { "post": { "operationId": "workers-ai-post-run-model", "summary": "Run a Workers AI model", "description": "Runs the Workers AI model specified in the URL path. Send the model's inputs directly in the request body, without a model/input/options wrapper.\n\nAccepts model-specific JSON or binary input. The response format depends on the model and the requested output.\n\nSee the [model catalog](https://developers.cloudflare.com/workers-ai/models/) for supported models and their input formats.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID used for this AI model request.", "required": true, "schema": { "description": "Cloudflare account ID used for this AI model request.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "model_name", "in": "path", "description": "Workers AI model identifier, including its namespace and model name.", "required": true, "schema": { "description": "Workers AI model identifier, including its namespace and model name.", "type": "string", "example": "@cf/meta/llama-3.1-8b-instruct" } } ], "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-audiences": [ "sdk" ], "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 uploaded files to Markdown", "description": "Converts files uploaded as multipart form data into Markdown using Workers AI. Returns a conversion result for each file. Use the supported-formats endpoint to check accepted file types.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "description": "Cloudflare account ID used for this AI model request.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "description": "Files to convert, supplied as multipart file uploads.", "type": "array", "items": { "format": "binary", "type": "string" } } }, "required": [ "files" ] } } } }, "responses": { "200": { "description": "Conversion results for the uploaded files", "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": "List supported Markdown conversion formats", "description": "Lists the file extensions and MIME types accepted by Workers AI's Markdown conversion endpoint. Use this list to check whether a file can be converted before uploading it.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "description": "Cloudflare account ID used for this AI model request.", "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": "list-markdown-supported-formats" } }, "/accounts/{account_id}/ai/websearch": { "post": { "operationId": "workers-ai-ai-gateway-web-search", "summary": "Search the web through AI Gateway", "description": "Run a web search through a configured AI Gateway.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "byokAlias": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "limit": { "type": "integer", "maximum": 10, "minimum": 1 }, "options": { "type": "object", "properties": { "gateway": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ] } }, "required": [ "gateway" ] }, "provider": { "type": "string", "maxLength": 1024, "minLength": 1 }, "query": { "minLength": 1, "type": "string" } }, "additionalProperties": false, "required": [ "query", "options" ] } } } }, "responses": { "200": { "description": "Web search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "properties": { "description": { "type": "string" }, "faviconUrl": { "type": "string", "format": "uri" }, "imageUrl": { "type": "string", "format": "uri" }, "lastModifiedDate": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "url", "title" ], "type": "object" } }, "metadata": { "type": "object", "properties": { "latencyMs": { "type": "number" }, "query": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "query", "requestId", "latencyMs" ] } }, "required": [ "items", "metadata" ] } } } }, "400": { "description": "Invalid request or gateway configuration", "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "nullable": true } }, "result": { "anyOf": [ { "nullable": true }, { "type": "object" }, { "nullable": true } ] }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ], "type": "object" }, { "properties": { "error": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "gateway", "credential", "provider", "internal" ] }, "code": { "type": "string" }, "gatewayRequestId": { "type": "string" }, "retryable": { "type": "boolean" }, "status": { "type": "integer" } }, "required": [ "category", "code", "status", "retryable", "gatewayRequestId" ] }, "ok": { "type": "boolean", "enum": [ false ] } }, "required": [ "ok", "error" ], "type": "object" } ] } } } }, "403": { "description": "Web search is not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "gateway", "credential", "provider", "internal" ] }, "code": { "type": "string" }, "gatewayRequestId": { "type": "string" }, "retryable": { "type": "boolean" }, "status": { "type": "integer" } }, "required": [ "category", "code", "status", "retryable", "gatewayRequestId" ] }, "ok": { "type": "boolean", "enum": [ false ] } }, "required": [ "ok", "error" ] } } } }, "502": { "description": "Web search provider failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "gateway", "credential", "provider", "internal" ] }, "code": { "type": "string" }, "gatewayRequestId": { "type": "string" }, "retryable": { "type": "boolean" }, "status": { "type": "integer" } }, "required": [ "category", "code", "status", "retryable", "gatewayRequestId" ] }, "ok": { "type": "boolean", "enum": [ false ] } }, "required": [ "ok", "error" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "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": "websearch" } }, "/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": "beta", "x-fern-sdk-group-name": "analytics.query.data-security.content-findings", "x-fern-sdk-method-name": "top-n", "x-stability": "beta" } }, "/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": "beta", "x-fern-sdk-group-name": "analytics.query.data-security.findings", "x-fern-sdk-method-name": "summary", "x-stability": "beta" } }, "/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": "beta", "x-fern-sdk-group-name": "analytics.query.data-security.findings", "x-fern-sdk-method-name": "timeseries", "x-stability": "beta" } }, "/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": "beta", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "summary", "x-stability": "beta" } }, "/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": "beta", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "timeseries", "x-stability": "beta" } }, "/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": "beta", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "top-n", "x-stability": "beta" } }, "/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}/argo/count_zones_enabled": { "get": { "operationId": "argo-smart-routing-get-count-zones-enabled-for-account", "summary": "Get count of zones with Argo Smart Routing enabled for account", "description": "Returns the number of zones that have Argo Smart Routing enabled for the specified account.", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifier of the account.", "required": true, "schema": { "$ref": "#/components/schemas/argo-config_identifier" } } ], "responses": { "200": { "description": "Count of zones with Argo Smart Routing enabled.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "errors": [], "messages": [], "result": 5, "success": true } } }, "schema": { "$ref": "#/components/schemas/argo-config_count_zones_response" } } } }, "4XX": { "description": "Count zones enabled failure.", "content": { "application/json": { "examples": { "error": { "summary": "Error response", "value": { "errors": [ { "code": 7003, "message": "No route for the URI" } ], "messages": [], "result": null, "success": false } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/argo-config_api_response_common_failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Argo Smart Routing" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "argo.smart-routing", "x-fern-sdk-method-name": "count-zones-enabled-for-account" } }, "/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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-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. Token IDs are resolved through an eventually consistent index, so revoking a token within about a second of creating it can return 404; retry after a short delay.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "maxLength": 63, "minLength": 2, "pattern": "^[a-zA-Z0-9]([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-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/audit_logs": { "get": { "operationId": "audit-logs-get-account-audit-logs", "summary": "Get account audit logs", "description": "Gets a list of audit logs for an account. Can be filtered by who made the change, on which zone, and the timeframe of the change.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_identifier" } }, { "name": "id", "in": "query", "schema": { "description": "Finds a specific log by its ID.", "type": "string", "example": "f174be97-19b1-40d6-954d-70cd5fbd52db" } }, { "name": "export", "in": "query", "schema": { "description": "Indicates that this request is an export of logs in CSV format.", "type": "boolean", "example": true } }, { "name": "action.type", "in": "query", "schema": { "description": "Filters by the action type.", "type": "string", "example": "add" } }, { "name": "actor.ip", "in": "query", "schema": { "description": "Filters by the IP address of the request that made the change by specific IP address or valid CIDR Range.", "type": "string", "example": "17.168.228.63" } }, { "name": "actor.email", "in": "query", "schema": { "description": "Filters by the email address of the actor that made the change.", "type": "string", "format": "email", "example": "alice@example.com" } }, { "name": "since", "in": "query", "schema": { "oneOf": [ { "description": "Limits the returned results to logs newer than the specified date. A `full-date` that conforms to RFC3339.", "example": "2019-04-30", "format": "date", "type": "string" }, { "description": "Limits the returned results to logs newer than the specified date. A `date-time` that conforms to RFC3339.", "example": "2019-04-30T01:12:20Z", "format": "date-time", "type": "string" } ] } }, { "name": "before", "in": "query", "schema": { "oneOf": [ { "description": "Limits the returned results to logs older than the specified date. A `full-date` that conforms to RFC3339.", "example": "2019-04-30", "format": "date", "type": "string" }, { "description": "Limits the returned results to logs older than the specified date. A `date-time` that conforms to RFC3339.", "example": "2019-04-30T01:12:20Z", "format": "date-time", "type": "string" } ] } }, { "name": "zone.name", "in": "query", "schema": { "description": "Filters by the name of the zone associated to the change.", "type": "string", "example": "example.com" } }, { "name": "direction", "in": "query", "schema": { "description": "Changes the direction of the chronological sorting.", "type": "string", "example": "desc", "default": "desc", "enum": [ "desc", "asc" ] } }, { "name": "per_page", "in": "query", "schema": { "description": "Sets the number of results to return per page.", "type": "number", "example": 25, "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "description": "Defines which page of results to return.", "type": "number", "example": 50, "default": 1, "minimum": 1 } }, { "name": "hide_user_logs", "in": "query", "schema": { "description": "Indicates whether or not to hide user level audit logs.", "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Get account audit logs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_audit_logs_response_collection" } } } }, "4XX": { "description": "Get account audit logs response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_audit_logs_response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Audit Logs" ], "x-api-token-group": [ "Account Settings Write", "Account Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "audit-logs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/autorag/rags/{id}/ai-search": { "post": { "operationId": "autorag-config-ai-search", "summary": "AI Search", "description": "Runs an AI Search query against an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "anyOf": [ { "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value" ], "type": "object" }, { "properties": { "filters": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value" ], "type": "object" } }, "type": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "type", "filters" ], "type": "object" } ] }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "model": { "anyOf": [ { "enum": [ "@cf/meta/llama-3.3-70b-instruct-fp8-fast", "@cf/meta/llama-3.1-8b-instruct-fast", "@cf/meta/llama-3.1-8b-instruct-fp8", "@cf/meta/llama-4-scout-17b-16e-instruct", "@cf/qwen/qwen3-30b-a3b-fp8", "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b", "@cf/moonshotai/kimi-k2-instruct", "anthropic/claude-3-7-sonnet", "anthropic/claude-sonnet-4", "anthropic/claude-opus-4", "anthropic/claude-3-5-haiku", "cerebras/qwen-3-235b-a22b-instruct", "cerebras/qwen-3-235b-a22b-thinking", "cerebras/llama-3.3-70b", "cerebras/llama-4-maverick-17b-128e-instruct", "cerebras/llama-4-scout-17b-16e-instruct", "cerebras/gpt-oss-120b", "google-ai-studio/gemini-2.5-flash", "google-ai-studio/gemini-2.5-pro", "grok/grok-4", "groq/llama-3.3-70b-versatile", "groq/llama-3.1-8b-instant", "openai/gpt-5", "openai/gpt-5-mini", "openai/gpt-5-nano" ], "type": "string" }, { "enum": [ "" ], "type": "string" } ] }, "query": { "type": "string" }, "ranking_options": { "type": "object", "default": {}, "properties": { "ranker": { "type": "string" }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "model": { "anyOf": [ { "enum": [ "@cf/baai/bge-reranker-base" ], "type": "string" }, { "enum": [ "" ], "type": "string" } ] } } }, "rewrite_query": { "type": "boolean", "default": false }, "stream": { "type": "boolean", "default": false }, "system_prompt": { "type": "string" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Returns the log details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "attributes": { "type": "object" }, "content": { "items": { "properties": { "text": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "file_id": { "type": "string" }, "filename": { "type": "string" }, "score": { "type": "number" } }, "required": [ "score" ], "type": "object" } }, "has_more": { "type": "boolean", "default": false }, "next_page": { "type": "string", "nullable": true }, "object": { "type": "string" }, "response": { "type": "string" }, "search_query": { "type": "string" } }, "required": [ "search_query", "response" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG RAG Search" ], "x-api-token-group": [ "Auto Rag Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag", "x-fern-sdk-method-name": "ai-search" } }, "/accounts/{account_id}/autorag/rags/{id}/files": { "get": { "operationId": "autorag-config-files", "summary": "Files", "description": "Lists files indexed by an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "completed", "queued", "running", "error" ] } } ], "responses": { "200": { "description": "Returns the AI Search files", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "error": { "type": "string" }, "key": { "type": "string" } }, "required": [ "key", "error" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer", "default": 20, "maximum": 50, "minimum": 5 }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "404": { "description": "autorag_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "autorag_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG RAG" ], "x-api-token-group": [ "Auto Rag Write", "Auto Rag Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag", "x-fern-sdk-method-name": "files" } }, "/accounts/{account_id}/autorag/rags/{id}/jobs": { "get": { "operationId": "autorag-config-list-jobs", "summary": "List Jobs", "description": "Lists jobs for an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 0 } } ], "responses": { "200": { "description": "Returns a list of AutoRAG Jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string" }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ] }, "started_at": { "type": "string" } }, "required": [ "id", "source" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "404": { "description": "autorag_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "autorag_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG Jobs" ], "x-api-token-group": [ "Auto Rag Write", "Auto Rag Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag.jobs", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/autorag/rags/{id}/jobs/{job_id}": { "get": { "operationId": "autorag-config-get-job", "summary": "Get a Job Details", "description": "Returns details for an AutoRAG job.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "responses": { "200": { "description": "Returns a AutoRAG Job Details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string" }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ] }, "started_at": { "type": "string" } }, "required": [ "id", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "job_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7021 }, "message": { "type": "string", "example": "job_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG Jobs" ], "x-api-token-group": [ "Auto Rag Write", "Auto Rag Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag.jobs", "x-fern-sdk-method-name": "get" } }, "/accounts/{account_id}/autorag/rags/{id}/jobs/{job_id}/logs": { "get": { "operationId": "autorag-config-list-job-logs", "summary": "List Job Logs", "description": "Lists logs for an AutoRAG job.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 500, "minimum": 0 } } ], "responses": { "200": { "description": "Returns a list of AutoRAG Job Logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "number" }, "id": { "type": "integer" }, "message": { "type": "string" }, "message_type": { "type": "integer" } }, "required": [ "id", "message", "message_type", "created_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "404": { "description": "autorag_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "autorag_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG Jobs" ], "x-api-token-group": [ "Auto Rag Write", "Auto Rag Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag.jobs", "x-fern-sdk-method-name": "logs" } }, "/accounts/{account_id}/autorag/rags/{id}/search": { "post": { "operationId": "autorag-config-search", "summary": "Search", "description": "Searches an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "anyOf": [ { "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value" ], "type": "object" }, { "properties": { "filters": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value" ], "type": "object" } }, "type": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "type", "filters" ], "type": "object" } ] }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "query": { "type": "string" }, "ranking_options": { "type": "object", "default": {}, "properties": { "ranker": { "type": "string" }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "model": { "anyOf": [ { "enum": [ "@cf/baai/bge-reranker-base" ], "type": "string" }, { "enum": [ "" ], "type": "string" } ] } } }, "rewrite_query": { "type": "boolean", "default": false } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Returns the log details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "attributes": { "type": "object" }, "content": { "items": { "properties": { "text": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "file_id": { "type": "string" }, "filename": { "type": "string" }, "score": { "type": "number" } }, "required": [ "score" ], "type": "object" } }, "has_more": { "type": "boolean", "default": false }, "next_page": { "type": "string", "nullable": true }, "object": { "type": "string" }, "search_query": { "type": "string" } }, "required": [ "search_query" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG RAG Search" ], "x-api-token-group": [ "Auto Rag Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag", "x-fern-sdk-method-name": "search" } }, "/accounts/{account_id}/autorag/rags/{id}/sync": { "patch": { "operationId": "autorag-config-sync", "summary": "Sync", "description": "Starts synchronization for an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "responses": { "200": { "description": "Returns the autorag sync status", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "autorag_is_paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7032 }, "message": { "type": "string", "example": "autorag_is_paused" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "autorag_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "autorag_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "429": { "description": "sync_in_cooldown", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7020 }, "message": { "type": "string", "example": "sync_in_cooldown" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG RAG" ], "x-api-token-group": [ "Auto Rag Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag", "x-fern-sdk-method-name": "sync" } }, "/accounts/{account_id}/basin-catalog": { "get": { "operationId": "basin-list-catalogs", "summary": "List Basin Catalogs", "description": "Returns a list of R2 buckets that have been enabled as Apache Iceberg catalogs\nfor the specified account. Each catalog represents an R2 bucket configured\nto store Iceberg metadata and data files.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } } ], "responses": { "200": { "description": "List of Basin Catalogs.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "warehouses": [ { "bucket": "analytics-bucket", "id": "550e8400-e29b-41d4-a716-446655440000", "maintenance_config": { "compaction": { "state": "enabled", "target_size_mb": "128" }, "snapshot_expiration": { "max_snapshot_age": "7d", "min_snapshots_to_keep": 100, "state": "enabled" } }, "name": "account123_analytics-bucket", "status": "active" }, { "bucket": "logs-bucket", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "maintenance_config": { "compaction": { "state": "disabled", "target_size_mb": "128" }, "snapshot_expiration": { "max_snapshot_age": "7d", "min_snapshots_to_keep": 100, "state": "disabled" } }, "name": "account123_logs-bucket", "status": "inactive" } ] }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_catalog-list" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Basin Catalog Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write", "Workers R2 Data Catalog Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}": { "get": { "operationId": "basin-get-catalog-details", "summary": "Get Basin Catalog details", "description": "Retrieve detailed information about a specific Basin Catalog by bucket name.\nReturns catalog status, maintenance configuration, and credential status.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } } ], "responses": { "200": { "description": "Basin Catalog details.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "bucket": "analytics-bucket", "credential_status": "present", "id": "550e8400-e29b-41d4-a716-446655440000", "maintenance_config": { "compaction": { "state": "enabled", "target_size_mb": "128" }, "snapshot_expiration": { "max_snapshot_age": "7d", "min_snapshots_to_keep": 100, "state": "enabled" } }, "name": "account123_analytics-bucket", "status": "active" }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_catalog" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Basin Catalog Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write", "Workers R2 Data Catalog Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog", "x-fern-sdk-method-name": "get" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/credential": { "post": { "operationId": "basin-store-credentials", "summary": "Store catalog credentials", "description": "Store authentication credentials for a catalog. These credentials are used\nto authenticate with R2 storage when performing catalog operations.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "token": "your-cloudflare-api-token-here" }, "schema": { "$ref": "#/components/schemas/r2-data-catalog_catalog-credential-request" } } } }, "responses": { "200": { "description": "Credentials stored successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": null, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credential Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.credentials", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/credential/status": { "get": { "operationId": "basin-get-credential-status", "summary": "Get Basin Catalog credential status", "description": "Check whether the configured catalog credentials are valid, invalid,\nor absent by probing authentication against the catalog.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } } ], "responses": { "200": { "description": "Credential status retrieved successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "status": "valid" }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/r2-data-catalog_credential-probe-status" } }, "required": [ "status" ] } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credential Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write", "Workers R2 Data Catalog Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.credentials", "x-fern-sdk-method-name": "status" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/delete": { "post": { "operationId": "basin-delete-catalog", "summary": "Delete Basin Catalog metadata", "description": "Removes the catalog from the control plane without deleting R2 bucket objects.\nSet force=true to remove catalog namespaces, tables, views, and maintenance\nmetadata. Force deletion is limited to a configured catalog object count.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } }, { "name": "force", "in": "query", "description": "Remove child metadata before deleting the catalog.", "schema": { "type": "boolean", "default": false }, "x-fern-parameter-name": "cascade" } ], "responses": { "204": { "description": "Catalog metadata deleted successfully." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed." }, "404": { "description": "Catalog not found." }, "409": { "description": "Catalog is non-empty, has unfinished work, is protected, or exceeds the force-delete limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error." } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Basin Catalog Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog", "x-fern-sdk-method-name": "delete", "x-forge-require-confirmation": "This removes catalog metadata. R2 bucket objects are retained." } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/disable": { "post": { "operationId": "basin-disable-catalog", "summary": "Disable Basin Catalog", "description": "Disable an R2 bucket as a catalog. This operation deactivates the catalog\nbut preserves existing metadata and data files. The catalog can be\nre-enabled later.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name to disable as catalog.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } } ], "responses": { "204": { "description": "Catalog disabled successfully." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Basin Catalog Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog", "x-fern-sdk-method-name": "disable", "x-forge-require-confirmation": "This operation turns off the data catalog for the bucket. Existing namespace or table state remains, but writes stop." } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/enable": { "post": { "operationId": "basin-enable-catalog", "summary": "Enable R2 bucket as a catalog", "description": "Enable an R2 bucket as an Apache Iceberg catalog. This operation creates\nthe necessary catalog infrastructure and activates the bucket for storing\nIceberg metadata and data files.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name to enable as catalog.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } } ], "responses": { "200": { "description": "Catalog enabled successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "account123_my-bucket" }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_catalog-activation-response" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "R2 bucket not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "409": { "description": "Catalog already enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Basin Catalog Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog", "x-fern-sdk-method-name": "enable" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/maintenance-configs": { "get": { "operationId": "basin-get-maintenance-config", "summary": "Get catalog maintenance configuration", "description": "Retrieve the maintenance configuration for a specific catalog,\nincluding compaction settings and credential status.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } } ], "responses": { "200": { "description": "Maintenance configuration retrieved successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "credential_status": "present", "maintenance_config": { "compaction": { "state": "enabled", "target_size_mb": "128" }, "snapshot_expiration": { "max_snapshot_age": "7d", "min_snapshots_to_keep": 100, "state": "enabled" } } }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-config-response" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Maintenance Configuration" ], "x-api-token-group": [ "Workers R2 Data Catalog Write", "Workers R2 Data Catalog Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.maintenance-configs", "x-fern-sdk-method-name": "get" }, "post": { "operationId": "basin-update-maintenance-config", "summary": "Update catalog maintenance configuration", "description": "Update the maintenance configuration for a catalog. This allows you to\nenable or disable compaction and adjust target file sizes for optimization.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "compaction": { "state": "enabled", "target_size_mb": "256" }, "snapshot_expiration": { "max_snapshot_age": "14d", "min_snapshots_to_keep": 5, "state": "enabled" } }, "schema": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-update-request" } } } }, "responses": { "200": { "description": "Maintenance configuration updated successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "compaction": { "state": "enabled", "target_size_mb": "256" }, "snapshot_expiration": { "max_snapshot_age": "14d", "min_snapshots_to_keep": 5, "state": "enabled" } }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-config" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Maintenance Configuration" ], "x-api-token-group": [ "Workers R2 Data Catalog Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.maintenance-configs", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/namespaces": { "get": { "operationId": "basin-list-namespaces", "summary": "List namespaces in catalog", "description": "Returns a list of namespaces in the specified Basin Catalog.\nSupports hierarchical filtering and pagination for efficient traversal\nof large namespace hierarchies.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } }, { "name": "page_token", "in": "query", "description": "Opaque pagination token from a previous response.\nUse this to fetch the next page of results.\n", "schema": { "type": "string" }, "example": "MSYxNzU5NzU1NTc4NTA0MTk0JjAxOTliOTliLTJjODgtNzNiMy04ZGJiLTQyMWUwZThmMjc1Nw" }, { "name": "page_size", "in": "query", "description": "Maximum number of namespaces to return per page.\nDefaults to 100, maximum 1000.\n", "schema": { "type": "integer", "default": 100, "maximum": 1000, "minimum": 1 }, "example": 100 }, { "name": "parent", "in": "query", "description": "Parent namespace to filter by. Only returns direct children of this namespace.\nFor nested namespaces, use %1F as separator (e.g., \"bronze%1Fanalytics\").\nOmit this parameter to list top-level namespaces.\n", "schema": { "type": "string" }, "example": "bronze" }, { "name": "return_uuids", "in": "query", "description": "Whether to include namespace UUIDs in the response.\nSet to true to receive the namespace_uuids array.\n", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "return_details", "in": "query", "description": "Whether to include additional metadata (timestamps).\nWhen true, response includes created_at and updated_at arrays.\n", "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "List of namespaces retrieved successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "details": [ { "created_at": "2025-10-07T10:00:00Z", "namespace": [ "bronze" ], "namespace_uuid": "0199b999-6869-7383-bb1f-d30e059d5326", "updated_at": "2025-10-07T12:00:00Z" }, { "created_at": "2025-10-07T10:15:00Z", "namespace": [ "silver" ], "namespace_uuid": "0199b99b-2c88-73b3-8dbb-421e0e8f2757", "updated_at": null }, { "created_at": "2025-10-07T10:30:00Z", "namespace": [ "gold" ], "namespace_uuid": "0199b99c-3d99-73c4-9dcc-532f1f9f3868", "updated_at": "2025-10-07T11:00:00Z" } ], "namespace_uuids": [ "0199b999-6869-7383-bb1f-d30e059d5326", "0199b99b-2c88-73b3-8dbb-421e0e8f2757", "0199b99c-3d99-73c4-9dcc-532f1f9f3868" ], "namespaces": [ [ "bronze" ], [ "silver" ], [ "gold" ] ], "next_page_token": null }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_namespace-list-response" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request (e.g., invalid page_size, malformed parent namespace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Namespace Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write", "Workers R2 Data Catalog Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.namespaces", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/namespaces/{namespace}/tables": { "get": { "operationId": "basin-list-tables", "summary": "List tables in namespace", "description": "Returns a list of tables in the specified namespace within a Basin Catalog.\nSupports pagination for efficient traversal of large table collections.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } }, { "name": "namespace", "in": "path", "description": "The namespace identifier.\nFor nested namespaces, use %1F as separator (e.g., \"bronze%1Fanalytics\").\n", "required": true, "schema": { "type": "string" }, "example": "bronze" }, { "name": "page_token", "in": "query", "description": "Opaque pagination token from a previous response.\nUse this to fetch the next page of results.\n", "schema": { "type": "string" }, "example": "MSYxNzU5NzU2MTI4NTU2Njk2JjAxOTliOWEzLTkxMmUtN2ZhMS05YzllLTg5MTAxMGQzYTg0MQ" }, { "name": "page_size", "in": "query", "description": "Maximum number of tables to return per page.\nDefaults to 100, maximum 1000.\n", "schema": { "type": "integer", "default": 100, "maximum": 1000, "minimum": 1 }, "example": 100 }, { "name": "return_uuids", "in": "query", "description": "Whether to include table UUIDs in the response.\nSet to true to receive the table_uuids array.\n", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "return_details", "in": "query", "description": "Whether to include additional metadata (timestamps, locations).\nWhen true, response includes created_at, updated_at, metadata_locations, and locations arrays.\n", "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "List of tables retrieved successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "details": [ { "created_at": "2025-10-07T10:00:00Z", "identifier": { "name": "events", "namespace": [ "bronze" ] }, "location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id/", "metadata_location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id/metadata/v1.metadata.json", "table_uuid": "0199b9a1-28a0-71e0-a73e-b0fc32c8468e", "updated_at": "2025-10-07T15:00:00Z" }, { "created_at": "2025-10-07T10:30:00Z", "identifier": { "name": "users", "namespace": [ "bronze" ] }, "location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id-2/", "metadata_location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id-2/metadata/v2.metadata.json", "table_uuid": "0199b9a1-3c74-7731-bf53-d8c67ead079d", "updated_at": "2025-10-07T16:00:00Z" } ], "identifiers": [ { "name": "events", "namespace": [ "bronze" ] }, { "name": "users", "namespace": [ "bronze" ] } ], "next_page_token": null, "table_uuids": [ "0199b9a1-28a0-71e0-a73e-b0fc32c8468e", "0199b9a1-3c74-7731-bf53-d8c67ead079d" ] }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_table-list-response" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request (e.g., invalid page_size, malformed namespace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog or namespace not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Table Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write", "Workers R2 Data Catalog Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.namespaces.tables", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/namespaces/{namespace}/tables/{table_name}": { "get": { "operationId": "basin-get-table", "summary": "Get table details", "description": "Returns full Apache Iceberg metadata for a single table: schema,\npartition specs, sort orders, properties, and recent snapshot history.\nDesigned for catalog introspection UIs that need per-table details\nwithout holding R2 credentials.\n\nThe `metadata.snapshots`, `metadata.snapshot-log`, and\n`metadata.metadata-log` arrays are pruned to the most recent 10\nentries by `timestamp-ms`. Use `total_snapshots` and\n`returned_snapshots` to surface the truncation to end users.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } }, { "name": "namespace", "in": "path", "description": "The namespace identifier.\nFor nested namespaces, use %1F as separator (e.g., \"bronze%1Fanalytics\").\n", "required": true, "schema": { "type": "string" }, "example": "bronze" }, { "name": "table_name", "in": "path", "description": "The table name within the given namespace.", "required": true, "schema": { "type": "string" }, "example": "events" } ], "responses": { "200": { "description": "Table details retrieved successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "identifier": { "name": "events", "namespace": [ "bronze" ] }, "metadata": { "current-schema-id": 1, "current-snapshot-id": 3055729675574597000, "default-spec-id": 0, "format-version": 2, "location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id", "partition-specs": [ { "fields": [ { "field-id": 1000, "name": "user_id_bucket", "source-id": 1, "transform": "bucket[16]" } ], "spec-id": 0 } ], "properties": { "write.parquet.compression-codec": "zstd" }, "schemas": [ { "type": "struct", "fields": [ { "id": 1, "name": "user_id", "required": true, "type": "long" } ], "schema-id": 1 } ], "snapshots": [ { "sequence-number": 1, "snapshot-id": 3055729675574597000, "summary": { "operation": "append" }, "timestamp-ms": 1555100955770 } ], "table-uuid": "550e8400-e29b-41d4-a716-446655440000" }, "metadata_location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id/metadata/00001-abc.metadata.json", "returned_snapshots": 10, "table_uuid": "550e8400-e29b-41d4-a716-446655440000", "total_snapshots": 122113 }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_get-table-response" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request (e.g., malformed namespace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden — JWT claims do not match account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Catalog, namespace, or table not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Table Management" ], "x-api-token-group": [ "Workers R2 Data Catalog Write", "Workers R2 Data Catalog Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.namespaces.tables", "x-fern-sdk-method-name": "get" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/namespaces/{namespace}/tables/{table_name}/maintenance-configs": { "get": { "operationId": "basin-get-table-maintenance-config", "summary": "Get table maintenance configuration", "description": "Retrieve the maintenance configuration for a specific table,\nincluding compaction settings.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } }, { "name": "namespace", "in": "path", "description": "The namespace identifier (use %1F as separator for nested namespaces).", "required": true, "schema": { "type": "string" }, "example": "my_namespace%1Fsub_namespace" }, { "name": "table_name", "in": "path", "description": "The table name.", "required": true, "schema": { "type": "string" }, "example": "my_table" } ], "responses": { "200": { "description": "Table maintenance configuration retrieved successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "maintenance_config": { "compaction": { "next_eligible_at": "2026-09-01T12:00:00Z", "state": "enabled", "target_size_mb": "128" }, "interval": "1h", "snapshot_expiration": { "max_snapshot_age": "7d", "min_snapshots_to_keep": 100, "next_eligible_at": "2026-09-01T12:00:00Z", "state": "enabled" } } }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_table-maintenance-config-response" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Table not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Table Maintenance Configuration" ], "x-api-token-group": [ "Workers R2 Data Catalog Write", "Workers R2 Data Catalog Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.namespaces.tables.maintenance-configs", "x-fern-sdk-method-name": "get" }, "post": { "operationId": "basin-update-table-maintenance-config", "summary": "Update table maintenance configuration", "description": "Update the maintenance configuration for a specific table. This allows you to\nenable or disable compaction and adjust target file sizes for optimization.\n", "parameters": [ { "name": "account_id", "in": "path", "description": "Identifies the account.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "description": "Specifies the R2 bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } }, { "name": "namespace", "in": "path", "description": "The namespace identifier (use %1F as separator for nested namespaces).", "required": true, "schema": { "type": "string" }, "example": "my_namespace%1Fsub_namespace" }, { "name": "table_name", "in": "path", "description": "The table name.", "required": true, "schema": { "type": "string" }, "example": "my_table" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "compaction": { "state": "enabled", "target_size_mb": "256" }, "snapshot_expiration": { "max_snapshot_age": "14d", "min_snapshots_to_keep": 5, "state": "enabled" } }, "schema": { "$ref": "#/components/schemas/r2-data-catalog_table-maintenance-update-request" } } } }, "responses": { "200": { "description": "Table maintenance configuration updated successfully.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "compaction": { "next_eligible_at": "2026-09-01T12:00:00Z", "state": "enabled", "target_size_mb": "256" }, "interval": "1h", "snapshot_expiration": { "max_snapshot_age": "14d", "min_snapshots_to_keep": 5, "next_eligible_at": "2026-09-01T12:00:00Z", "state": "enabled" } }, "success": true }, "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_table-maintenance-config" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Table not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Table Maintenance Configuration" ], "x-api-token-group": [ "Workers R2 Data Catalog Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.namespaces.tables.maintenance-configs", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/namespaces/{namespace}/tables/{table_name}/maintenance-configs/{configuration_type}/queue": { "post": { "operationId": "basin-queue-table-maintenance", "summary": "Queue table maintenance", "description": "Queue maintenance for normal polling. This request does not start a run.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "table_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "configuration_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "compaction", "snapshot_expiration" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_queue-maintenance-request" } } } }, "responses": { "202": { "description": "Maintenance was queued for normal polling.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_queue-maintenance-response" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Table or maintenance configuration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "409": { "description": "Maintenance is currently assigned to an executor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "429": { "description": "Manual queue request limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Table Maintenance Configuration" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.namespaces.tables.maintenance-configs", "x-fern-sdk-method-name": "queue" } }, "/accounts/{account_id}/basin-catalog/{bucket_name}/namespaces/{namespace}/tables/{table_name}/maintenance-runs": { "get": { "operationId": "basin-list-table-maintenance-runs", "summary": "List table maintenance runs", "description": "Retrieves recent table maintenance runs for the current table.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_account-id" } }, { "name": "bucket_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/r2-data-catalog_bucket-name" } }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "table_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "page_token", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Maintenance runs retrieved successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/r2-data-catalog_maintenance-runs-response" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } }, "404": { "description": "Table not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/r2-data-catalog_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Table Maintenance Configuration" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "basin-catalog.namespaces.tables.maintenance-runs", "x-fern-sdk-method-name": "list" } }, "/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:** This endpoint serves `usage` records only; cost and pricing\nfields are absent from responses. To retrieve rated costs, use `POST`\non the same path with `Metric: cost`.\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 populated only when `Metric`\nis `cost`; otherwise they are absent from responses.\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 groups, in any combination of\ndimension keys and resource-tag keys. Tag groups are returned in the\n`Tags` field. Usage without a requested tag remains in an untagged\ngroup, with that key omitted from `Tags`.\n\nRequests that use tag filtering or tag grouping return HTTP 400 when the\nunderlying usage data source does not support tags.\n\nRequests that use dimension grouping return HTTP 400 when the\nunderlying usage data source does not support dimensions.\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" } }, "/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" } }, "/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" } }, "/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" } }, "/accounts/{account_id}/brand-protection/alerts": { "get": { "operationId": "getAccountsAccountIdBrandProtectionAlerts", "summary": "Read all alerts on submitted domains", "description": "Return all alerts on submitted domains.", "responses": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.alerts", "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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.alerts", "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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.alerts", "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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.brands", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getAccountsAccountIdBrandProtectionBrands", "summary": "Read all brands", "description": "Return all brands.", "responses": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.brands", "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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": "postAccountsAccountIdBrandProtectionBrandsPatterns", "summary": "Create new patterns for brands by ID", "description": "Return a success message after creating new patterns for brands by ID.", "responses": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.brands", "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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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/logos": { "get": { "operationId": "getAccountsAccountIdBrandProtectionLogos", "summary": "Read all saved logo queries", "description": "Return all saved logo queries.", "responses": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.logos", "x-fern-sdk-method-name": "list", "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" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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/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." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.queries", "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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" }, "4XX": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "5XX": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.queries", "x-fern-sdk-method-name": "dismiss", "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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" }, "4XX": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "5XX": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.queries", "x-fern-sdk-method-name": "undismiss", "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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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": { "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "500": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" }, "2XX": { "$ref": "#/components/responses/brand-protection-api_SUCCESS" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "brand-protection.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-ignore": true, "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-ignore": true, "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-ignore": true, "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-ignore": true, "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-ignore": true, "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-ignore": true, "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-ignore": true, "x-fern-sdk-group-name": "browser-extension.config.logs.extension-events", "x-fern-sdk-method-name": "search", "x-stability": "beta" } }, "/accounts/{account_id}/browser-extension/config/logs/extension-events/timeseries": { "parameters": [ { "$ref": "#/components/parameters/brex_AccountId" } ], "post": { "operationId": "accounts-browser-extension-config-extension-events-timeseries", "summary": "Query browser extension event timeseries", "description": "Returns browser extension event counts grouped by time bucket and the requested\n`groupBy` fields. Accepts the same filters as event log search. When `resolution` is\nomitted, ranges shorter than 10 days use `1 hours` buckets and ranges of 10 days or\nmore use `1 days`. Empty buckets are omitted. Results over 10000 slots return 400.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ExtensionEventsTimeseriesRequest" } } } }, "responses": { "200": { "description": "Browser extension event timeseries response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ExtensionEventsTimeseriesResponse" } } } }, "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-ignore": true, "x-fern-sdk-group-name": "browser-extension.config.logs.extension-events", "x-fern-sdk-method-name": "timeseries", "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 } }, { "name": "browser", "in": "query", "description": "Rendering backend. Set to `kitesurf` to use Kitesurf (beta).", "schema": { "description": "Rendering backend. Set to `kitesurf` to use Kitesurf (beta).", "type": "string", "enum": [ "kitesurf" ] } } ], "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 `