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. To 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. Using 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. To 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 our [API fundamentals](https://developers.cloudflare.com/fundamentals/api/). For 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). Totally new to Cloudflare? [Start here](https://developers.cloudflare.com/fundamentals/get-started/). license: name: BSD-3-Clause url: https://opensource.org/licenses/BSD-3-Clause title: Cloudflare API version: 4.0.0 servers: - description: Client API url: https://api.cloudflare.com/client/v4 paths: /accounts: get: operationId: accounts-list-accounts summary: List Accounts description: List all accounts you have ownership or verified access to. parameters: - name: name in: query schema: description: Name of the account. type: string example: example.com readOnly: true - name: page in: query schema: description: Page number of paginated results. type: number default: 1 minimum: 1 - name: per_page in: query schema: description: Maximum number of results per page. type: number default: 20 maximum: 50 minimum: 5 - name: direction in: query schema: description: Direction to order results. type: string example: desc enum: - asc - desc responses: '200': description: List Accounts response content: application/json: schema: $ref: '#/components/schemas/iam_response_collection_accounts' 4XX: description: List Accounts response failure content: application/json: schema: $ref: '#/components/schemas/iam_api-response-common-failure' security: - api_email: [] api_key: [] tags: - Accounts x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: accounts x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: account-creation summary: Create an account description: Create an account (only available for tenant admins at this time) requestBody: description: Parameters for account creation required: true content: application/json: schema: $ref: '#/components/schemas/iam_create-account' responses: '200': description: Account Creation Success Response content: application/json: schema: $ref: '#/components/schemas/iam_response_single_account' 4XX: description: Account Creation Failure Response content: application/json: schema: $ref: '#/components/schemas/iam_api-response-common-failure' security: - api_email: [] api_key: [] tags: - Accounts x-cfPlanAvailability: business: false enterprise: false free: false pro: false x-fern-availability: generally-available x-fern-sdk-group-name: accounts x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}: delete: operationId: account-deletion summary: Delete a specific account description: Delete a specific account (only available for tenant admins at this time). This is a permanent operation that will delete any zones or other resources under the account parameters: - name: account_id in: path required: true schema: description: The account ID of the account to be deleted type: string responses: '200': description: Account Deletion Success Response content: application/json: schema: $ref: '#/components/schemas/iam_api-response-single-id' 4XX: description: Account Deletion Failure Response content: application/json: schema: $ref: '#/components/schemas/iam_api-response-common-failure' security: - api_email: [] api_key: [] tags: - Accounts x-api-token-group: - Account Settings Write x-cfPermissionsRequired: enum: - '#organization:edit' x-cfPlanAvailability: business: false enterprise: false free: false pro: false x-fern-availability: generally-available x-fern-sdk-group-name: accounts x-fern-sdk-method-name: delete x-forge-hidden: true x-forge-require-confirmation: Are you sure? This action cannot be undone. get: operationId: accounts-account-details summary: Account Details description: Get information about a specific account that you are a member of. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/iam_account_identifier' responses: '200': description: Account Details response content: application/json: schema: $ref: '#/components/schemas/iam_response_single_account' 4XX: description: Account Details response failure content: application/json: schema: $ref: '#/components/schemas/iam_api-response-common-failure' security: - api_email: [] api_key: [] tags: - Accounts x-api-token-group: - Trust and Safety Write - Trust and Safety Read - DNS View Write - DNS View Read - SCIM Provisioning - Load Balancers Account Write - Load Balancers Account Read - 'Zero Trust: PII Read' - DDoS Botnet Feed Write - DDoS Botnet Feed Read - Workers R2 Storage Write - Workers R2 Storage Read - DDoS Protection Write - DDoS Protection Read - Workers Tail Read - Workers KV Storage Write - Workers KV Storage Read - Workers Scripts Write - Workers Scripts Read - 'Load Balancing: Monitors and Pools Write' - 'Load Balancing: Monitors and Pools Read' - Account Firewall Access Rules Write - Account Firewall Access Rules Read - DNS Firewall Write - DNS Firewall Read - Billing Write - Billing Read - Account Settings Write - Account Settings Read x-cfPermissionsRequired: enum: - '#organization:read' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: accounts x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: accounts-update-account summary: Update Account description: Update an existing account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/iam_account_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/iam_components-schemas-account' responses: '200': description: Update Account response content: application/json: schema: $ref: '#/components/schemas/iam_response_single_account' 4XX: description: Update Account response failure content: application/json: schema: $ref: '#/components/schemas/iam_api-response-common-failure' security: - api_email: [] api_key: [] tags: - Accounts x-api-token-group: - Account Settings Write x-cfPermissionsRequired: enum: - '#organization:edit' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: accounts x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/abuse-reports: get: operationId: ListAbuseReports summary: List abuse reports description: List the abuse reports for a given account parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: page in: query description: Where in pagination to start listing abuse reports schema: type: integer - name: per_page in: query description: How many abuse reports per page to list schema: type: integer - name: sort in: query description: A property to sort by, followed by the order (id, cdate, domain, type, status) schema: type: string example: cdate,desc - name: domain in: query description: Filter by domain name related to the abuse report schema: type: string example: example.com - name: created_before in: query description: Returns reports created before the specified date schema: description: Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html) type: string example: 2009-11-10T23:00:00Z example: 2009-11-10T23:00:00Z - name: created_after in: query description: Returns reports created after the specified date schema: description: Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html) type: string example: 2009-11-10T23:00:00Z example: 2009-11-10T23:00:00Z - name: status in: query description: Filter by the status of the report. schema: $ref: '#/components/schemas/abuse-reports_ReportStatus' example: denied - name: type in: query description: Filter by the type of the report. schema: $ref: '#/components/schemas/abuse-reports_ReportType' example: denied - name: mitigation_status in: query description: Filter reports that have any mitigations in the given status. schema: $ref: '#/components/schemas/abuse-reports_MitigationStatus' example: active responses: '200': description: Abuse report list successful content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' result: type: object properties: reports: type: array items: $ref: '#/components/schemas/abuse-reports_AbuseReport' required: - reports result_info: type: object properties: count: type: number page: type: number per_page: type: number total_count: type: number total_pages: type: number required: - page - per_page - count - total_count - total_pages success: type: boolean required: - success '401': description: |- The request is not authorized. Missing or invalid credentials may be rejected with the standard Cloudflare API authentication error. If credentials are valid, the API token does not have the Abuse Reports read permission required for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '500': description: Failed to retrieve abuse reports content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' success: type: boolean required: - success security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write - Trust and Safety Read x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/abuse-reports/{report_id}/appeals/eligibility: get: operationId: CheckAppealEligibility summary: Check whether a report can be appealed description: 'Returns whether the report is currently appealable, along with the signals behind that decision: whether it already has an open appeal, how many appeals have been submitted against it, and whether it has at least one mitigation that an appeal could reverse.' parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: report_id in: path description: Abuse Report ID required: true schema: type: string responses: '200': description: Appeal eligibility for the report content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' result: $ref: '#/components/schemas/abuse-reports_AppealEligibility' success: type: boolean required: - success '401': description: |- The request is not authorized. Missing or invalid credentials may be rejected with the standard Cloudflare API authentication error. If credentials are valid, the API token does not have the Abuse Reports read permission required for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '404': description: The report was not found, or does not support appeals. content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' success: type: boolean required: - success '500': description: Failed to check appeal eligibility. content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' success: type: boolean required: - success security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write - Trust and Safety Read x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports.appeals x-fern-sdk-method-name: eligibility x-forge-hidden: true /accounts/{account_id}/abuse-reports/{report_id}/emails: get: operationId: ListEmails summary: List abuse report emails description: List emails sent to the customer for an abuse report. Returns all successful customer emails sent for the specified abuse report. Does not include emails sent to hosts or submitters. parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: report_id in: path description: Abuse Report ID required: true schema: type: string - name: page in: query description: Page number to retrieve (default 1) schema: type: integer - name: per_page in: query description: Number of emails per page (default 20, max 100) schema: type: integer responses: '200': description: List abuse report emails successful content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' result: type: object properties: emails: type: array items: $ref: '#/components/schemas/abuse-reports_EmailListItem' required: - emails result_info: type: object properties: count: type: number page: type: number per_page: type: number total_count: type: number total_pages: type: number required: - page - per_page - count - total_count - total_pages success: type: boolean required: - success '400': description: Bad request - invalid parameters or report not found content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' success: type: boolean required: - success '401': description: |- The request is not authorized. Missing or invalid credentials may be rejected with the standard Cloudflare API authentication error. If credentials are valid, the API token does not have the Abuse Reports read permission required for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '500': description: Failed to list abuse report emails content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' success: type: boolean required: - success security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write - Trust and Safety Read x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports.emails x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/abuse-reports/{report_id}/mitigations: get: operationId: ListMitigations summary: List abuse report mitigations description: List mitigations done to remediate the abuse report. parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: report_id in: path description: Abuse Report ID required: true schema: type: string - name: page in: query description: Where in pagination to start listing abuse reports schema: type: integer - name: per_page in: query description: How many abuse reports per page to list schema: type: integer - name: sort in: query description: A property to sort by, followed by the order schema: type: string enum: - type,asc - type,desc - effective_date,asc - effective_date,desc - status,asc - status,desc - entity_type,asc - entity_type,desc example: type,desc - name: type in: query description: Filter by the type of mitigation. This filter parameter can be specified multiple times to include multiple types of mitigations in the result set. schema: $ref: '#/components/schemas/abuse-reports_MitigationType' - name: effective_before in: query description: Returns mitigations that were dispatched before the given date schema: description: Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html) type: string example: 2009-11-10T23:00:00Z example: 2009-11-10T23:00:00Z - name: effective_after in: query description: Returns mitigation that were dispatched after the given date schema: description: Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html) type: string example: 2009-11-10T23:00:00Z example: 2009-11-10T23:00:00Z - name: status in: query description: Filter by the status of the mitigation. schema: $ref: '#/components/schemas/abuse-reports_MitigationStatus' - name: entity_type in: query description: Filter by the type of entity the mitigation impacts. schema: $ref: '#/components/schemas/abuse-reports_MitigatedEntityType' responses: '200': description: List abuse report mitigations successful content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' result: type: object properties: mitigations: type: array items: $ref: '#/components/schemas/abuse-reports_MitigationListItem' required: - mitigations result_info: type: object properties: count: type: number page: type: number per_page: type: number total_count: type: number total_pages: type: number required: - page - per_page - count - total_count - total_pages success: type: boolean required: - success '401': description: |- The request is not authorized. Missing or invalid credentials may be rejected with the standard Cloudflare API authentication error. If credentials are valid, the API token does not have the Abuse Reports read permission required for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '500': description: Failed to list abuse report mitigations content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' success: type: boolean required: - success security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write - Trust and Safety Read x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports.mitigations x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/abuse-reports/{report_id}/mitigations/appeal: post: operationId: RequestReview summary: Request review on mitigations description: Request a review for mitigations on an account. Repeating a request for a mitigation with an unresolved appeal is idempotent and returns that mitigation in the in-review state. parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: report_id in: path description: Abuse Report ID required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/abuse-reports_MitigationAppealRequest' responses: '200': description: Mitigation appeals received, including idempotent replays of unresolved appeals. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_MitigationAppealResult' '207': description: Some mitigation appeals were accepted while others were invalid or cannot be appealed. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_MitigationAppealResult' '401': description: |- The request is not authorized. Missing or invalid credentials may be rejected with the standard Cloudflare API authentication error. If credentials are valid, the API token does not have the Abuse Reports edit permission required for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '500': description: Failed to request review on delayed action. content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_Message' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' success: type: boolean required: - success security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports.mitigations x-fern-sdk-method-name: review x-forge-hidden: true /accounts/{account_id}/abuse-reports/{report_param}: get: operationId: GetAbuseReport summary: Abuse Report Details description: Retrieve the details of an abuse report. parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: report_param in: path description: Identifier of the abuse report required: true schema: type: string responses: '200': description: Report submitted successfully content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_ErrorMessage' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' result: $ref: '#/components/schemas/abuse-reports_AbuseReport' success: type: boolean required: - success - result '400': description: Report submitted with an error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_ErrorMessage' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' result: $ref: '#/components/schemas/abuse-reports_AbuseReport' success: type: boolean required: - success - errors '401': description: |- The request is not authorized. Missing or invalid credentials may be rejected with the standard Cloudflare API authentication error. If credentials are valid, the API token does not have the Abuse Reports read permission required for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '500': description: Report submitted with an error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/abuse-reports_ErrorMessage' messages: type: array items: $ref: '#/components/schemas/abuse-reports_Message' result: $ref: '#/components/schemas/abuse-reports_AbuseReport' success: type: boolean required: - success - errors security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write - Trust and Safety Read x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports x-fern-sdk-method-name: get x-forge-hidden: true post: operationId: SubmitAbuseReport summary: Submit an abuse report description: |- Submit an abuse report of a particular type. Requires the abuse-reports entitlement on the account (Enterprise accounts have it by default; other accounts must request access) and an API token with the `Account > Abuse Reports > Edit` permission. If the account is not entitled, the request is rejected with an HTTP `401` response (see below). parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: report_param in: path description: 'The report type to be submitted. Example: abuse_general' required: true schema: $ref: '#/components/schemas/abuse-reports_SubmissionReportType' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/abuse-reports_SubmitReportRequest' responses: '200': description: Report submitted successfully content: application/json: schema: $ref: '#/components/schemas/abuse-reports_SubmitReportResponse' '400': description: Report submitted with an error content: application/json: schema: $ref: '#/components/schemas/abuse-reports_SubmitErrorResponse' '401': description: |- The request is not authorized to submit abuse reports. Missing or invalid credentials may be rejected with the standard Cloudflare API authentication error. If credentials are valid, this is most commonly because the account does not have the abuse-reports entitlement (Enterprise accounts have it by default; other accounts must request access), or because the API token is missing the `Account > Abuse Reports > Edit` permission. Entitlement failures return the message `Not entitled to use feature: Abuse Report API`. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '500': description: Report submitted with an error content: application/json: schema: $ref: '#/components/schemas/abuse-reports_SubmitErrorResponse' security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/abuse-reports/submitted: get: operationId: ListSubmittedAbuseReports summary: List submitted abuse reports description: List abuse reports submitted by the account. parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: page in: query description: Page of submitted reports to return. schema: type: integer default: 1 minimum: 1 - name: per_page in: query description: Number of submitted reports per page. schema: type: integer default: 100 maximum: 200 minimum: 1 - name: sort in: query description: A property and direction to sort by (id, cdate, domain, type, status). schema: type: string example: cdate,desc - name: id in: query description: Filter by report code. schema: type: string - name: domain in: query description: Filter by reported domain. This parameter can be specified multiple times. schema: type: array items: type: string explode: true style: form - name: created_before in: query description: Return reports submitted before this time. schema: type: string format: date-time - name: created_after in: query description: Return reports submitted after this time. schema: type: string format: date-time - name: status in: query description: Filter by submitter-facing status. This parameter can be specified multiple times. schema: type: array items: $ref: '#/components/schemas/abuse-reports_SubmittedAbuseReportStatus' explode: true style: form - name: type in: query description: Filter by report type. This parameter can be specified multiple times. schema: type: array items: $ref: '#/components/schemas/abuse-reports_ReportType' explode: true style: form responses: '200': description: Submitted abuse reports listed successfully. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_SubmittedAbuseReportListResponse' '400': description: Invalid account or query parameters. '401': description: The request is not authorized to read abuse reports for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '500': description: Failed to retrieve submitted abuse reports. security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write - Trust and Safety Read x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports x-fern-sdk-method-name: listSubmitted x-forge-hidden: true /accounts/{account_id}/abuse-reports/submitted/{report_id}: get: operationId: GetSubmittedAbuseReport summary: Get a submitted abuse report description: Retrieve a report submitted by the account. parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: report_id in: path description: Public report code. required: true schema: type: string responses: '200': description: Submitted abuse report found. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_SubmittedAbuseReportDetailResponse' '400': description: Invalid account or report code. '401': description: The request is not authorized to read abuse reports for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '404': description: No matching submitted report was found for the account. '500': description: Failed to retrieve the submitted abuse report. security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write - Trust and Safety Read x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports x-fern-sdk-method-name: getSubmitted x-forge-hidden: true /accounts/{account_id}/abuse-reports/submitted/{report_id}/emails: get: operationId: ListSubmittedAbuseReportEmails summary: List emails sent to an abuse report submitter description: List successful emails sent to the submitter of a report submitted by the account. Does not include emails sent to customers or hosts. parameters: - name: account_id in: path description: Cloudflare Account ID required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 maxLength: 32 - name: report_id in: path description: Public report code. required: true schema: type: string - name: page in: query description: Page number to retrieve (default 1). schema: type: integer - name: per_page in: query description: Number of emails per page (default 20, max 100). schema: type: integer responses: '200': description: Submitted abuse report emails listed successfully. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_EmailListResponse' '400': description: Invalid account, report, or query parameters. '401': description: The request is not authorized to read abuse reports for this account. content: application/json: schema: $ref: '#/components/schemas/abuse-reports_UnauthorizedErrorResponse' '404': description: Submitted abuse report not found for the selected account. '500': description: Failed to retrieve submitted abuse report emails. security: - api_token: [] tags: - tseng-abuse-complaint-processor_other x-api-token-group: - Trust and Safety Write - Trust and Safety Read x-fern-availability: generally-available x-fern-sdk-group-name: abuse-reports.emails x-fern-sdk-method-name: listSubmitted x-forge-hidden: true /accounts/{account_id}/access/ai-controls/mcp/analytics/portals/{portal_id}/tool-calls/timeseries: get: operationId: mcp-portals-api-portal-tool-call-timeseries summary: Per-portal MCP tool-call timeseries description: Returns daily or monthly tool-call counts for a portal. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c - name: portal_id in: path required: true schema: type: string - name: granularity in: query schema: type: string default: daily enum: - daily - monthly - name: aggregate in: query schema: type: string default: 'false' enum: - 'true' - 'false' - name: tz in: query schema: type: string default: utc pattern: ^(utc|Z|\+(?:(?:0\d|1[0-3]):[0-5]\d|14:00)|-(?:(?:0\d|1[01]):[0-5]\d|12:00))$ - name: days in: query description: Daily trailing-window size; defaults to 7 and is ignored for monthly schema: description: Daily trailing-window size; defaults to 7 and is ignored for monthly type: integer maximum: 179 minimum: 1 responses: '200': description: Per-day tool/call counts across all servers in a portal over the selected window content: application/json: schema: type: object properties: result: type: object properties: aggregate: type: boolean end: type: integer granularity: type: string enum: - daily - monthly series: type: array items: properties: count: type: integer day: type: string required: - day - count type: object start: type: integer total: type: integer tz: type: string pattern: ^(utc|Z|\+(?:(?:0\d|1[0-3]):[0-5]\d|14:00)|-(?:(?:0\d|1[01]):[0-5]\d|12:00))$ required: - granularity - aggregate - tz - start - end - series - total success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Analytics x-api-token-group: - MCP Portals Write - MCP Portals Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.portals x-fern-sdk-method-name: portal-tool-call-timeseries x-forge-hidden: true /accounts/{account_id}/access/ai-controls/mcp/analytics/servers/{server_id}/tool-calls/timeseries: get: operationId: mcp-portals-api-server-tool-call-timeseries summary: Per-server MCP tool-call timeseries description: Returns daily or monthly tool-call counts for a server. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c - name: server_id in: path required: true schema: type: string - name: granularity in: query schema: type: string default: daily enum: - daily - monthly - name: aggregate in: query schema: type: string default: 'false' enum: - 'true' - 'false' - name: tz in: query schema: type: string default: utc pattern: ^(utc|Z|\+(?:(?:0\d|1[0-3]):[0-5]\d|14:00)|-(?:(?:0\d|1[01]):[0-5]\d|12:00))$ - name: days in: query description: Daily trailing-window size; defaults to 7 and is ignored for monthly schema: description: Daily trailing-window size; defaults to 7 and is ignored for monthly type: integer maximum: 179 minimum: 1 responses: '200': description: Per-day tool/call counts for a single server over the selected window content: application/json: schema: type: object properties: result: type: object properties: aggregate: type: boolean end: type: integer granularity: type: string enum: - daily - monthly series: type: array items: properties: count: type: integer day: type: string required: - day - count type: object start: type: integer total: type: integer tz: type: string pattern: ^(utc|Z|\+(?:(?:0\d|1[0-3]):[0-5]\d|14:00)|-(?:(?:0\d|1[01]):[0-5]\d|12:00))$ required: - granularity - aggregate - tz - start - end - series - total success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Analytics x-api-token-group: - MCP Portals Write - MCP Portals Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.servers x-fern-sdk-method-name: server-tool-call-timeseries x-forge-hidden: true /accounts/{account_id}/access/ai-controls/mcp/analytics/tool-calls/timeseries: get: operationId: mcp-portals-api-account-tool-call-timeseries summary: Account-global MCP tool-call timeseries description: Returns daily or monthly tool-call counts across the account. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c - name: granularity in: query schema: type: string default: daily enum: - daily - monthly - name: aggregate in: query schema: type: string default: 'false' enum: - 'true' - 'false' - name: tz in: query schema: type: string default: utc pattern: ^(utc|Z|\+(?:(?:0\d|1[0-3]):[0-5]\d|14:00)|-(?:(?:0\d|1[01]):[0-5]\d|12:00))$ - name: days in: query description: Daily trailing-window size; defaults to 7 and is ignored for monthly schema: description: Daily trailing-window size; defaults to 7 and is ignored for monthly type: integer maximum: 179 minimum: 1 responses: '200': description: Per-day tool/call counts across the whole account over the selected window content: application/json: schema: type: object properties: result: type: object properties: aggregate: type: boolean end: type: integer granularity: type: string enum: - daily - monthly series: type: array items: properties: count: type: integer day: type: string required: - day - count type: object start: type: integer total: type: integer tz: type: string pattern: ^(utc|Z|\+(?:(?:0\d|1[0-3]):[0-5]\d|14:00)|-(?:(?:0\d|1[01]):[0-5]\d|12:00))$ required: - granularity - aggregate - tz - start - end - series - total success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Analytics x-api-token-group: - MCP Portals Write - MCP Portals Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.portals x-fern-sdk-method-name: account-tool-call-timeseries x-forge-hidden: true /accounts/{account_id}/access/ai-controls/mcp/portals: get: operationId: mcp-portals-api-list-portals summary: List MCP Portals description: Lists all MCP portals configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: search in: query schema: description: Search by id, name, hostname type: string responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: allow_code_mode: description: 'Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.' type: boolean example: true deprecated: true code_mode: description: 'Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.' type: string example: opt_in enum: - off - opt_in - default_on - enforced created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP portal. type: string example: This is my custom MCP Portal maxLength: 512 hostname: description: Hostname where the MCP portal is available. type: string example: example.com pattern: ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$ id: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP portal. type: string example: My MCP Portal maxLength: 350 secure_web_gateway: description: Route outbound MCP traffic through Zero Trust Secure Web Gateway. type: boolean example: false default: false servers: type: array items: properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true default_disabled: type: boolean description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 on_behalf: type: boolean prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false server_id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: type: array items: properties: enabled: type: boolean name: type: string portal_alias: type: string example: portal-tool-alias portal_description: type: string example: portal-level description server_alias: type: string example: server-tool-alias server_description: type: string example: server-level description required: - name type: object updated_tools: type: array items: properties: enabled: type: boolean name: type: string portal_alias: type: string example: portal-tool-alias portal_description: type: string example: portal-level description server_alias: type: string example: server-tool-alias server_description: type: string example: server-level description required: - name type: object required: - id - name - hostname - auth_type - tools - prompts - server_id type: object x-stainless-collection-type: set required: - id - name - hostname - servers type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal x-api-token-group: - MCP Portals Write - MCP Portals Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.portals x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: mcp-portals-api-create-portals summary: Create a new MCP Portal description: Creates a new MCP portal for managing AI tool access through Cloudflare Access. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c requestBody: content: application/json: schema: type: object properties: allow_code_mode: description: 'Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.' type: boolean example: true deprecated: true code_mode: description: 'Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.' type: string example: opt_in enum: - off - opt_in - default_on - enforced description: description: Optional description of the MCP portal. type: string example: This is my custom MCP Portal maxLength: 512 hostname: description: Hostname where the MCP portal is available. type: string example: example.com pattern: ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$ id: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ name: description: Display name for the MCP portal. type: string example: My MCP Portal maxLength: 350 secure_web_gateway: description: Route outbound MCP traffic through Zero Trust Secure Web Gateway. type: boolean example: false default: false servers: description: MCP servers attached to the portal and their portal-specific settings. type: array items: properties: default_disabled: description: Disable this server by default for clients connecting through the portal. type: boolean on_behalf: description: Use end-user OAuth credentials when connecting this server to the portal. type: boolean server_id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ updated_prompts: description: Portal-specific prompt overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Portal-specific tool overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object required: - server_id type: object maxItems: 80 x-stainless-collection-type: set required: - id - name - hostname responses: '201': description: Returns the created Object content: application/json: schema: type: object properties: result: type: object properties: allow_code_mode: description: 'Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.' type: boolean example: true deprecated: true code_mode: description: 'Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.' type: string example: opt_in enum: - off - opt_in - default_on - enforced created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP portal. type: string example: This is my custom MCP Portal maxLength: 512 hostname: description: Hostname where the MCP portal is available. type: string example: example.com pattern: ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$ id: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP portal. type: string example: My MCP Portal maxLength: 350 secure_web_gateway: description: Route outbound MCP traffic through Zero Trust Secure Web Gateway. type: boolean example: false default: false servers: type: array items: properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true default_disabled: type: boolean description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 on_behalf: type: boolean prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false server_id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: type: array items: properties: enabled: type: boolean name: type: string portal_alias: type: string example: portal-tool-alias portal_description: type: string example: portal-level description server_alias: type: string example: server-tool-alias server_description: type: string example: server-level description required: - name type: object updated_tools: type: array items: properties: enabled: type: boolean name: type: string portal_alias: type: string example: portal-tool-alias portal_description: type: string example: portal-level description server_alias: type: string example: server-tool-alias server_description: type: string example: server-level description required: - name type: object required: - id - name - hostname - auth_type - tools - prompts - server_id type: object x-stainless-collection-type: set required: - id - name - hostname - servers success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal x-api-token-group: - MCP Portals Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.portals x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/ai-controls/mcp/portals/{id}: delete: operationId: mcp-portals-api-delete-portals summary: Delete an MCP Portal description: Deletes an MCP portal from the account. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c - name: id in: path required: true schema: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: allow_code_mode: description: 'Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.' type: boolean example: true deprecated: true code_mode: description: 'Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.' type: string example: opt_in enum: - off - opt_in - default_on - enforced created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP portal. type: string example: This is my custom MCP Portal maxLength: 512 hostname: description: Hostname where the MCP portal is available. type: string example: example.com pattern: ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$ id: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP portal. type: string example: My MCP Portal maxLength: 350 secure_web_gateway: description: Route outbound MCP traffic through Zero Trust Secure Web Gateway. type: boolean example: false default: false required: - id - name - hostname success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal x-api-token-group: - MCP Portals Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.portals x-fern-sdk-method-name: delete x-forge-hidden: true x-forge-require-confirmation: This operation permanently deletes the MCP portal. get: operationId: mcp-portals-api-fetch-gateways summary: Read details of an MCP Portal description: Read the details of a single MCP Portal, including its configured servers. parameters: - name: id in: path required: true schema: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c responses: '200': description: Returns a single object if found content: application/json: schema: type: object properties: result: type: object properties: allow_code_mode: description: 'Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.' type: boolean example: true deprecated: true code_mode: description: 'Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.' type: string example: opt_in enum: - off - opt_in - default_on - enforced created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP portal. type: string example: This is my custom MCP Portal maxLength: 512 hostname: description: Hostname where the MCP portal is available. type: string example: example.com pattern: ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$ id: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP portal. type: string example: My MCP Portal maxLength: 350 secure_web_gateway: description: Route outbound MCP traffic through Zero Trust Secure Web Gateway. type: boolean example: false default: false servers: type: array items: properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true default_disabled: type: boolean description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 on_behalf: type: boolean prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false server_id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: type: array items: properties: enabled: type: boolean name: type: string portal_alias: type: string example: portal-tool-alias portal_description: type: string example: portal-level description server_alias: type: string example: server-tool-alias server_description: type: string example: server-level description required: - name type: object updated_tools: type: array items: properties: enabled: type: boolean name: type: string portal_alias: type: string example: portal-tool-alias portal_description: type: string example: portal-level description server_alias: type: string example: server-tool-alias server_description: type: string example: server-level description required: - name type: object required: - id - name - hostname - auth_type - tools - prompts - server_id type: object x-stainless-collection-type: set required: - id - name - hostname - servers success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal x-api-token-group: - MCP Portals Write - MCP Portals Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.portals x-fern-sdk-method-name: read x-forge-hidden: true put: operationId: mcp-portals-api-update-portals summary: Update an MCP Portal description: Updates an MCP portal configuration. parameters: - name: id in: path required: true schema: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c requestBody: content: application/json: schema: type: object properties: allow_code_mode: description: 'Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.' type: boolean example: true deprecated: true code_mode: description: 'Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.' type: string example: opt_in enum: - off - opt_in - default_on - enforced description: description: Optional description of the MCP portal. type: string example: This is my custom MCP Portal maxLength: 512 hostname: description: Hostname where the MCP portal is available. type: string example: example.com pattern: ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$ name: description: Display name for the MCP portal. type: string example: My MCP Portal maxLength: 350 secure_web_gateway: description: Route outbound MCP traffic through Zero Trust Secure Web Gateway. type: boolean example: false default: false servers: description: MCP servers attached to the portal and their portal-specific settings. type: array items: properties: default_disabled: description: Disable this server by default for clients connecting through the portal. type: boolean on_behalf: description: Use end-user OAuth credentials when connecting this server to the portal. type: boolean server_id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ updated_prompts: description: Portal-specific prompt overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Portal-specific tool overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object required: - server_id type: object maxItems: 80 x-stainless-collection-type: set responses: '200': description: Returns the updated Object content: application/json: schema: type: object properties: result: type: object properties: allow_code_mode: description: 'Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.' type: boolean example: true deprecated: true code_mode: description: 'Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.' type: string example: opt_in enum: - off - opt_in - default_on - enforced created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP portal. type: string example: This is my custom MCP Portal maxLength: 512 hostname: description: Hostname where the MCP portal is available. type: string example: example.com pattern: ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$ id: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP portal. type: string example: My MCP Portal maxLength: 350 secure_web_gateway: description: Route outbound MCP traffic through Zero Trust Secure Web Gateway. type: boolean example: false default: false servers: type: array items: properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true default_disabled: type: boolean description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 on_behalf: type: boolean prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false server_id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: type: array items: properties: enabled: type: boolean name: type: string portal_alias: type: string example: portal-tool-alias portal_description: type: string example: portal-level description server_alias: type: string example: server-tool-alias server_description: type: string example: server-level description required: - name type: object updated_tools: type: array items: properties: enabled: type: boolean name: type: string portal_alias: type: string example: portal-tool-alias portal_description: type: string example: portal-level description server_alias: type: string example: server-tool-alias server_description: type: string example: server-level description required: - name type: object required: - id - name - hostname - auth_type - tools - prompts - server_id type: object x-stainless-collection-type: set required: - id - name - hostname - servers success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal x-api-token-group: - MCP Portals Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.portals x-fern-sdk-method-name: update x-forge-hidden: true x-forge-params: allow_code_mode: default: null secure_web_gateway: default: null /accounts/{account_id}/access/ai-controls/mcp/portals/{portal_id}/servers/{server_id}/effective-redirect-uri: get: operationId: mcp-portals-api-effective-redirect-uri summary: Resolve an MCP server OAuth redirect URI description: "Resolves the OAuth redirect URI to register for a portal and server based on the server's current shared callback setting. Use the returned value when setting up a new manual OAuth registration. This value is for display only: existing manual OAuth registrations continue using their stored redirect URI, so changing callback settings can make this result differ from the URI used at runtime." parameters: - name: portal_id in: path required: true schema: description: Unique identifier for the MCP portal. type: string example: my-mcp-portal maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: server_id in: path required: true schema: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c responses: '200': description: Returns the effective redirect URI and its source. content: application/json: schema: type: object properties: result: type: object properties: redirect_uri: type: string format: uri source: type: string enum: - per_portal - shared_mcp22 required: - redirect_uri - source success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal x-api-token-group: - MCP Portals Write - MCP Portals Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: mcp.portals x-fern-sdk-method-name: resolve-oauth-redirect-uri /accounts/{account_id}/access/ai-controls/mcp/servers: get: operationId: mcp-portals-api-list-servers summary: List MCP Servers description: Lists all MCP servers configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: search in: query schema: description: Search by id, name type: string responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: description: Server-wide prompt capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Server-wide tool capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object required: - id - name - hostname - auth_type - tools - prompts type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Servers x-api-token-group: - MCP Portals Write - MCP Portals Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.servers x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: mcp-portals-api-create-servers summary: Create a new MCP Server description: Creates a new MCP server for connecting to an upstream MCP endpoint. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c requestBody: content: application/json: schema: type: object properties: auth_credentials: description: 'Static credential for the upstream MCP server. For auth_type "bearer", either a raw token string (e.g. "sk-abc123"), which is wrapped server-side as `Authorization: Bearer `, or a JSON-encoded object of the form `{"headers":{"Header-Name":"value",...}}` for custom or multiple static headers (e.g. Cloudflare Access service tokens: `{"headers":{"cf-access-client-id":"...","cf-access-client-secret":"..."}}`).' type: string example: sk-my-bearer-token x-sensitive: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated client_secret: description: Pre-registered OAuth client_secret. Write-only - accepted on create/update when auth_credentials.auth_mode is 'manual'. Stored AES-GCM-encrypted in server_oauth_secrets; never returned by read endpoints. type: string writeOnly: true x-sensitive: true description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false updated_prompts: description: Server-wide prompt capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Server-wide tool capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object required: - id - name - hostname - auth_type responses: '201': description: Returns the created Object content: application/json: schema: type: object properties: result: type: object properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: description: Server-wide prompt capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Server-wide tool capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object required: - id - name - hostname - auth_type - tools - prompts success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Servers x-api-token-group: - MCP Portals Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.servers x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/ai-controls/mcp/servers/{id}: delete: operationId: mcp-portals-api-delete-servers summary: Delete an MCP Server description: Deletes an MCP server from the account. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c - name: id in: path required: true schema: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: description: Server-wide prompt capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Server-wide tool capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object required: - id - name - hostname - auth_type - tools - prompts success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Servers x-api-token-group: - MCP Portals Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.servers x-fern-sdk-method-name: delete x-forge-hidden: true x-forge-require-confirmation: This operation permanently deletes the MCP server, removes it from every portal, and deletes its stored OAuth secrets. get: operationId: mcp-portals-api-fetch-servers summary: Read the details of an MCP Server description: Retrieves an MCP server's configuration and capability sync state. parameters: - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c - name: id in: path required: true schema: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ responses: '200': description: Returns a single object if found content: application/json: schema: type: object properties: result: type: object properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: description: Server-wide prompt capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Server-wide tool capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object required: - id - name - hostname - auth_type - tools - prompts success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Servers x-api-token-group: - MCP Portals Write - MCP Portals Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.servers x-fern-sdk-method-name: read x-forge-hidden: true put: operationId: mcp-portals-api-update-servers summary: Update an MCP Server description: Updates an MCP server's configuration and credentials. parameters: - name: id in: path required: true schema: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c requestBody: content: application/json: schema: type: object properties: auth_credentials: description: 'Static credential for the upstream MCP server. For auth_type "bearer", either a raw token string (e.g. "sk-abc123"), which is wrapped server-side as `Authorization: Bearer `, or a JSON-encoded object of the form `{"headers":{"Header-Name":"value",...}}` for custom or multiple static headers (e.g. Cloudflare Access service tokens: `{"headers":{"cf-access-client-id":"...","cf-access-client-secret":"..."}}`).' type: string example: sk-my-bearer-token x-sensitive: true client_secret: description: Pre-registered OAuth client_secret. Write-only - accepted on create/update when auth_credentials.auth_mode is 'manual'. Stored AES-GCM-encrypted in server_oauth_secrets; never returned by read endpoints. type: string writeOnly: true x-sensitive: true description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false updated_prompts: description: Server-wide prompt capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Server-wide tool capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object responses: '200': description: Returns the updated Object content: application/json: schema: type: object properties: result: type: object properties: auth_config_summary: description: Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value. type: object properties: auth_mode: type: string enum: - dcr - manual client_secret_version: type: number config: type: object properties: authorization_endpoint: type: string issuer: type: string resource: type: string revocation_endpoint: type: string token_endpoint: type: string has_client_secret: type: boolean registration_info: type: object properties: client_id: type: string redirect_uris: type: array items: type: string scope: type: string token_endpoint_auth_method: type: string readOnly: true auth_type: description: Authentication method used to connect to the upstream MCP server. type: string example: unauthenticated enum: - oauth - bearer - unauthenticated authentication_status: description: Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow. type: string enum: - not_required - required - connected - stale - manual readOnly: true created_at: type: string format: date-time readOnly: true created_by: type: string readOnly: true description: description: Optional description of the MCP server. type: string example: This is one remote MCP server maxLength: 512 nullable: true error: type: string readOnly: true error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true hostname: description: URL of the upstream MCP endpoint. type: string format: uri example: https://example.com/mcp id: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ is_shared_oauth_callback_enabled: description: When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true. type: boolean default: false last_successful_sync: type: string format: date-time readOnly: true last_synced: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string readOnly: true name: description: Display name for the MCP server. type: string example: My MCP Server maxLength: 350 prompts: type: array items: additionalProperties: true description: 'Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.' type: object readOnly: true secure_web_gateway: description: Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway. type: boolean example: false default: false status: description: Current sync state of the server type: string example: ready default: waiting enum: - waiting - ready - stale - error readOnly: true tools: type: array items: additionalProperties: true description: 'Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.' type: object readOnly: true updated_prompts: description: Server-wide prompt capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object updated_tools: description: Server-wide tool capability overrides. type: array items: properties: alias: description: Custom name exposed for the capability. type: string example: my-custom-alias maxLength: 40 pattern: ^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$ description: description: Custom description exposed for the capability. type: string enabled: description: Whether the capability is available through the MCP server. type: boolean name: description: Name of the tool or prompt capability to override. type: string required: - name type: object required: - id - name - hostname - auth_type - tools - prompts success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Servers x-api-token-group: - MCP Portals Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.servers x-fern-sdk-method-name: update x-forge-hidden: true x-forge-params: is_shared_oauth_callback_enabled: default: null secure_web_gateway: default: null /accounts/{account_id}/access/ai-controls/mcp/servers/{id}/sync: post: operationId: mcp-portals-api-sync-server summary: Sync MCP Server Capabilities description: Syncs an MCP server's capabilities and returns the updated server state, including any connection errors. parameters: - name: id in: path required: true schema: description: Unique identifier for the MCP server. type: string example: my-mcp-server maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: a86a8f5c339544d7bdc89926de14fb8c responses: '200': description: Sync completed. Check result.status and result.error_details for outcome. content: application/json: schema: type: object properties: result: type: object properties: error: type: string error_details: type: object properties: cause: description: Underlying error message type: string is_upstream: description: True = MCP server returned an error. False = couldn't reach the server type: boolean mcp_code: description: MCP protocol error code type: number retryable: description: Whether the error is transient and worth retrying type: boolean status_code: description: HTTP status code from the server type: number readOnly: true status: type: string enum: - waiting - ready - stale - error success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - MCP Portal Servers x-api-token-group: - MCP Portals Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.mcp_portals x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: mcp.servers x-fern-sdk-method-name: sync x-forge-hidden: true /accounts/{account_id}/access/apps: get: operationId: access-applications-list-access-applications summary: List Access applications description: Lists all Access applications in an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: name in: query schema: description: The name of the app. type: string - name: domain in: query schema: description: The domain of the app. type: string - name: aud in: query schema: description: The aud of the app. type: string - name: target_attributes in: query schema: description: Target Criteria attributes in key=value format. type: string - name: exact in: query schema: description: True for only exact string matches against passed name/domain query parameters. type: boolean - name: search in: query schema: description: Search for apps by other listed query parameters. type: string - $ref: '#/components/parameters/access_page' - $ref: '#/components/parameters/access_per_page' responses: '200': description: List Access applications response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-7' 4XX: description: List Access applications response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-api-token-group: - 'Access: Apps and Policies Revoke' - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications x-fern-sdk-method-name: list x-forge-hidden: true x-stability: beta post: operationId: access-applications-add-an-application summary: Add an Access application description: Adds a new application to Access. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_app_request' responses: '201': description: Add an Access application response content: application/json: schema: allOf: - $ref: '#/components/schemas/access_single_response-8' - properties: result: $ref: '#/components/schemas/access_app_response' type: object 4XX: description: Add an Access application response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications x-fern-sdk-method-name: create x-forge-hidden: true x-stability: beta /accounts/{account_id}/access/apps/{app_id}: delete: operationId: access-applications-delete-an-access-application summary: Delete an Access application description: Deletes an application from Access. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_app_id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Delete an Access application response content: application/json: schema: $ref: '#/components/schemas/access_id_response' 4XX: description: Delete an Access application response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-applications-get-an-access-application summary: Get an Access application description: Fetches information about an Access application. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_app_id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get an Access application response content: application/json: schema: $ref: '#/components/schemas/access_single_response-8' 4XX: description: Get an Access application response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta put: operationId: access-applications-update-an-access-application summary: Update an Access application description: Updates an Access application. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_app_id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_app_request' responses: '200': description: Update an Access application response content: application/json: schema: allOf: - $ref: '#/components/schemas/access_single_response-8' - properties: result: $ref: '#/components/schemas/access_app_response' type: object 4XX: description: Update an Access application response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications x-fern-sdk-method-name: update x-forge-hidden: true x-stability: beta /accounts/{account_id}/access/apps/{app_id}/ca: delete: operationId: access-short-lived-certificate-c-as-delete-a-short-lived-certificate-ca summary: Delete a short-lived certificate CA description: Deletes a short-lived certificate CA. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Delete a short-lived certificate CA response content: application/json: schema: $ref: '#/components/schemas/access_id_response-2' 4XX: description: Delete a short-lived certificate CA response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access short-lived certificate CAs x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.cas x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-short-lived-certificate-c-as-get-a-short-lived-certificate-ca summary: Get a short-lived certificate CA description: Fetches a short-lived certificate CA and its public key. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get a short-lived certificate CA response content: application/json: schema: $ref: '#/components/schemas/access_single_response-5' 4XX: description: Get a short-lived certificate CA response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access short-lived certificate CAs x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.cas x-fern-sdk-method-name: get x-forge-hidden: true post: operationId: access-short-lived-certificate-c-as-create-a-short-lived-certificate-ca summary: Create a short-lived certificate CA description: Generates a new short-lived certificate CA and public key. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Create a short-lived certificate CA response content: application/json: schema: $ref: '#/components/schemas/access_single_response-5' 4XX: description: Create a short-lived certificate CA response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access short-lived certificate CAs x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.cas x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/apps/{app_id}/policies: get: operationId: access-policies-list-access-app-policies summary: List Access application policies description: Lists Access policies configured for an application. Returns both exclusively scoped and reusable policies used by the application. parameters: - name: app_id in: path description: The application ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 200 maximum: 1000 responses: '200': description: List Access application policies response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-8' 4XX: description: List Access application policies response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access application-scoped policies x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.policies x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-policies-create-an-access-policy summary: Create an Access application policy description: Creates a policy applying exclusive to a single application that defines the users or groups who can reach it. We recommend creating a reusable policy instead and subsequently referencing its ID in the application's 'policies' array. parameters: - name: app_id in: path description: The application ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_app_policy_write_request' responses: '201': description: Create an Access application policy response. content: application/json: schema: $ref: '#/components/schemas/access_single_response-9' 4XX: description: Create an Access application policy response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access application-scoped policies x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.policies x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/apps/{app_id}/policies/{policy_id}: delete: operationId: access-policies-delete-an-access-policy summary: Delete an Access application policy description: Deletes an Access policy specific to an application. To delete a reusable policy, use the /accounts/{account_id}/policies/{uid} endpoint. parameters: - name: app_id in: path description: The application ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: policy_id in: path description: The policy ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Delete an Access application policy response. content: application/json: schema: $ref: '#/components/schemas/access_id_response' 4XX: description: Delete an Access application policy response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access application-scoped policies x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.policies x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-policies-get-an-access-policy summary: Get an Access application policy description: Fetches a single Access policy configured for an application. Returns both exclusively owned and reusable policies used by the application. parameters: - name: app_id in: path description: The application ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: policy_id in: path description: The policy ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get an Access policy response. content: application/json: schema: $ref: '#/components/schemas/access_single_response-9' 4XX: description: Get an Access policy response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access application-scoped policies x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.policies x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-policies-update-an-access-policy summary: Update an Access application policy description: Updates an Access policy specific to an application. To update a reusable policy, use the /accounts/{account_id}/policies/{uid} endpoint. parameters: - name: app_id in: path description: The application ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: policy_id in: path description: The policy ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: examples: fido2_key_only: summary: Update a policy requiring a FIDO2 key value: decision: allow include: - everyone: {} mfa_config: allowed_authenticators: - ssh_fido2_key name: Allow SSH users with a FIDO2 key piv_and_fido2_key: summary: Update a policy allowing a PIV key or FIDO2 key value: decision: allow include: - everyone: {} mfa_config: allowed_authenticators: - piv_key - ssh_fido2_key name: Allow SSH users with a PIV key or FIDO2 key piv_only: summary: Update a policy requiring a PIV key value: decision: allow include: - everyone: {} mfa_config: allowed_authenticators: - piv_key name: Allow SSH users with a PIV key schema: $ref: '#/components/schemas/access_app_policy_write_request' responses: '200': description: Update an Access application policy response. content: application/json: schema: $ref: '#/components/schemas/access_single_response-9' 4XX: description: Update an Access application policy response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access application-scoped policies x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.policies x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/apps/{app_id}/policies/{policy_id}/make_reusable: put: operationId: access-policies-convert-reusable summary: Convert an Access application policy to a reusable policy description: Converts an application-scoped policy to a reusable policy. The policy will no longer be exclusively scoped to the application. Further updates to the policy should go through the /accounts/{account_id}/policies/{uid} endpoint. parameters: - name: app_id in: path description: The application ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: policy_id in: path description: The policy ID. required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Convert an Access application policy to a reusable policy content: application/json: schema: $ref: '#/components/schemas/access_response_collection-8' 4XX: description: Convert an Access application policy to a reusable policy failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access application-scoped policies x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.apps.policies.make.reusable x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/apps/{app_id}/revoke_tokens: post: operationId: access-applications-revoke-service-tokens summary: Revoke application tokens description: Revokes all tokens issued for an application. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_app_id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Revoke application tokens response content: application/json: schema: $ref: '#/components/schemas/access_empty_response-2' 4XX: description: Revoke application tokens response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-api-token-group: - 'Access: Apps and Policies Revoke' - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications x-fern-sdk-method-name: revoke-tokens x-forge-hidden: true x-forge-require-confirmation: This operation invalidates every service token for the app. /accounts/{account_id}/access/apps/{app_id}/settings: patch: operationId: access-applications-patch-update-access-application-settings summary: Update Access application settings description: Updates Access application settings. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_app_id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_app_settings_request' responses: '202': description: Update Access application settings response content: application/json: schema: allOf: - $ref: '#/components/schemas/access_single_response_update' 4XX: description: Update Access application settings response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.settings x-fern-sdk-method-name: edit x-forge-hidden: true put: operationId: access-applications-put-update-access-application-settings summary: Update Access application settings description: Updates Access application settings. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_app_id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_app_settings_request' responses: '202': description: Update Access application settings response content: application/json: schema: allOf: - $ref: '#/components/schemas/access_single_response_update' 4XX: description: Update Access application settings response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.settings x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/apps/{app_id}/user_policy_checks: get: operationId: access-applications-test-access-policies summary: Test Access policies description: Tests if a specific user has permission to access an application. parameters: - name: app_id in: path required: true schema: $ref: '#/components/schemas/access_app_id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Test Access policies response content: application/json: schema: $ref: '#/components/schemas/access_policy_check_response' 4XX: description: Test Access policies response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access applications x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.user-policy-checks x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/apps/ca: get: operationId: access-short-lived-certificate-c-as-list-short-lived-certificate-c-as summary: List short-lived certificate CAs description: Lists short-lived certificate CAs and their public keys. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 100 maximum: 1000 responses: '200': description: List short-lived certificate CAs response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-4' 4XX: description: List short-lived certificate CAs response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access short-lived certificate CAs x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.cas x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/authenticator_device_aaguids: get: operationId: access-authenticator-device-aaguids-list summary: List authenticator device AAGUIDs description: Returns a list of Authenticator Device AAGUIDs for MFA configuration. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: List authenticator device AAGUIDs response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-16' 4XX: description: List authenticator device AAGUIDs response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access Authenticator Device AAGUIDs x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.authenticator-device-aaguids x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/bookmarks: get: operationId: access-bookmark-applications-(-deprecated)-list-bookmark-applications summary: List Bookmark applications description: Lists Bookmark applications. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier-3' responses: '200': description: List Bookmark applications response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-14' 4XX: description: List Bookmark applications response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' deprecated: true security: - api_token: [] - api_email: [] api_key: [] tags: - Access Bookmark applications (Deprecated) x-api-token-group: - 'Access: Apps and Policies Revoke' - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-cfDeprecation: description: This endpoint is deprecated in favor of using a specialized Access Application App Type. display: true eol: 2023-03-19T00:00:00Z id: bookmarks_deprecation x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.bookmarks x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/bookmarks/{bookmark_id}: delete: operationId: access-bookmark-applications-(-deprecated)-delete-a-bookmark-application summary: Delete a Bookmark application description: Deletes a Bookmark application. parameters: - name: bookmark_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier-3' requestBody: required: true content: application/json: {} responses: '200': description: Delete a Bookmark application response content: application/json: schema: $ref: '#/components/schemas/access_id_response' 4XX: description: Delete a Bookmark application response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' deprecated: true security: - api_token: [] - api_email: [] api_key: [] tags: - Access Bookmark applications (Deprecated) x-api-token-group: - 'Access: Apps and Policies Write' x-cfDeprecation: description: This endpoint is deprecated in favor of using a specialized Access Application App Type. display: true eol: 2023-03-19T00:00:00Z id: bookmarks_deprecation x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.bookmarks x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-bookmark-applications-(-deprecated)-get-a-bookmark-application summary: Get a Bookmark application description: Fetches a single Bookmark application. parameters: - name: bookmark_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier-3' responses: '200': description: Get a Bookmark application response content: application/json: schema: $ref: '#/components/schemas/access_single_response-13' 4XX: description: Get a Bookmark application response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' deprecated: true security: - api_token: [] - api_email: [] api_key: [] tags: - Access Bookmark applications (Deprecated) x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-cfDeprecation: description: This endpoint is deprecated in favor of using a specialized Access Application App Type. display: true eol: 2023-03-19T00:00:00Z id: bookmarks_deprecation x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.bookmarks x-fern-sdk-method-name: get x-forge-hidden: true post: operationId: access-bookmark-applications-(-deprecated)-create-a-bookmark-application summary: Create a Bookmark application description: Create a new Bookmark application. parameters: - name: bookmark_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier-3' requestBody: required: true content: application/json: {} responses: '200': description: Create a Bookmark application response content: application/json: schema: $ref: '#/components/schemas/access_single_response-13' 4XX: description: Create a Bookmark application response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' deprecated: true security: - api_token: [] - api_email: [] api_key: [] tags: - Access Bookmark applications (Deprecated) x-cfDeprecation: description: This endpoint is deprecated in favor of using a specialized Access Application App Type. display: true eol: 2023-03-19T00:00:00Z id: bookmarks_deprecation x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.bookmarks x-fern-sdk-method-name: create x-forge-hidden: true put: operationId: access-bookmark-applications-(-deprecated)-update-a-bookmark-application summary: Update a Bookmark application description: Updates a configured Bookmark application. parameters: - name: bookmark_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier-3' requestBody: required: true content: application/json: {} responses: '200': description: Update a Bookmark application response content: application/json: schema: $ref: '#/components/schemas/access_single_response-13' 4XX: description: Update a Bookmark application response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' deprecated: true security: - api_token: [] - api_email: [] api_key: [] tags: - Access Bookmark applications (Deprecated) x-api-token-group: - 'Access: Apps and Policies Write' x-cfDeprecation: description: This endpoint is deprecated in favor of using a specialized Access Application App Type. display: true eol: 2023-03-19T00:00:00Z id: bookmarks_deprecation x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.bookmarks x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/certificates: get: operationId: access-mtls-authentication-list-mtls-certificates summary: List mTLS certificates description: Lists all mTLS root certificates. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 50 maximum: 1000 responses: '200': description: List mTLS certificates response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-5' 4XX: description: List mTLS certificates response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access mTLS authentication x-api-token-group: - 'Access: Mutual TLS Certificates Write' - 'Access: Mutual TLS Certificates Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.certificates x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-mtls-authentication-add-an-mtls-certificate summary: Add an mTLS certificate description: Adds a new mTLS root certificate to Access. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: associated_hostnames: $ref: '#/components/schemas/access_associated_hostnames' certificate: description: The certificate content. type: string example: |- -----BEGIN CERTIFICATE----- MIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...N4RI7KKB7nikiuUf8vhULKy5IX10 DrUtmu/B -----END CERTIFICATE----- name: $ref: '#/components/schemas/access_name-7' required: - name - certificate responses: '201': description: Add an mTLS certificate response content: application/json: schema: $ref: '#/components/schemas/access_single_response-6' 4XX: description: Add an mTLS certificate response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access mTLS authentication x-api-token-group: - 'Access: Mutual TLS Certificates Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.certificates x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/certificates/{certificate_id}: delete: operationId: access-mtls-authentication-delete-an-mtls-certificate summary: Delete an mTLS certificate description: Deletes an mTLS certificate. parameters: - name: certificate_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Delete an mTLS certificate response content: application/json: schema: $ref: '#/components/schemas/access_id_response-3' 4XX: description: Delete an mTLS certificate response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access mTLS authentication x-api-token-group: - 'Access: Mutual TLS Certificates Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.certificates x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-mtls-authentication-get-an-mtls-certificate summary: Get an mTLS certificate description: Fetches a single mTLS certificate. parameters: - name: certificate_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get an mTLS certificate response content: application/json: schema: $ref: '#/components/schemas/access_single_response-6' 4XX: description: Get an mTLS certificate response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access mTLS authentication x-api-token-group: - 'Access: Mutual TLS Certificates Write' - 'Access: Mutual TLS Certificates Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.certificates x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-mtls-authentication-update-an-mtls-certificate summary: Update an mTLS certificate description: Updates a configured mTLS certificate. parameters: - name: certificate_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: associated_hostnames: $ref: '#/components/schemas/access_associated_hostnames' name: $ref: '#/components/schemas/access_name-7' required: - associated_hostnames responses: '200': description: Update an mTLS certificate response content: application/json: schema: $ref: '#/components/schemas/access_single_response-6' 4XX: description: Update an mTLS certificate response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access mTLS authentication x-api-token-group: - 'Access: Mutual TLS Certificates Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.certificates x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/certificates/settings: get: operationId: access-mtls-authentication-list-mtls-certificates-hostname-settings summary: List all mTLS hostname settings description: List all mTLS hostname settings for this account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: List mTLS hostname settings response content: application/json: schema: $ref: '#/components/schemas/access_response_collection_hostnames' 4XX: description: List mTLS hostname settings response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access mTLS authentication x-api-token-group: - 'Access: Mutual TLS Certificates Write' - 'Access: Mutual TLS Certificates Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.certificates.settings x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-mtls-authentication-update-an-mtls-certificate-settings summary: Update an mTLS certificate's hostname settings description: Updates an mTLS certificate's hostname settings. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: settings: type: array items: $ref: '#/components/schemas/access_settings' required: - settings responses: '202': description: Update an mTLS certificates hostname settings response content: application/json: schema: $ref: '#/components/schemas/access_response_collection_hostnames' 4XX: description: Update an mTLS certificates hostname settings failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access mTLS authentication x-api-token-group: - 'Access: Mutual TLS Certificates Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.certificates.settings x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/custom_pages: get: operationId: access-custom-pages-list-custom-pages summary: List custom pages description: List custom pages parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 50 maximum: 1000 responses: '200': description: List custom pages response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-10' 4XX: description: List custom pages response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access custom pages x-api-token-group: - 'Access: Custom Pages Write' - 'Access: Custom Pages Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.custom-pages x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-custom-pages-create-a-custom-page summary: Create a custom page description: Create a custom page parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: content: application/json: schema: $ref: '#/components/schemas/access_custom_page' responses: '201': description: Create a custom page response content: application/json: schema: $ref: '#/components/schemas/access_single_response_without_html' '422': description: Template failed content validation; the verdict rides in the result. content: application/json: schema: $ref: '#/components/schemas/access_validate_response' 4XX: description: Create a custom page response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access custom pages x-api-token-group: - 'Access: Custom Pages Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.custom-pages x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/custom_pages/{custom_page_id}: delete: operationId: access-custom-pages-delete-a-custom-page summary: Delete a custom page description: Delete a custom page parameters: - name: custom_page_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Delete a custom page response content: application/json: schema: $ref: '#/components/schemas/access_id_response-3' 4XX: description: Delete a custom page response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access custom pages x-api-token-group: - 'Access: Custom Pages Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.custom-pages x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-custom-pages-get-a-custom-page summary: Get a custom page description: Fetches a custom page and also returns its HTML. parameters: - name: custom_page_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get a custom page response content: application/json: schema: $ref: '#/components/schemas/access_single_response-11' 4XX: description: Get a custom page response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access custom pages x-api-token-group: - 'Access: Custom Pages Write' - 'Access: Custom Pages Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.custom-pages x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-custom-pages-update-a-custom-page summary: Update a custom page description: Update a custom page parameters: - name: custom_page_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: content: application/json: schema: $ref: '#/components/schemas/access_custom_page' responses: '200': description: Update a custom page response content: application/json: schema: $ref: '#/components/schemas/access_single_response_without_html' '422': description: Template failed content validation; the verdict rides in the result. content: application/json: schema: $ref: '#/components/schemas/access_validate_response' 4XX: description: Update a custom page response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access custom pages x-api-token-group: - 'Access: Custom Pages Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.custom-pages x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/custom_pages/validate: post: operationId: access-custom-pages-validate-a-custom-page-template summary: Validate a custom page template description: Validate a Liquid template and return its errors and warnings without persisting it. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: content: application/json: schema: $ref: '#/components/schemas/access_custom_page_validate' responses: '200': description: Validate a custom page template response content: application/json: schema: $ref: '#/components/schemas/access_validate_response' 4XX: description: Validate a custom page template response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access custom pages x-api-token-group: - 'Access: Custom Pages Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.custom-pages x-fern-sdk-method-name: validate x-forge-hidden: true /accounts/{account_id}/access/gateway_ca: get: operationId: access-gateway-ca-list-SSH-ca summary: List SSH Certificate Authorities (CA) description: Lists SSH Certificate Authorities (CA). parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: List SSH Certificate Authorities (CA) response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-6' 4XX: description: List SSH Certificate Authorities (CA) response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Gateway CA x-api-token-group: - 'Access: SSH Auditing Write' - 'Access: SSH Auditing Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.gateway-ca x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-gateway-ca-add-an-SSH-ca summary: Add a new SSH Certificate Authority (CA) description: Adds a new SSH Certificate Authority (CA). parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '201': description: Add a new SSH Certificate Authority (CA) response content: application/json: schema: $ref: '#/components/schemas/access_single_response-7' 4XX: description: Add a new SSH Certificate Authority (CA) response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Gateway CA x-api-token-group: - 'Access: SSH Auditing Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.gateway-ca x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/gateway_ca/{certificate_id}: delete: operationId: access-gateway-ca-delete-an-SSH-ca summary: Delete an SSH Certificate Authority (CA) description: Deletes an SSH Certificate Authority. parameters: - name: certificate_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Delete an SSH Certificate Authority (CA) response content: application/json: schema: $ref: '#/components/schemas/access_id_response' 4XX: description: Delete an SSH Certificate Authority (CA) response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Gateway CA x-api-token-group: - 'Access: SSH Auditing Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.gateway-ca x-fern-sdk-method-name: delete x-forge-hidden: true /accounts/{account_id}/access/groups: get: operationId: access-groups-list-access-groups summary: List Access groups description: Lists all Access groups. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: name in: query schema: description: The name of the group. type: string - name: search in: query schema: description: Search for groups by other listed query parameters. type: string - $ref: '#/components/parameters/access_page' - $ref: '#/components/parameters/access_per_page' responses: '200': description: List Access groups response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-2' 4XX: description: List Access groups response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access groups x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.groups x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-groups-create-an-access-group summary: Create an Access group description: Creates a new Access group. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: exclude: $ref: '#/components/schemas/access_exclude' include: $ref: '#/components/schemas/access_include' is_default: $ref: '#/components/schemas/access_is_default' name: $ref: '#/components/schemas/access_name-6' require: $ref: '#/components/schemas/access_require' required: - name - include responses: '201': description: Create an Access group response content: application/json: schema: $ref: '#/components/schemas/access_single_response-4' 4XX: description: Create an Access group response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access groups x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.groups x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/groups/{group_id}: delete: operationId: access-groups-delete-an-access-group summary: Delete an Access group description: Deletes an Access group. parameters: - name: group_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Delete an Access group response content: application/json: schema: $ref: '#/components/schemas/access_id_response' 4XX: description: Delete an Access group response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access groups x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.groups x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-groups-get-an-access-group summary: Get an Access group description: Fetches a single Access group. parameters: - name: group_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get an Access group response content: application/json: schema: $ref: '#/components/schemas/access_single_response-4' 4XX: description: Get an Access group response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access groups x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.groups x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-groups-update-an-access-group summary: Update an Access group description: Updates a configured Access group. parameters: - name: group_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: exclude: $ref: '#/components/schemas/access_exclude' include: $ref: '#/components/schemas/access_include' is_default: $ref: '#/components/schemas/access_is_default' name: $ref: '#/components/schemas/access_name-6' require: $ref: '#/components/schemas/access_require' required: - name - include responses: '200': description: Update an Access group response content: application/json: schema: $ref: '#/components/schemas/access_single_response-4' 4XX: description: Update an Access group response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access groups x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.groups x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/identity_providers: get: operationId: access-identity-providers-list-access-identity-providers summary: List Access identity providers description: Lists all configured identity providers. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: scim_enabled in: query schema: description: Indicates to Access to only retrieve identity providers that have the System for Cross-Domain Identity Management (SCIM) enabled. type: string example: true - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 200 maximum: 1000 responses: '200': description: List Access identity providers response content: application/json: schema: $ref: '#/components/schemas/access_response_collection' 4XX: description: List Access identity providers response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access identity providers x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.identity-providers x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-identity-providers-add-an-access-identity-provider summary: Add an Access identity provider description: Adds a new identity provider to Access. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_identity-providers' responses: '201': description: Add an Access identity provider response content: application/json: schema: $ref: '#/components/schemas/access_single_response-3' 4XX: description: Add an Access identity provider response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access identity providers x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.identity-providers x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/identity_providers/{identity_provider_id}: delete: operationId: access-identity-providers-delete-an-access-identity-provider summary: Delete an Access identity provider description: Deletes an identity provider from Access. parameters: - name: identity_provider_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Delete an Access identity provider response content: application/json: schema: $ref: '#/components/schemas/access_id_response' 4XX: description: Delete an Access identity provider response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access identity providers x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.identity-providers x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-identity-providers-get-an-access-identity-provider summary: Get an Access identity provider description: Fetches a configured identity provider. parameters: - name: identity_provider_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get an Access identity provider response content: application/json: schema: $ref: '#/components/schemas/access_single_response-3' 4XX: description: Get an Access identity provider response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access identity providers x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.identity-providers x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-identity-providers-update-an-access-identity-provider summary: Update an Access identity provider description: Updates a configured identity provider. parameters: - name: identity_provider_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_identity-providers' responses: '200': description: Update an Access identity provider response content: application/json: schema: $ref: '#/components/schemas/access_single_response-3' 4XX: description: Update an Access identity provider response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access identity providers x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.identity-providers x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/identity_providers/{identity_provider_id}/saml_certificate: post: operationId: access-identity-providers-create-saml-certificate-for-identity-provider summary: Create SAML encryption certificate for Identity Provider description: | Creates a new SAML encryption certificate set and assigns it to the specified SAML Identity Provider. This endpoint is idempotent - if the IdP already has a certificate set assigned, the existing certificate set is returned with a 200 status. **Workflow for enabling SAML encryption:** 1. Call this endpoint to create and assign a certificate set to the IdP 2. Update the IdP configuration (PUT `/identity_providers/{id}`) with: - `config.enable_encryption: true` - `saml_certificate_set_id: ` 3. Configure the certificate's public key in your external SAML Identity Provider parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: identity_provider_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' responses: '200': description: IdP already has a certificate set assigned (idempotent) content: application/json: schema: $ref: '#/components/schemas/access_saml_certificate_set_response' '201': description: SAML certificate set created and assigned to IdP content: application/json: schema: $ref: '#/components/schemas/access_saml_certificate_set_response' '403': description: SAML encryption not enabled for organization content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' '404': description: Identity provider not found content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' 4XX: description: Create SAML certificate for IdP response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access identity providers x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.identity-providers.saml-certificate x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/identity_providers/{identity_provider_id}/scim/groups: get: operationId: access-identity-providers-list-scim-group-resources summary: List SCIM Group resources description: Lists SCIM Group resources synced to Cloudflare via the System for Cross-domain Identity Management (SCIM). parameters: - name: identity_provider_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: cf_resource_id in: query schema: $ref: '#/components/schemas/access_cf_resource_id' explode: true style: form - name: idp_resource_id in: query schema: $ref: '#/components/schemas/access_idp_resource_id' explode: true style: form - name: name in: query schema: $ref: '#/components/schemas/access_name-4' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 100 maximum: 100 responses: '200': description: List SCIM Group resources response content: application/json: schema: $ref: '#/components/schemas/access_scim_groups_response' 4XX: description: List SCIM Group resources response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access identity providers x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.identity-providers.scim.groups x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/identity_providers/{identity_provider_id}/scim/users: get: operationId: access-identity-providers-list-scim-user-resources summary: List SCIM User resources description: Lists SCIM User resources synced to Cloudflare via the System for Cross-domain Identity Management (SCIM). parameters: - name: identity_provider_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: cf_resource_id in: query schema: $ref: '#/components/schemas/access_cf_resource_id-2' explode: true style: form - name: idp_resource_id in: query schema: $ref: '#/components/schemas/access_idp_resource_id-2' explode: true style: form - name: username in: query schema: $ref: '#/components/schemas/access_username' - name: email in: query schema: $ref: '#/components/schemas/access_email' - name: name in: query schema: $ref: '#/components/schemas/access_name-5' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 100 maximum: 100 responses: '200': description: List SCIM User resources response content: application/json: schema: $ref: '#/components/schemas/access_scim_users_response' 4XX: description: List SCIM User resources response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access identity providers x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.identity-providers.scim.users x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/idp_federation_grants: get: operationId: access-idp-federation-grants-list summary: List IdP federation grants description: Lists the IdP federation grants owned by the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: List IdP federation grants response content: application/json: schema: $ref: '#/components/schemas/access_idp_federation_grant_list_response' 4XX: description: List IdP federation grants response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access IdP federation grants x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.idp-federation-grants x-fern-sdk-method-name: list x-forge-hidden: true x-stability: beta post: operationId: access-idp-federation-grants-create summary: Create an IdP federation grant description: | Creates an IdP federation grant for the specified identity provider, making it available for federation to other accounts in the same Cloudflare organization. The account must belong to a Cloudflare organization. One-time pin and Cloudflare-managed identity providers cannot be federated. An account can federate at most five identity providers at a time. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_idp_federation_grant_create_request' responses: '201': description: Create IdP federation grant response content: application/json: schema: $ref: '#/components/schemas/access_idp_federation_grant_response' 4XX: description: Create IdP federation grant response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access IdP federation grants x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.idp-federation-grants x-fern-sdk-method-name: create x-forge-hidden: true x-stability: beta /accounts/{account_id}/access/idp_federation_grants/{grant_id}: delete: operationId: access-idp-federation-grants-delete summary: Delete an IdP federation grant description: | Deletes an IdP federation grant. The identity provider remains in the account, but it is no longer available for federation to other accounts. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: grant_id in: path description: UID of the IdP federation grant. required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Delete IdP federation grant response content: application/json: schema: $ref: '#/components/schemas/access_idp_federation_grant_id_response' '404': description: IdP federation grant does not exist content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' 4XX: description: Delete IdP federation grant response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access IdP federation grants x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.idp-federation-grants x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-idp-federation-grants-get summary: Get an IdP federation grant description: Retrieves a single IdP federation grant by its UID. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: grant_id in: path description: UID of the IdP federation grant. required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get IdP federation grant response content: application/json: schema: $ref: '#/components/schemas/access_idp_federation_grant_response' '404': description: IdP federation grant does not exist content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' 4XX: description: Get IdP federation grant response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access IdP federation grants x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.idp-federation-grants x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta /accounts/{account_id}/access/keys: get: operationId: access-key-configuration-get-the-access-key-configuration summary: Get the Access key configuration description: Gets the Access key rotation settings for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get the Access key configuration response content: application/json: schema: $ref: '#/components/schemas/access_single_response-12' 4XX: description: Get the Access key configuration response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access key configuration x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.keys x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-key-configuration-update-the-access-key-configuration summary: Update the Access key configuration description: Updates the Access key rotation settings for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: key_rotation_interval_days: $ref: '#/components/schemas/access_key_rotation_interval_days' required: - key_rotation_interval_days responses: '200': description: Update the Access key configuration response content: application/json: schema: $ref: '#/components/schemas/access_single_response-12' 4XX: description: Update the Access key configuration response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access key configuration x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.keys x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/keys/rotate: post: operationId: access-key-configuration-rotate-access-keys summary: Rotate Access keys description: Perfoms a key rotation for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Rotate Access keys response content: application/json: schema: $ref: '#/components/schemas/access_single_response-12' 4XX: description: Rotate Access keys response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access key configuration x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.keys x-fern-sdk-method-name: rotate x-forge-hidden: true /accounts/{account_id}/access/logs/access_requests: get: operationId: access-authentication-logs-get-access-authentication-logs summary: Get Access authentication logs description: Gets a list of Access authentication audit logs for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: limit in: query description: The maximum number of log entries to retrieve. schema: type: integer default: 25 example: 25 - name: direction in: query description: The chronological sorting order for the logs. schema: type: string default: desc enum: - desc - asc example: desc - name: since in: query description: The earliest event timestamp to query. schema: type: string format: date-time example: 2020-07-01T05:20:00Z - name: until in: query description: The latest event timestamp to query. schema: type: string format: date-time example: 2020-10-01T05:20:00Z - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 25 - name: email in: query description: | Filter by user email. Match mode is controlled by `emailOp` (preferred) or the legacy `email_exact` flag. - Default (no `emailOp`, `email_exact=false` or unset): substring match — `email=@example.com` returns all events with that domain. - Exact match: set `emailOp=eq` (preferred) or `email_exact=true` — e.g. `email=user@example.com&email_exact=true` returns only that user. - Explicit substring match: set `emailOp=contains` (without `email_exact=true`). When both are set, `email_exact=true` takes precedence and the match is exact. - Exclusion: set `emailOp=neq`. With `email_exact=true` this is an exact-value exclusion; without it, a fuzzy substring exclusion. 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 as a filter. Use `email` instead. 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. `contains` performs a substring (case-sensitive) match. When `email_exact=true` is also set, `email_exact` takes precedence and `contains` is ignored. 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 as a filter (the `user_id` parameter is itself deprecated). 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. When omitted, all fields are returned. schema: type: string example: action,allowed,app_name,country,created_at,ray_id,user_email responses: '200': description: Get Access authentication logs response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-11' 4XX: description: Get Access authentication logs response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access authentication logs x-api-token-group: - 'Access: Audit Logs Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.logs.access-requests x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/logs/jit_requests: get: operationId: access-jit-request-logs-list summary: List Access JIT request logs description: Lists account-wide Access JIT request logs reconstructed from request lifecycle events. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 25 maximum: 1000 - name: status in: query schema: $ref: '#/components/schemas/access_jit_request_status' - name: search in: query description: Case-insensitive search over request ID, requester email, application audience, and application hostname. schema: type: string - name: since in: query description: The earliest request timestamp to query. Defaults to 366 days before the current time. schema: type: string format: date-time - name: until in: query description: The latest request timestamp to query. Defaults to the current time. schema: type: string format: date-time responses: '200': description: Access JIT request logs response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-12' 4XX: description: Access JIT request logs response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access JIT request logs x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.logs.jit-requests x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/logs/jit_requests/{knock_request_id}: get: operationId: access-jit-request-logs-get summary: Get an Access JIT request log description: Gets an account-scoped Access JIT request summary and its lifecycle events in chronological order. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: knock_request_id in: path required: true schema: type: string format: uuid responses: '200': description: Access JIT request log detail response content: application/json: schema: $ref: '#/components/schemas/access_response_single' '404': description: Access JIT request log not found content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' 4XX: description: Access JIT request log detail response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access JIT request logs x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.logs.jit-requests x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/access/logs/scim/updates: get: operationId: access-scim-update-logs-list-access-scim-update-logs summary: List Access SCIM update logs description: Lists Access SCIM update logs that maintain a record of updates made to User and Group resources synced to Cloudflare via the System for Cross-domain Identity Management (SCIM). parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: limit in: query schema: $ref: '#/components/schemas/access_limit' - name: direction in: query schema: $ref: '#/components/schemas/access_direction' example: desc - name: since in: query schema: $ref: '#/components/schemas/access_since' - name: until in: query schema: $ref: '#/components/schemas/access_until' - name: idp_id in: query required: true schema: $ref: '#/components/schemas/access_idp_id' explode: true style: form - name: status in: query schema: $ref: '#/components/schemas/access_status-2' explode: true style: form - name: resource_type in: query schema: $ref: '#/components/schemas/access_resource_type' explode: true style: form - name: request_method in: query schema: $ref: '#/components/schemas/access_request_method' explode: true style: form - name: resource_user_email in: query schema: $ref: '#/components/schemas/access_resource_user_email' explode: true style: form - name: resource_group_name in: query schema: $ref: '#/components/schemas/access_resource_group_name' explode: true style: form - name: cf_resource_id in: query schema: $ref: '#/components/schemas/access_cf_resource_id-3' explode: true style: form - name: idp_resource_id in: query schema: $ref: '#/components/schemas/access_idp_resource_id-3' explode: true style: form - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 20 maximum: 1000 responses: '200': description: Get Access SCIM update logs response content: application/json: schema: $ref: '#/components/schemas/access_scim_update_logs_response' 4XX: description: Get Access SCIM update logs response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access SCIM update logs x-api-token-group: - 'Access: SCIM Logs Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.logs.scim.updates x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/organizations: get: operationId: zero-trust-organization-get-your-zero-trust-organization summary: Get your Zero Trust organization description: Returns the configuration for your Zero Trust organization. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get your Zero Trust organization response content: application/json: schema: $ref: '#/components/schemas/access_single_response' 4XX: description: Get your Zero Trust organization response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust organization x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Revoke' - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.organizations x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: zero-trust-organization-create-your-zero-trust-organization summary: Create your Zero Trust organization description: Sets up a Zero Trust organization for your account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: allow_authenticate_via_warp: $ref: '#/components/schemas/access_allow_authenticate_via_warp' auth_domain: $ref: '#/components/schemas/access_auth_domain' auto_redirect_to_identity: $ref: '#/components/schemas/access_auto_redirect_to_identity' deny_unmatched_requests: $ref: '#/components/schemas/access_deny_unmatched_requests' deny_unmatched_requests_exempted_zone_names: $ref: '#/components/schemas/access_deny_unmatched_requests_exempted_zone_names' is_ui_read_only: $ref: '#/components/schemas/access_is_ui_read_only' login_design: $ref: '#/components/schemas/access_login_design' mfa_config: $ref: '#/components/schemas/access_org_mfa_config' mfa_piv_key_requirements: $ref: '#/components/schemas/access_mfa_piv_key_requirements' mfa_required_for_all_apps: $ref: '#/components/schemas/access_mfa_required_for_all_apps' name: $ref: '#/components/schemas/access_name' session_duration: $ref: '#/components/schemas/access_session_duration' ui_read_only_toggle_reason: $ref: '#/components/schemas/access_ui_read_only_toggle_reason' user_seat_expiration_inactive_time: $ref: '#/components/schemas/access_user_seat_expiration_inactive_time' warp_auth_non_browser_401: $ref: '#/components/schemas/access_warp_auth_non_browser_401' warp_auth_session_duration: $ref: '#/components/schemas/access_warp_auth_session_duration' required: - name - auth_domain responses: '201': description: Create your Zero Trust organization response content: application/json: schema: $ref: '#/components/schemas/access_single_response' 4XX: description: Create your Zero Trust organization response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust organization x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.organizations x-fern-sdk-method-name: create x-forge-hidden: true put: operationId: zero-trust-organization-update-your-zero-trust-organization summary: Update your Zero Trust organization description: Updates the configuration for your Zero Trust organization. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: allow_authenticate_via_warp: $ref: '#/components/schemas/access_allow_authenticate_via_warp' auth_domain: $ref: '#/components/schemas/access_auth_domain' auto_redirect_to_identity: $ref: '#/components/schemas/access_auto_redirect_to_identity' custom_pages: $ref: '#/components/schemas/access_custom_pages' deny_unmatched_requests: $ref: '#/components/schemas/access_deny_unmatched_requests' deny_unmatched_requests_exempted_zone_names: $ref: '#/components/schemas/access_deny_unmatched_requests_exempted_zone_names' is_ui_read_only: $ref: '#/components/schemas/access_is_ui_read_only' login_design: $ref: '#/components/schemas/access_login_design' mfa_config: $ref: '#/components/schemas/access_org_mfa_config' mfa_piv_key_requirements: $ref: '#/components/schemas/access_mfa_piv_key_requirements' mfa_required_for_all_apps: $ref: '#/components/schemas/access_mfa_required_for_all_apps' name: $ref: '#/components/schemas/access_name' session_duration: $ref: '#/components/schemas/access_session_duration' ui_read_only_toggle_reason: $ref: '#/components/schemas/access_ui_read_only_toggle_reason' user_seat_expiration_inactive_time: $ref: '#/components/schemas/access_user_seat_expiration_inactive_time' warp_auth_non_browser_401: $ref: '#/components/schemas/access_warp_auth_non_browser_401' warp_auth_session_duration: $ref: '#/components/schemas/access_warp_auth_session_duration' responses: '200': description: Update your Zero Trust organization response content: application/json: schema: $ref: '#/components/schemas/access_single_response' 4XX: description: Update your Zero Trust organization response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust organization x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.organizations x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/organizations/doh: get: operationId: zero-trust-organization-get-your-zero-trust-organization-doh-settings summary: Get your Zero Trust organization DoH settings description: Returns the DoH settings for your Zero Trust organization. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get your Zero Trust organization DoH settings response content: application/json: schema: allOf: - $ref: '#/components/schemas/access_single_response-2' - properties: result: type: object properties: doh_jwt_duration: description: 'The duration the DoH JWT is valid for. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. Note that the maximum duration for this setting is the same as the key rotation period on the account.' type: string example: 800h type: object 4XX: description: Get your Zero Trust organization DoH settings response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust organization x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Revoke' - 'Access: Organizations, Identity Providers, and Groups Write' - 'Access: Organizations, Identity Providers, and Groups Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.organizations.doh x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: zero-trust-organization-update-your-zero-trust-organization-doh-settings summary: Update your Zero Trust organization DoH settings description: Updates the DoH settings for your Zero Trust organization. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: content: application/json: schema: type: object properties: doh_jwt_duration: $ref: '#/components/schemas/access_doh_jwt_duration' service_token_id: description: The uuid of the service token you want to use for DoH authentication type: string example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415 responses: '201': description: Update your Zero Trust organization DoH settings response content: application/json: schema: allOf: - $ref: '#/components/schemas/access_single_response-2' - properties: result: type: object properties: doh_jwt_duration: $ref: '#/components/schemas/access_doh_jwt_duration' type: object 4XX: description: Update your Zero Trust organization DoH settings response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust organization x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.organizations.doh x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/organizations/revoke_user: post: operationId: zero-trust-organization-revoke-all-access-tokens-for-a-user summary: Revoke all Access tokens for a user description: Revokes a user's access across all applications. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: devices in: query description: When set to `true`, all devices associated with the user will be revoked. schema: type: boolean example: true requestBody: required: true content: application/json: schema: type: object properties: devices: description: When set to `true`, all devices associated with the user will be revoked. type: boolean example: true email: description: The email of the user to revoke. type: string example: test@example.com user_uid: description: The uuid of the user to revoke. type: string example: 699d98642c564d2e855e9661899b7252 warp_session_reauth: description: When set to `true`, the user will be required to re-authenticate to WARP for all Gateway policies that enforce a WARP client session duration. When `false`, the user’s WARP session will remain active type: boolean example: true required: - email responses: '200': description: Revoke all Access tokens for a user response content: application/json: schema: $ref: '#/components/schemas/access_empty_response' 4XX: description: Revoke all Access tokens for a user response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust organization x-api-token-group: - 'Access: Organizations, Identity Providers, and Groups Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.organizations x-fern-sdk-method-name: revoke-users x-forge-hidden: true x-forge-require-confirmation: This operation revokes all access tokens for a user destructively. /accounts/{account_id}/access/policies: get: operationId: access-policies-list-access-reusable-policies summary: List Access reusable policies description: Lists Access reusable policies. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 100 maximum: 1000 responses: '200': description: List Access reusable policies response. content: application/json: schema: $ref: '#/components/schemas/access_response_collection-9' 4XX: description: List Access reusable policies response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access reusable policies x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.policies x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-policies-create-an-access-reusable-policy summary: Create an Access reusable policy description: Creates a new Access reusable policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_policy_req' responses: '201': description: Create an Access reusable policy response. content: application/json: schema: $ref: '#/components/schemas/access_single_response-10' 4XX: description: Create an Access reusable policy response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access reusable policies x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.policies x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/policies/{policy_id}: delete: operationId: access-policies-delete-an-access-reusable-policy summary: Delete an Access reusable policy description: Deletes an Access reusable policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/access_uuid-2' responses: '202': description: Delete an Access reusable policy response. content: application/json: schema: $ref: '#/components/schemas/access_id_response-4' 4XX: description: Delete an Access reusable policy response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access reusable policies x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.policies x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-policies-get-an-access-reusable-policy summary: Get an Access reusable policy description: Fetches a single Access reusable policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/access_uuid-2' responses: '200': description: Get an Access reusable policy response. content: application/json: schema: $ref: '#/components/schemas/access_single_response-10' 4XX: description: Get an Access reusable policy response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access reusable policies x-api-token-group: - 'Access: Apps and Policies Write' - 'Access: Apps and Policies Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.policies x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-policies-update-an-access-reusable-policy summary: Update an Access reusable policy description: Updates a Access reusable policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/access_uuid-2' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_policy_req' responses: '200': description: Update an Access reusable policy response. content: application/json: schema: $ref: '#/components/schemas/access_single_response-10' 4XX: description: Update an Access reusable policy response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access reusable policies x-api-token-group: - 'Access: Apps and Policies Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.policies x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/policy-tests: post: operationId: access-policy-tests summary: Start Access policy test description: Starts an Access policy test. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_policy_init_req' responses: '200': description: Start Access policy test response. content: application/json: schema: $ref: '#/components/schemas/access_policy_init_resp' '400': description: Start Access policy test response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access policy tester x-api-token-group: - 'Access: Policy Test Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.policy-tests x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/policy-tests/{policy_test_id}: get: operationId: access-policy-tests-get-an-update summary: Get the current status of a given Access policy test description: Fetches the current status of a given Access policy test. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: policy_test_id in: path required: true schema: $ref: '#/components/schemas/access_policy_test_id' responses: '200': description: Get an Access policy test update response. content: application/json: schema: $ref: '#/components/schemas/access_policy_update_resp' '400': description: Get an Access policy test update response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access policy tester x-api-token-group: - 'Access: Policy Test Write' - 'Access: Policy Test Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.policy-tests x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/access/policy-tests/{policy_test_id}/users: get: operationId: access-policy-tests-get-a-user-page summary: Get an Access policy test users page description: Fetches a single page of user results from an Access policy test. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: policy_test_id in: path required: true schema: $ref: '#/components/schemas/access_policy_test_id' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: type: integer default: 25 maximum: 1000 - name: status in: query description: Filter users by their policy evaluation status. schema: type: string enum: - success - fail - error responses: '200': description: Get an Access policy tester users page response. content: application/json: schema: $ref: '#/components/schemas/access_policy_users_resp' '400': description: Get an Access policy tester users page response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access policy tester x-api-token-group: - 'Access: Policy Test Write' - 'Access: Policy Test Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.applications.policy-tests.users x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/saml_certificates: get: operationId: access-saml-certificates-list-certificate-sets summary: List SAML certificate sets description: | Returns a paginated list of the organization's SAML encryption certificate sets. Each certificate set includes the current and (if present) previous certificates. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: page in: query description: Page number of paginated results. schema: type: integer default: 1 minimum: 1 - name: per_page in: query description: Maximum number of results per page. schema: type: integer default: 25 maximum: 1000 minimum: 1 - name: id in: query description: Filter by SAML certificate set UID. Accepts a comma-separated list of UIDs. schema: type: string example: a5bb4b3f-c2d1-4e6a-8f9b-1d3e4f5a6b7c,f174e90a-fafe-4643-bbbc-4a0ed4fc8415 responses: '200': description: List SAML certificate sets response content: application/json: schema: $ref: '#/components/schemas/access_certificate_set_list_response' 4XX: description: List SAML certificate sets response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access SAML encryption certificates x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.saml-certificates x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/saml_certificates/{saml_cert_set_id}: get: operationId: access-saml-certificates-get-certificate-set summary: Get SAML certificate set description: Retrieves a specific SAML encryption certificate set by its UID, including both current and previous certificates if available. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: saml_cert_set_id in: path description: UID of the SAML certificate set. required: true schema: $ref: '#/components/schemas/access_uuid' responses: '200': description: Get SAML certificate set response content: application/json: schema: $ref: '#/components/schemas/access_certificate_set_response' '404': description: SAML certificate set does not exist content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' 4XX: description: Get SAML certificate set response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access SAML encryption certificates x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.saml-certificates x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/access/saml_certificates/{saml_cert_set_id}/pem: get: operationId: access-saml-certificates-get-pem summary: Download current certificate in PEM format description: Downloads the current SAML encryption certificate's public key in PEM format for the specified certificate set. This endpoint is useful for providing the certificate to Identity Providers for SAML assertion encryption configuration. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: saml_cert_set_id in: path description: UID of the SAML certificate set. required: true schema: $ref: '#/components/schemas/access_uuid' responses: '200': description: PEM certificate file headers: Content-Disposition: schema: type: string example: attachment; filename="saml_certificate.pem" content: application/x-pem-file: schema: type: string example: | -----BEGIN CERTIFICATE----- MIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT... ...certificate content... -----END CERTIFICATE----- '404': description: SAML certificate set does not exist content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' 4XX: description: Get PEM certificate response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access SAML encryption certificates x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.saml-certificates x-fern-sdk-method-name: get-pem x-forge-hidden: true /accounts/{account_id}/access/saml_certificates/{saml_cert_set_id}/rotate: post: operationId: access-saml-certificates-rotate-certificate summary: Rotate SAML certificate description: | Rotates the SAML encryption certificates within the specified certificate set. This generates a new certificate and moves the current certificate to the previous slot. If a previous certificate exists, it will be deactivated and removed. This endpoint ensures zero-downtime rotation by maintaining both current and previous certificates during the transition period, allowing IdPs time to update their configurations. Automated rotation happens 30 days before a current certificate's expiration. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: saml_cert_set_id in: path description: UID of the SAML certificate set to rotate. required: true schema: $ref: '#/components/schemas/access_uuid' responses: '200': description: Rotate SAML certificate response content: application/json: schema: $ref: '#/components/schemas/access_certificate_set_response' '404': description: SAML certificate set does not exist content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' 4XX: description: Rotate SAML certificate response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access SAML encryption certificates x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.saml-certificates x-fern-sdk-method-name: rotate x-forge-hidden: true /accounts/{account_id}/access/seats: patch: operationId: zero-trust-seats-update-a-user-seat summary: Update a user seat description: Removes a user from a Zero Trust seat when both `access_seat` and `gateway_seat` are set to false. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier-2' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/access_seats_definition' responses: '200': description: Update a user seat response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-13' 4XX: description: Update a user seat response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust seats x-api-token-group: - 'Zero Trust: Seats Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.seats x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/access/service_tokens: get: operationId: access-service-tokens-list-service-tokens summary: List service tokens description: Lists all service tokens. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: name in: query schema: description: The name of the service token. type: string - name: search in: query schema: description: Search for service tokens by other listed query parameters. type: string - $ref: '#/components/parameters/access_page' - $ref: '#/components/parameters/access_per_page' responses: '200': description: List service tokens response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-3' 4XX: description: List service tokens response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access service tokens x-api-token-group: - 'Access: Service Tokens Write' - 'Access: Service Tokens Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.service-tokens x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-service-tokens-create-a-service-token summary: Create a service token description: Generates a new service token. **Note:** This is the only time you can get the Client Secret. If you lose the Client Secret, you will have to rotate the Client Secret or create a new service token. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: client_secret_version: $ref: '#/components/schemas/access_client_secret_version' duration: $ref: '#/components/schemas/access_duration' enabled: $ref: '#/components/schemas/access_enabled' name: $ref: '#/components/schemas/access_name-2' previous_client_secret_expires_at: $ref: '#/components/schemas/access_previous_client_secret_expires_at' required: - name responses: '201': description: Create a service token response content: application/json: schema: $ref: '#/components/schemas/access_create_response' 4XX: description: Create a service token response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access service tokens x-api-token-group: - 'Access: Service Tokens Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.service-tokens x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/service_tokens/{service_token_id}: delete: operationId: access-service-tokens-delete-a-service-token summary: Delete a service token description: Deletes a service token. parameters: - name: service_token_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Delete a service token response content: application/json: schema: $ref: '#/components/schemas/access_single_response-2' 4XX: description: Delete a service token response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access service tokens x-api-token-group: - 'Access: Service Tokens Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.service-tokens x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-service-tokens-get-a-service-token summary: Get a service token description: Fetches a single service token. parameters: - name: service_token_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get a service token response content: application/json: schema: $ref: '#/components/schemas/access_single_response-2' 4XX: description: Get a service token response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access service tokens x-api-token-group: - 'Access: Service Tokens Write' - 'Access: Service Tokens Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.service-tokens x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-service-tokens-update-a-service-token summary: Update a service token description: Updates a configured service token. parameters: - name: service_token_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: client_secret_version: $ref: '#/components/schemas/access_client_secret_version' duration: $ref: '#/components/schemas/access_duration' enabled: $ref: '#/components/schemas/access_enabled' name: $ref: '#/components/schemas/access_name-2' previous_client_secret_expires_at: $ref: '#/components/schemas/access_previous_client_secret_expires_at' responses: '200': description: Update a service token response content: application/json: schema: $ref: '#/components/schemas/access_single_response-2' 4XX: description: Update a service token response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access service tokens x-api-token-group: - 'Access: Service Tokens Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.service-tokens x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/service_tokens/{service_token_id}/refresh: post: operationId: access-service-tokens-refresh-a-service-token summary: Refresh a service token description: Refreshes the expiration of a service token. parameters: - name: service_token_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Refresh a service token response content: application/json: schema: $ref: '#/components/schemas/access_single_response-2' 4XX: description: Refresh a service token response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access service tokens x-api-token-group: - 'Access: Service Tokens Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.service-tokens x-fern-sdk-method-name: refresh x-forge-hidden: true /accounts/{account_id}/access/service_tokens/{service_token_id}/rotate: post: operationId: access-service-tokens-rotate-a-service-token summary: Rotate a service token description: Generates a new Client Secret for a service token and revokes the old one. parameters: - name: service_token_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: content: application/json: schema: type: object properties: previous_client_secret_expires_at: description: The expiration of the previous `client_secret`. If not provided, it defaults to the current timestamp in order to immediately expire the previous secret. type: string format: date-time example: 2014-01-01T05:20:00.12345Z x-auditable: true responses: '200': description: Rotate a service token response content: application/json: schema: $ref: '#/components/schemas/access_create_response' 4XX: description: Rotate a service token response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access service tokens x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.service-tokens x-fern-sdk-method-name: rotate x-forge-hidden: true /accounts/{account_id}/access/tags: get: operationId: access-tags-list-tags summary: List tags description: List tags parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - $ref: '#/components/parameters/access_page' - name: per_page in: query schema: description: Number of results per page. type: integer default: 50 maximum: 1000 responses: '200': description: List tags response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-15' 4XX: description: List tags response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access tags x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.tags x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: access-tags-create-tag summary: Create a tag description: Create a tag parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/access_name-13' responses: '201': description: Create a tag response content: application/json: schema: $ref: '#/components/schemas/access_single_response-14' 4XX: description: Create a tag response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access tags x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.tags x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/tags/{tag_name}: delete: operationId: access-tags-delete-a-tag summary: Delete a tag description: Delete a tag parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: tag_name in: path required: true schema: $ref: '#/components/schemas/access_name-13' responses: '202': description: Delete a tag response content: application/json: schema: $ref: '#/components/schemas/access_name_response' 4XX: description: Delete a tag response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access tags x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.tags x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: access-tags-get-a-tag summary: Get a tag description: Get a tag parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: tag_name in: path required: true schema: $ref: '#/components/schemas/access_name-13' responses: '200': description: Get a tag response content: application/json: schema: $ref: '#/components/schemas/access_single_response-14' 4XX: description: Get a tag response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access tags x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.tags x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: access-tags-update-a-tag summary: Update a tag description: Update a tag parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: tag_name in: path required: true schema: $ref: '#/components/schemas/access_name-13' requestBody: content: application/json: schema: $ref: '#/components/schemas/access_tag_without_app_count' responses: '200': description: Update a tag response content: application/json: schema: $ref: '#/components/schemas/access_single_response-14' 4XX: description: Update a tag response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Access tags x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.tags x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/users: get: operationId: zero-trust-users-get-users summary: Get users description: Gets a list of users for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: name in: query schema: description: The name of the user. type: string - name: email in: query schema: description: The email of the user. type: string - name: search in: query schema: description: Search for users by other listed query parameters. type: string - $ref: '#/components/parameters/access_page' - $ref: '#/components/parameters/access_per_page' responses: '200': description: Get users response content: application/json: schema: $ref: '#/components/schemas/access_response_collection-24' 4XX: description: Get users response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: - 'Access: Audit Logs Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: zero-trust-users-create-user summary: Create a user description: Creates a new user. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: email: $ref: '#/components/schemas/access_email-2' name: $ref: '#/components/schemas/access_name-10' required: - email responses: '201': description: Create user response content: application/json: schema: $ref: '#/components/schemas/access_single_user_response' 4XX: description: Create user response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: null x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/access/users/{user_id}: delete: operationId: zero-trust-users-delete-user summary: Delete a user description: Deletes a specific user for an account. This will also revoke any active seats and tokens for the user. parameters: - name: user_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '202': description: Delete user response content: application/json: schema: $ref: '#/components/schemas/access_delete_user_response' 4XX: description: Delete user response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: null x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: zero-trust-users-get-user summary: Get a user description: Gets a specific user for an account. parameters: - name: user_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get user response content: application/json: schema: $ref: '#/components/schemas/access_single_user_response' 4XX: description: Get user response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: - 'Access: Audit Logs Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: zero-trust-users-update-user summary: Update a user description: Updates a specific user's name for an account. Requires the user's current email as confirmation (email cannot be changed). parameters: - name: user_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' requestBody: required: true content: application/json: schema: type: object properties: email: $ref: '#/components/schemas/access_email-2' name: $ref: '#/components/schemas/access_name-10' required: - name - email responses: '200': description: Update user response content: application/json: schema: $ref: '#/components/schemas/access_single_user_response' 4XX: description: Update user response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: - 'Zero Trust: Seats Write' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/access/users/{user_id}/active_sessions: get: operationId: zero-trust-users-get-active-sessions summary: Get active sessions description: Get active sessions for a single user. parameters: - name: user_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get active sessions response content: application/json: schema: $ref: '#/components/schemas/access_active_sessions_response' 4XX: description: Get active sessions response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: - 'Access: Audit Logs Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users.active-sessions x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/users/{user_id}/active_sessions/{nonce}: get: operationId: zero-trust-users-get-active-session summary: Get single active session description: Get an active session for a single user. parameters: - name: user_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: nonce in: path required: true schema: $ref: '#/components/schemas/access_nonce' responses: '200': description: Get active session response content: application/json: schema: $ref: '#/components/schemas/access_active_session_response' 4XX: description: Get active session response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: - 'Access: Audit Logs Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users.active-sessions x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/access/users/{user_id}/failed_logins: get: operationId: zero-trust-users-get-failed-logins summary: Get failed logins description: Get all failed login attempts for a single user. parameters: - name: user_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get failed logins response content: application/json: schema: $ref: '#/components/schemas/access_failed_login_response' 4XX: description: Get failed logins response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: - 'Access: Audit Logs Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users.failed-logins x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/access/users/{user_id}/last_seen_identity: get: operationId: zero-trust-users-get-last-seen-identity summary: Get last seen identity description: Get last seen identity for a single user. parameters: - name: user_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' responses: '200': description: Get active session response content: application/json: schema: $ref: '#/components/schemas/access_last_seen_identity_response' 4XX: description: Get active session response failure content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: - 'Access: Audit Logs Read' x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.access.users.last-seen-identity x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/access/users/{user_id}/mfa_authenticators/{authenticator_id}: delete: operationId: zero-trust-users-delete-mfa-authenticator summary: Delete a user's MFA device description: Deletes a specific MFA device, including a PIV key or FIDO2 key enrollment, for a user. This action is only available if MFA is turned on for the organization. Successful deletion revokes the enrollment and returns a null result. parameters: - name: user_id in: path required: true schema: $ref: '#/components/schemas/access_uuid' - name: account_id in: path required: true schema: $ref: '#/components/schemas/access_identifier' - name: authenticator_id in: path required: true schema: $ref: '#/components/schemas/access_authenticator_id' responses: '200': description: Delete authenticator response. content: application/json: schema: $ref: '#/components/schemas/access_delete_authenticator_response' 4XX: description: Delete authenticator response failure. content: application/json: schema: $ref: '#/components/schemas/access_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Zero Trust users x-api-token-group: null x-fern-availability: generally-available x-fern-sdk-group-name: zero-trust.users.mfa.authenticators x-fern-sdk-method-name: delete x-forge-hidden: true /accounts/{account_id}/addressing/address_maps: get: operationId: ip-address-management-address-maps-list-address-maps summary: List Address Maps description: List all address maps owned by the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' responses: '200': description: List Address Maps response content: application/json: schema: $ref: '#/components/schemas/addressing_response_collection-3' 4XX: description: List Address Maps response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_response_collection-3' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write - Address Maps Read x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: ip-address-management-address-maps-create-address-map summary: Create Address Map description: Create a new address map under the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: schema: properties: description: $ref: '#/components/schemas/addressing_description-2' enabled: $ref: '#/components/schemas/addressing_enabled' ips: type: array items: $ref: '#/components/schemas/addressing_ip_address' example: - 192.0.2.1 memberships: $ref: '#/components/schemas/addressing_membership_requests' responses: '200': description: Create Address Map response content: application/json: schema: $ref: '#/components/schemas/addressing_full_response' 4XX: description: Create Address Map response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_full_response' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/addressing/address_maps/{address_map_id}: delete: operationId: ip-address-management-address-maps-delete-address-map summary: Delete Address Map description: Delete a particular address map owned by the account. An Address Map must be disabled before it can be deleted. parameters: - name: address_map_id in: path required: true schema: $ref: '#/components/schemas/addressing_address_map_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: {} 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_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: ip-address-management-address-maps-address-map-details summary: Address Map Details description: Show a particular address map owned by the account. parameters: - name: address_map_id in: path required: true schema: $ref: '#/components/schemas/addressing_address_map_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' responses: '200': description: Address Map Details response content: application/json: schema: $ref: '#/components/schemas/addressing_full_response' 4XX: description: Address Map Details response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_full_response' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write - Address Maps Read x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: ip-address-management-address-maps-update-address-map summary: Update Address Map description: Modify properties of an address map owned by the account. parameters: - name: address_map_id in: path required: true schema: $ref: '#/components/schemas/addressing_address_map_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: schema: 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_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/addressing/address_maps/{address_map_id}/accounts/{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' requestBody: required: true content: application/json: {} 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_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps.accounts x-fern-sdk-method-name: delete x-forge-hidden: true put: operationId: ip-address-management-address-maps-add-an-account-membership-to-an-address-map summary: Add an account membership to an Address Map description: Add an account as a member of a particular address map. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' - name: address_map_id in: path required: true schema: $ref: '#/components/schemas/addressing_address_map_identifier' requestBody: required: true content: application/json: {} responses: '200': description: Add an account membership to an Address Map response content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-collection' 4XX: description: Add an account membership to an Address Map response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_api-response-collection' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Address Maps x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps.accounts x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/addressing/address_maps/{address_map_id}/ips/{ip_address}: delete: operationId: ip-address-management-address-maps-remove-an-ip-from-an-address-map summary: Remove an IP from an Address Map description: Remove an IP from a particular address map. parameters: - name: ip_address in: path required: true schema: $ref: '#/components/schemas/addressing_ip_address' - name: address_map_id in: path required: true schema: $ref: '#/components/schemas/addressing_address_map_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: {} 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_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps.ips x-fern-sdk-method-name: delete x-forge-hidden: true put: operationId: ip-address-management-address-maps-add-an-ip-to-an-address-map summary: Add an IP to an Address Map description: Add an IP from a prefix owned by the account to a particular address map. parameters: - name: ip_address in: path required: true schema: $ref: '#/components/schemas/addressing_ip_address' - name: address_map_id in: path required: true schema: $ref: '#/components/schemas/addressing_address_map_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: {} responses: '200': description: Add an IP to an Address Map response content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-collection' 4XX: description: Add an IP to an Address Map response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_api-response-collection' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps.ips x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/addressing/address_maps/{address_map_id}/zones/{zone_id}: delete: operationId: ip-address-management-address-maps-remove-a-zone-membership-from-an-address-map summary: Remove a zone membership from an Address Map description: Remove a zone as a member of a particular address map. parameters: - name: zone_id in: path required: true schema: $ref: '#/components/schemas/addressing_zone_identifier' - name: address_map_id in: path required: true schema: $ref: '#/components/schemas/addressing_address_map_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: {} 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_email: [] api_key: [] tags: - IP Address Management Address Maps x-api-token-group: - Address Maps Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps.zones x-fern-sdk-method-name: delete x-forge-hidden: true put: operationId: ip-address-management-address-maps-add-a-zone-membership-to-an-address-map summary: Add a zone membership to an Address Map description: Add a zone as a member of a particular address map. parameters: - name: zone_id in: path required: true schema: $ref: '#/components/schemas/addressing_zone_identifier' - name: address_map_id in: path required: true schema: $ref: '#/components/schemas/addressing_address_map_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: {} responses: '200': description: Add a zone membership to an Address Map response content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-collection' 4XX: description: Add a zone membership to an Address Map response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_api-response-collection' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Address Maps x-fern-availability: generally-available x-fern-sdk-group-name: addressing.address-maps.zones x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/addressing/leases: get: operationId: ip-address-management-list-leases summary: List Leases description: List all leases owned by the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier-2' responses: '200': description: List Leases response content: application/json: schema: $ref: '#/components/schemas/addressing_response_collection-4' 4XX: description: List Leases response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_response_collection-4' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Leases x-api-token-group: null x-fern-availability: generally-available x-fern-sdk-group-name: addressing.leases x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/addressing/loa_documents: post: operationId: ip-address-management-prefixes-upload-loa-document summary: Upload LOA Document description: Submit LOA document (pdf format) under the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: multipart/form-data: schema: type: object properties: loa_document: description: LOA document to upload. type: string example: '@document.pdf' required: - loa_document responses: '201': description: Upload LOA Document response content: application/json: schema: $ref: '#/components/schemas/addressing_loa_upload_response' 4XX: description: Upload LOA Document response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_loa_upload_response' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Prefixes x-api-token-group: - Magic Transit Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.loa-documents x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/addressing/loa_documents/{loa_document_id}/download: get: operationId: ip-address-management-prefixes-download-loa-document summary: Download LOA Document description: Download specified LOA document under the account. parameters: - name: loa_document_id in: path required: true schema: $ref: '#/components/schemas/addressing_loa_document_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' responses: '200': description: Download LOA Document response content: application/pdf: schema: type: string format: binary 4XX: description: Download LOA Document response failure content: application/json: schema: allOf: - {} - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Prefixes x-api-token-group: - Magic Transit Read - Magic Transit Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.loa-documents x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/addressing/prefixes: get: operationId: ip-address-management-prefixes-list-prefixes summary: List Prefixes description: List all prefixes owned by the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' responses: '200': description: List Prefixes response content: application/json: schema: $ref: '#/components/schemas/addressing_response_collection' 4XX: description: List Prefixes response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_response_collection' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Prefixes x-api-token-group: - Magic Transit Read - Magic Transit Write - 'IP Prefixes: Write' - 'IP Prefixes: Read' - 'IP Prefixes: BGP On Demand Write' - 'IP Prefixes: BGP On Demand Read' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: ip-address-management-prefixes-add-prefix summary: Add Prefix description: Add a new prefix under the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: schema: 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_email: [] api_key: [] tags: - IP Address Management Prefixes x-api-token-group: null x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}: delete: operationId: ip-address-management-prefixes-delete-prefix summary: Delete Prefix description: Delete an unapproved prefix owned by the account. parameters: - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: {} 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_email: [] api_key: [] tags: - IP Address Management Prefixes x-api-token-group: - Magic Transit Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: ip-address-management-prefixes-prefix-details summary: Prefix Details description: List a particular prefix owned by the account. parameters: - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' responses: '200': description: Prefix Details response content: application/json: schema: $ref: '#/components/schemas/addressing_single_response' 4XX: description: Prefix Details response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_single_response' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Prefixes x-api-token-group: - Magic Transit Read - Magic Transit Write - 'IP Prefixes: Write' - 'IP Prefixes: Read' - 'IP Prefixes: BGP On Demand Write' - 'IP Prefixes: BGP On Demand Read' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: ip-address-management-prefixes-update-prefix-description summary: Update Prefix Description description: Modify the description for a prefix owned by the account. parameters: - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: schema: 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_email: [] api_key: [] tags: - IP Address Management Prefixes x-api-token-group: - Magic Transit Write - 'IP Prefixes: Write' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/prefixes: get: operationId: ip-address-management-prefixes-list-bgp-prefixes summary: List BGP Prefixes description: List all BGP Prefixes within the specified IP Prefix. BGP Prefixes are used to control which specific subnets are advertised to the Internet. It is possible to advertise subnets more specific than an IP Prefix by creating more specific BGP Prefixes. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' responses: '200': description: List BGP Prefixes response content: application/json: schema: $ref: '#/components/schemas/addressing_response_collection_bgp' 4XX: description: List BGP Prefixes response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_response_collection_bgp' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management BGP Prefixes x-api-token-group: - Magic Transit Read - Magic Transit Write - 'IP Prefixes: Write' - 'IP Prefixes: Read' - 'IP Prefixes: BGP On Demand Write' - 'IP Prefixes: BGP On Demand Read' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.bgp-prefixes x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: ip-address-management-prefixes-create-bgp-prefix summary: Create BGP Prefix description: Create a BGP prefix, controlling the BGP advertisement status of a specific subnet. When created, BGP prefixes are initially withdrawn, and can be advertised with the Update BGP Prefix API. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/addressing_bgp_prefix_create' responses: '200': description: Create BGP Prefix response content: application/json: schema: $ref: '#/components/schemas/addressing_single_response_bgp' 4XX: description: Create BGP Prefix response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_single_response_bgp' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management BGP Prefixes x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.bgp-prefixes x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/prefixes/{bgp_prefix_id}: delete: operationId: ip-address-management-prefixes-delete-bgp-prefix summary: Delete BGP Prefix description: Delete a BGP Prefix associated with the specified IP Prefix. A BGP Prefix must be withdrawn before it can be deleted. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: bgp_prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_bgp_prefix_identifier' responses: '200': description: Delete BGP Prefix response content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-common' 4XX: description: Delete BGP Prefix response failure content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management BGP Prefixes x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.bgp-prefixes x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: ip-address-management-prefixes-fetch-bgp-prefix summary: Fetch BGP Prefix description: Retrieve a single BGP Prefix according to its identifier parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: bgp_prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_bgp_prefix_identifier' responses: '200': description: Fetch BGP Prefix response content: application/json: schema: $ref: '#/components/schemas/addressing_single_response_bgp' 4XX: description: Fetch BGP Prefix response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_single_response_bgp' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management BGP Prefixes x-api-token-group: - Magic Transit Read - Magic Transit Write - 'IP Prefixes: Write' - 'IP Prefixes: Read' - 'IP Prefixes: BGP On Demand Write' - 'IP Prefixes: BGP On Demand Read' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.bgp-prefixes x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: ip-address-management-prefixes-update-bgp-prefix summary: Update BGP Prefix description: Update the properties of a BGP Prefix, such as the on demand advertisement status (advertised or withdrawn). parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: bgp_prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_bgp_prefix_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/addressing_bgp_prefix_update_advertisement' responses: '200': description: Update BGP Prefix response content: application/json: schema: $ref: '#/components/schemas/addressing_single_response_bgp' 4XX: description: Update BGP Prefix response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_single_response_bgp' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management BGP Prefixes x-api-token-group: - Magic Transit Write - 'IP Prefixes: Write' - 'IP Prefixes: BGP On Demand Write' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.bgp-prefixes x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/status: get: operationId: ip-address-management-dynamic-advertisement-get-advertisement-status summary: Get Advertisement Status description: | View the current advertisement state for a prefix. **Deprecated:** Prefer the BGP Prefixes endpoints, which additionally allow for advertising and withdrawing subnets of an 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: 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_email: [] api_key: [] tags: - IP Address Management Dynamic Advertisement x-api-token-group: - Magic Transit Read - Magic Transit Write - 'IP Prefixes: Write' - 'IP Prefixes: Read' - 'IP Prefixes: BGP On Demand Write' - 'IP Prefixes: BGP On Demand Read' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.advertisement-status x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: ip-address-management-dynamic-advertisement-update-prefix-dynamic-advertisement-status summary: Update Prefix Dynamic Advertisement Status description: | Advertise or withdraw the BGP route for a prefix. **Deprecated:** Prefer the BGP Prefixes endpoints, which additionally allow for advertising and withdrawing subnets of an 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: 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_email: [] api_key: [] tags: - IP Address Management Dynamic Advertisement x-api-token-group: - Magic Transit Write - 'IP Prefixes: Write' - 'IP Prefixes: BGP On Demand Write' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.advertisement-status x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}/bindings: get: operationId: ip-address-management-service-bindings-list-service-bindings summary: List Service Bindings description: | List the Cloudflare services this prefix is currently bound to. Traffic sent to an address within an IP prefix will be routed to the Cloudflare service of the most-specific Service Binding matching the address. **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. 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' 4XX: description: List Service Bindings response failure content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Service Bindings x-api-token-group: - 'IP Prefixes: Write' - 'IP Prefixes: Read' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.service-bindings x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: ip-address-management-service-bindings-create-service-binding summary: Create Service Binding description: | Creates a new Service Binding, routing traffic to IPs within the given CIDR to a service running on Cloudflare's network. **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. 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' 4XX: description: Create Service Binding response failure content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Service Bindings x-api-token-group: - 'IP Prefixes: Write' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.service-bindings x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}/bindings/{binding_id}: delete: operationId: ip-address-management-service-bindings-delete-service-binding summary: Delete Service Binding description: Delete a Service Binding parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: binding_id in: path required: true schema: $ref: '#/components/schemas/addressing_service_binding_identifier' responses: '200': description: Service Binding deleted content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-common' 4XX: description: Delete Service Binding response failure content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Service Bindings x-api-token-group: - 'IP Prefixes: Write' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.service-bindings x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: ip-address-management-service-bindings-get-service-binding summary: Get Service Binding description: Fetch a single Service Binding parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: binding_id in: path required: true schema: $ref: '#/components/schemas/addressing_service_binding_identifier' responses: '200': description: The Service Binding with the requested ID content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_api-response-common' - properties: result: $ref: '#/components/schemas/addressing_service_binding' 4XX: description: Get Service Binding response failure content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Service Bindings x-api-token-group: - 'IP Prefixes: Write' - 'IP Prefixes: Read' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.service-bindings x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}/delegations: get: operationId: ip-address-management-prefix-delegation-list-prefix-delegations summary: List Prefix Delegations description: List all delegations for a given account IP prefix. parameters: - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' responses: '200': description: List Prefix Delegations response content: application/json: schema: $ref: '#/components/schemas/addressing_response_collection-2' 4XX: description: List Prefix Delegations response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_response_collection-2' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Prefix Delegation x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.delegations x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: ip-address-management-prefix-delegation-create-prefix-delegation summary: Create Prefix Delegation description: Create a new account delegation for a given IP prefix. parameters: - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: schema: properties: cidr: $ref: '#/components/schemas/addressing_cidr' delegated_account_id: $ref: '#/components/schemas/addressing_delegated_account_identifier' required: - cidr - delegated_account_id responses: '200': description: Create Prefix Delegation response content: application/json: schema: $ref: '#/components/schemas/addressing_single_response-2' 4XX: description: Create Prefix Delegation response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_single_response-2' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Prefix Delegation x-api-token-group: - 'IP Prefixes: Write' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.delegations x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}/delegations/{delegation_id}: delete: operationId: ip-address-management-prefix-delegation-delete-prefix-delegation summary: Delete Prefix Delegation description: Delete an account delegation for a given IP prefix. parameters: - name: delegation_id in: path required: true schema: $ref: '#/components/schemas/addressing_delegation_identifier' - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' requestBody: required: true content: application/json: {} 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_email: [] api_key: [] tags: - IP Address Management Prefix Delegation x-api-token-group: - 'IP Prefixes: Write' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.delegations x-fern-sdk-method-name: delete x-forge-hidden: true /accounts/{account_id}/addressing/prefixes/{prefix_id}/validate: post: operationId: ip-address-management-prefixes-validate-prefix summary: Validate Prefix description: Triggers a new prefix validation. The checks are run asynchronously and include IRR, RPKI, and prefix ownership. parameters: - name: prefix_id in: path required: true schema: $ref: '#/components/schemas/addressing_prefix_identifier' - name: account_id in: path required: true schema: $ref: '#/components/schemas/addressing_account_identifier' responses: '202': description: Validate Prefix response content: application/json: schema: $ref: '#/components/schemas/addressing_single_response' 4XX: description: Validate Prefix response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/addressing_single_response' - $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Prefixes x-api-token-group: - Magic Transit Write - 'IP Prefixes: Write' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.prefixes.validate x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/addressing/regional_hostnames/regions: get: operationId: dls-account-regional-hostnames-list-regions summary: List Regions description: List all Regional Services regions available for use by this account. parameters: - $ref: '#/components/parameters/dls_account_id' responses: '200': description: List regions response content: application/json: schema: allOf: - $ref: '#/components/schemas/dls_api-response-collection' - properties: result: type: array items: properties: key: $ref: '#/components/schemas/dls_region_key' label: description: Human-readable text label for the region type: string example: Canada type: object 4XX: description: Failure to list regions content: application/json: schema: allOf: - $ref: '#/components/schemas/dls_api-response-common-failure' security: - api_email: [] api_key: [] - api_token: [] tags: - DLS Regional Services x-api-token-group: - DNS Read - DNS Write x-fern-availability: generally-available x-fern-sdk-group-name: addressing.regional_hostnames.regions x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/addressing/services: get: operationId: ip-address-management-service-bindings-list-services summary: List Services description: | Bring-Your-Own IP (BYOIP) prefixes onboarded to Cloudflare must be bound to a service running on the Cloudflare network to enable a Cloudflare product on the IP addresses. This endpoint can be used as a reference of available services on the Cloudflare network, and their service IDs. 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' 4XX: description: List Services response failure content: application/json: schema: $ref: '#/components/schemas/addressing_api-response-common-failure' security: - api_email: [] api_key: [] tags: - IP Address Management Service Bindings x-api-token-group: - 'IP Prefixes: Write' - 'IP Prefixes: Read' x-fern-availability: generally-available x-fern-sdk-group-name: addressing.services x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/agent-memory/namespaces: get: operationId: agent-memory-namespace-list summary: List namespaces description: Lists all namespaces for the given account. Results are paginated. parameters: - name: per_page in: query schema: description: Number of results per page. type: integer example: 20 maximum: 1000 minimum: 1 - name: order in: query schema: description: Field to order the results by. type: string example: id enum: - id - name - name: direction in: query schema: description: Direction to sort the results in. type: string example: asc enum: - asc - desc - name: cursor in: query schema: description: Pagination cursor returned by a previous list response. type: string responses: '200': description: A List of namespaces. content: application/json: schema: type: object properties: errors: description: Always empty for a successful response. type: array items: properties: code: description: Machine-readable status code. type: number example: 1003 documentation_url: description: Link to relevant documentation, when available. type: string message: description: Human-readable message describing the error or status. type: string example: namespace not found source: type: object properties: pointer: description: JSON pointer to the request field that caused the error. type: string example: /name required: - code - message type: object example: [] messages: description: Informational, non-error messages, if any. type: array items: properties: code: description: Machine-readable status code. type: number example: 1003 documentation_url: description: Link to relevant documentation, when available. type: string message: description: Human-readable message describing the error or status. type: string example: namespace not found source: type: object properties: pointer: description: JSON pointer to the request field that caused the error. type: string example: /name required: - code - message type: object example: [] result: type: array items: properties: created_at: description: Time the namespace was created. type: string format: date-time example: 2025-09-21T14:30:00Z id: description: Unique identifier of the namespace. type: string example: 01JSGCEXAMP1E0000000000000 name: description: Namespace name. type: string example: support-agent updated_at: description: Time the namespace was last updated. type: string format: date-time example: 2025-09-21T14:30:00Z required: - id - name - created_at - updated_at type: object result_info: type: object properties: count: description: Number of results returned in this page. type: integer example: 1 cursor: description: Opaque cursor for the next page; omitted on the last page. type: string example: 01JSGCEXAMP1E0000000000000 per_page: description: Page size used for this query. type: integer example: 20 success: description: Always true for a successful response. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 🔴 (fact) Prefers dark mode: The user prefers dark mode in all editors. 🟡 (task) Finish onboarding: Complete the onboarding checklist. required: - summary success: description: Always true for a successful response. 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. enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Memory x-fern-availability: beta x-fern-sdk-group-name: agent-memory x-fern-sdk-method-name: summary /accounts/{account_id}/ai-gateway/billing/credit-balance: get: operationId: aig-billing-get-credit-balance summary: Get credit balance description: Retrieve the current credit balance, payment method info, and top-up configuration. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string responses: '200': description: Credit balance retrieved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_GetCreditBalanceResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing x-fern-sdk-method-name: credit-balance x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/invoice-history: get: operationId: aig-billing-get-invoice-history summary: Get invoice history description: Retrieve a list of past invoices with pagination, optionally filtered by type. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string - name: type in: query description: 'Filter invoice type: auto, manual, or all.' schema: description: 'Filter invoice type: auto, manual, or all.' type: string example: all default: all enum: - auto - all - manual responses: '200': description: Invoice history retrieved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_GetInvoiceHistoryResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing x-fern-sdk-method-name: invoice-history x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/invoice-preview: get: operationId: aig-billing-get-invoice-preview summary: Get invoice preview description: Retrieve a preview of the upcoming invoice including line items and tax. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string responses: '200': description: Invoice preview retrieved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_GetInvoicePreviewResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing x-fern-sdk-method-name: invoice-preview x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/spending-limit: delete: operationId: aig-billing-delete-spending-limit summary: Delete spending limit description: Remove the spending limit for the account. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string responses: '200': description: Spending limit deleted. content: application/json: schema: $ref: '#/components/schemas/aig-billing_DeleteSpendingLimitResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing.spending-limit x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-billing-get-spending-limit summary: Get spending limit description: Retrieve the current spending limit configuration for the account. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string responses: '200': description: Spending limit configuration retrieved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_GetSpendingLimitResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing.spending-limit x-fern-sdk-method-name: get x-forge-hidden: true post: operationId: aig-billing-set-spending-limit summary: Set spending limit (deprecated) description: 'Deprecated: spending limits can no longer be created, enabled, or modified and this endpoint always responds 403. Use the new AI Gateway spend limits instead: https://developers.cloudflare.com/ai-gateway/features/spend-limits/. Existing limits can be removed via DELETE /spending-limit.' parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: amount: description: Spending limit amount in cents (min 100). type: integer example: 10000 minimum: 100 duration: description: Spending limit duration. type: string example: monthly enum: - daily - weekly - monthly strategy: description: Spending limit strategy. type: string example: fixed enum: - fixed - sliding additionalProperties: false required: - amount - strategy - duration responses: '201': description: Spending limit created. content: application/json: schema: $ref: '#/components/schemas/aig-billing_SetSpendingLimitResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' deprecated: true security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing.spending-limit x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/topup: post: operationId: aig-billing-create-topup summary: Create a top-up description: Create a credit top-up for the given account, charged to the account's default payment method. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: amount: description: Top-up amount in cents (min 1000). type: integer example: 5000 minimum: 1000 additionalProperties: false required: - amount responses: '200': description: Top-up initiated successfully. content: application/json: schema: $ref: '#/components/schemas/aig-billing_CreateTopupResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '402': description: Payment required — the payment method was declined. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing.topup x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/topup/config: delete: operationId: aig-billing-delete-topup-config summary: Delete auto top-up configuration description: Remove the auto top-up configuration for the account. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string responses: '200': description: Auto top-up configuration deleted. content: application/json: schema: $ref: '#/components/schemas/aig-billing_DeleteTopupConfigResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing.topup.config x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-billing-get-topup-config summary: Get auto top-up configuration description: Retrieve the current auto top-up threshold, amount, and any error state. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string responses: '200': description: Auto top-up configuration retrieved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_GetTopupConfigResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing.topup.config x-fern-sdk-method-name: get x-forge-hidden: true post: operationId: aig-billing-set-topup-config summary: Set auto top-up configuration description: Configure auto top-up with a balance threshold and top-up amount. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: amount: description: Auto top-up amount in cents (min 1000). type: integer example: 5000 minimum: 1000 threshold: description: Balance threshold in cents that triggers auto top-up (min 500). type: integer example: 500 minimum: 500 additionalProperties: false required: - threshold - amount responses: '200': description: Auto top-up configuration saved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_SetTopupConfigResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing.topup.config x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/topup/eligibility: post: operationId: aig-billing-topup-eligibility summary: Get top-up eligibility description: Determine whether an account can self-serve a credit top-up, and if not, why. The dashboard forwards the account's payment-method list in the body; the reason logic is owned here. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: payment_methods: description: Account-level payment methods, forwarded by the dashboard. type: array items: properties: default: description: Whether this is the account default payment method. type: boolean example: true last_four: description: Last 4 digits, for display copy only. type: string example: '4242' type: description: 'Payment-method type. Absent or unrecognized is treated as non-card (does not error). Known values: PAYPAL, CREDIT_CARD, APPLE_PAY, GOOGLE_PAY, ACH_DIRECT_DEBIT, SEPA_DEBIT, CASHAPP, LINK, CRYPTO.' type: string example: CREDIT_CARD type: object maxItems: 100 responses: '200': description: Eligibility determined. content: application/json: schema: $ref: '#/components/schemas/aig-billing_GetTopupEligibilityResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: ai-gateway.billing.topup x-fern-sdk-method-name: eligibility x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/topup/limits: get: operationId: aig-billing-get-topup-limits summary: Get account top-up limits description: Retrieve the minimum and maximum allowed top-up amounts (in cents) for this account. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string responses: '200': description: Top-up limits retrieved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_GetTopupLimitsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing x-fern-sdk-method-name: get-topup-limits x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/topup/status: post: operationId: aig-billing-check-topup-status summary: Check top-up status description: Get the payment processing status of a top-up by its invoice ID. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: payment_intent_id: description: Stripe invoice ID to check status for. type: string example: in_1abc additionalProperties: false required: - payment_intent_id responses: '200': description: Top-up status retrieved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_TopupStatusResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing.topup x-fern-sdk-method-name: status x-forge-hidden: true /accounts/{account_id}/ai-gateway/billing/usage-history: get: operationId: aig-billing-get-usage-history summary: Get usage history description: Retrieve aggregated usage meter event summaries for the given time range. parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string - name: value_grouping_window in: query description: Grouping window for usage data. required: true schema: description: Grouping window for usage data. type: string example: day enum: - day - hour - name: start_time in: query description: Start time as Unix timestamp in milliseconds. schema: description: Start time as Unix timestamp in milliseconds. type: number example: 1700000000000 nullable: true - name: end_time in: query description: End time as Unix timestamp in milliseconds. schema: description: End time as Unix timestamp in milliseconds. type: number example: 1700086400000 nullable: true responses: '200': description: Usage history retrieved. content: application/json: schema: $ref: '#/components/schemas/aig-billing_GetUsageHistoryResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/aig-billing_ErrorResponse' security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.billing x-fern-sdk-method-name: usage-history x-forge-hidden: true /accounts/{account_id}/ai-gateway/custom-providers: get: operationId: aig-config-list-account-provider summary: List Account Providers description: Lists all AI Gateway evaluator types configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: beta in: query schema: type: boolean - name: enable in: query schema: type: boolean - name: search in: query schema: description: Search by id, name, slug type: string responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: base_url: type: string format: uri beta: type: boolean created_at: type: string format: date-time curl_example: type: string description: type: string enable: type: boolean headers: type: string maxLength: 8192 id: type: string format: uuid js_example: type: string link: type: string logo: type: string modified_at: type: string format: date-time name: type: string position: type: integer slug: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - id - created_at - modified_at - name - slug - base_url type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Providers x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: aig-config-create-account-provider summary: Create a new Account Provider description: Creates a new AI Gateway. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 requestBody: content: application/json: schema: type: object properties: base_url: type: string format: uri beta: type: boolean curl_example: type: string description: type: string enable: type: boolean headers: type: string maxLength: 8192 js_example: type: string link: type: string name: type: string position: type: integer slug: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - name - slug - base_url responses: '200': description: Returns the created Object content: application/json: schema: type: object properties: result: type: object properties: base_url: type: string format: uri beta: type: boolean created_at: type: string format: date-time curl_example: type: string description: type: string enable: type: boolean headers: type: string maxLength: 8192 id: type: string format: uuid js_example: type: string link: type: string logo: type: string modified_at: type: string format: date-time name: type: string position: type: integer slug: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - id - created_at - modified_at - name - slug - base_url success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Providers x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/custom-providers/{id}: delete: operationId: aig-config-delete-account-provider summary: Delete a Account Provider description: Deletes an AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: base_url: type: string format: uri beta: type: boolean created_at: type: string format: date-time curl_example: type: string description: type: string enable: type: boolean headers: type: string maxLength: 8192 id: type: string format: uuid js_example: type: string link: type: string logo: type: string modified_at: type: string format: date-time name: type: string position: type: integer slug: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - id - created_at - modified_at - name - slug - base_url success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Providers x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-config-fetch-account-provider summary: Fetch a Account Provider description: Retrieves details for a specific AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Returns a single object if found content: application/json: schema: type: object properties: result: type: object properties: base_url: type: string format: uri beta: type: boolean created_at: type: string format: date-time curl_example: type: string description: type: string enable: type: boolean headers: type: string maxLength: 8192 id: type: string format: uuid js_example: type: string link: type: string logo: type: string modified_at: type: string format: date-time name: type: string position: type: integer slug: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - id - created_at - modified_at - name - slug - base_url success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Providers x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: aig-config-update-account-provider summary: Update a Account Provider description: Updates an existing AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: base_url: type: string format: uri beta: type: boolean curl_example: type: string description: type: string enable: type: boolean headers: type: string maxLength: 8192 js_example: type: string link: type: string logo: type: string name: type: string position: type: integer slug: type: string pattern: ^[a-zA-Z0-9_-]+$ responses: '200': description: Returns the updated Object content: application/json: schema: type: object properties: result: type: object properties: base_url: type: string format: uri beta: type: boolean created_at: type: string format: date-time curl_example: type: string description: type: string enable: type: boolean headers: type: string maxLength: 8192 id: type: string format: uuid js_example: type: string link: type: string logo: type: string modified_at: type: string format: date-time name: type: string position: type: integer slug: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - id - created_at - modified_at - name - slug - base_url success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Providers x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/ai-gateway/custom-providers/costs: get: operationId: aig-config-list-account-provider-cost summary: List Account Provider Costs description: Lists all AI Gateway evaluator types configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: enable in: query schema: type: boolean - name: account_provider_id in: query schema: type: string format: uuid - name: model_rule in: query schema: type: string default: equals enum: - equals - starts-with - contains - name: cost_type in: query schema: type: string default: tokens - name: search in: query schema: description: Search by model, changed_by type: string responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: account_provider_id: type: string format: uuid changed_by: type: string default: manual cost_in: type: number cost_out: type: number cost_type: type: string default: tokens created_at: type: string format: date-time enable: type: boolean id: type: string format: uuid model: type: string model_rule: type: string default: equals enum: - equals - starts-with - contains modified_at: type: string format: date-time token_pricing: type: string weight: type: integer required: - account_provider_id - model - id - created_at - modified_at type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Provider Costs x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers.costs x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: aig-config-create-account-provider-cost summary: Create a new Account Provider Cost description: Creates a new AI Gateway. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 requestBody: content: application/json: schema: type: object properties: account_provider_id: type: string format: uuid cost_in: type: number cost_out: type: number cost_type: type: string default: tokens enable: type: boolean model: type: string model_rule: type: string default: equals enum: - equals - starts-with - contains token_pricing: type: object properties: input_audio_tokens: type: number input_cache_creation_tokens: type: number input_cached_tokens: type: number input_image_count: type: number input_image_tokens: type: number input_text_tokens: type: number input_tokens: type: number input_video_tokens: type: number output_image_count: type: number output_reasoning_tokens: type: number output_tokens: type: number total_tokens: type: number required: - account_provider_id - model responses: '200': description: Returns the created Object content: application/json: schema: type: object properties: result: type: object properties: account_provider_id: type: string format: uuid changed_by: type: string default: manual cost_in: type: number cost_out: type: number cost_type: type: string default: tokens created_at: type: string format: date-time enable: type: boolean id: type: string format: uuid model: type: string model_rule: type: string default: equals enum: - equals - starts-with - contains modified_at: type: string format: date-time token_pricing: type: string weight: type: integer required: - account_provider_id - model - id - created_at - modified_at success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Provider Costs x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers.costs x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/custom-providers/costs/{id}: delete: operationId: aig-config-delete-account-provider-cost summary: Delete a Account Provider Cost description: Deletes an AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: account_provider_id: type: string format: uuid changed_by: type: string default: manual cost_in: type: number cost_out: type: number cost_type: type: string default: tokens created_at: type: string format: date-time enable: type: boolean id: type: string format: uuid model: type: string model_rule: type: string default: equals enum: - equals - starts-with - contains modified_at: type: string format: date-time token_pricing: type: string weight: type: integer required: - account_provider_id - model - id - created_at - modified_at success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Provider Costs x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers.costs x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-config-fetch-account-provider-cost summary: Fetch a Account Provider Cost description: Retrieves details for a specific AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Returns a single object if found content: application/json: schema: type: object properties: result: type: object properties: account_provider_id: type: string format: uuid changed_by: type: string default: manual cost_in: type: number cost_out: type: number cost_type: type: string default: tokens created_at: type: string format: date-time enable: type: boolean id: type: string format: uuid model: type: string model_rule: type: string default: equals enum: - equals - starts-with - contains modified_at: type: string format: date-time token_pricing: type: string weight: type: integer required: - account_provider_id - model - id - created_at - modified_at success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Provider Costs x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers.costs x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: aig-config-update-account-provider-cost summary: Update a Account Provider Cost description: Updates an existing AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: cost_in: type: number cost_out: type: number cost_type: type: string default: tokens enable: type: boolean model: type: string model_rule: type: string default: equals enum: - equals - starts-with - contains token_pricing: type: object properties: input_audio_tokens: type: number input_cache_creation_tokens: type: number input_cached_tokens: type: number input_image_count: type: number input_image_tokens: type: number input_text_tokens: type: number input_tokens: type: number input_video_tokens: type: number output_image_count: type: number output_reasoning_tokens: type: number output_tokens: type: number total_tokens: type: number responses: '200': description: Returns the updated Object content: application/json: schema: type: object properties: result: type: object properties: account_provider_id: type: string format: uuid changed_by: type: string default: manual cost_in: type: number cost_out: type: number cost_type: type: string default: tokens created_at: type: string format: date-time enable: type: boolean id: type: string format: uuid model: type: string model_rule: type: string default: equals enum: - equals - starts-with - contains modified_at: type: string format: date-time token_pricing: type: string weight: type: integer required: - account_provider_id - model - id - created_at - modified_at success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Account Provider Costs x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.account-providers.costs x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/ai-gateway/evaluation-types: get: operationId: aig-config-list-evaluators summary: List Evaluators description: Lists all available evaluator types for scoring AI gateway responses. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 50 minimum: 5 - name: order_by in: query schema: type: string default: mandatory - name: order_by_direction in: query schema: type: string default: desc enum: - asc - desc responses: '200': description: Returns a list of Evaluators content: application/json: schema: type: object properties: result: type: array items: properties: created_at: type: string format: date-time description: type: string enable: type: boolean id: type: string mandatory: type: boolean modified_at: type: string format: date-time name: type: string type: type: string required: - name - type - mandatory - description - enable - id - created_at - modified_at type: object result_info: type: object properties: count: type: number page: type: number per_page: type: number total_count: type: number required: - count - page - per_page - total_count success: type: boolean required: - success - result - result_info '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Evaluations x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.evaluation-types x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways: get: operationId: aig-config-list-gateway summary: List Gateways description: Lists all AI Gateway evaluator types configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: search in: query schema: description: Search by id type: string responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: authentication: type: boolean x-auditable: true cache_invalidate_on_update: type: boolean x-auditable: true cache_ttl: type: integer minimum: 0 nullable: true x-auditable: true collect_logs: type: boolean x-auditable: true created_at: type: string format: date-time dlp: anyOf: - properties: action: type: string enum: - BLOCK - FLAG enabled: type: boolean profiles: type: array items: type: string required: - profiles - enabled - action type: object - properties: enabled: type: boolean policies: type: array items: properties: action: type: string enum: - FLAG - BLOCK check: type: array items: enum: - REQUEST - RESPONSE type: string enabled: type: boolean id: type: string profiles: type: array items: type: string required: - id - enabled - action - profiles - check type: object required: - enabled - policies type: object guardrails: type: object nullable: true properties: prompt: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: type: string enum: - FLAG - BLOCK 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK response: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK required: - prompt - response x-auditable: true id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true is_default: type: boolean x-auditable: true log_classification: type: boolean x-auditable: true log_management: type: integer maximum: 10000000 minimum: 10000 nullable: true x-auditable: true log_management_strategy: type: string enum: - STOP_INSERTING - DELETE_OLDEST nullable: true x-auditable: true logpush: type: boolean x-auditable: true logpush_public_key: type: string maxLength: 1024 minLength: 16 nullable: true x-auditable: true modified_at: type: string format: date-time otel: type: array items: properties: authorization: type: string maxLength: 256 content_type: type: string default: json enum: - json - protobuf headers: type: object additionalProperties: maxLength: 4096 type: string url: type: string format: uri maxLength: 2048 required: - url - headers type: object maxItems: 5 nullable: true x-auditable: true rate_limiting_interval: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_limit: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_technique: type: string enum: - fixed - sliding nullable: true x-auditable: true retry_backoff: description: Backoff strategy for retry delays type: string enum: - constant - linear - exponential nullable: true x-auditable: true retry_delay: description: Delay between retry attempts in milliseconds (0-5000) type: integer maximum: 5000 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: ecd9fd7b minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ limit: type: number exclusiveMinimum: true minimum: 0 limitType: type: string enum: - cost metadata: type: object additionalProperties: oneOf: - properties: mode: type: string enum: - partition required: - mode type: object - properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values type: object model: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values provider: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values technique: type: string default: sliding enum: - fixed - sliding window: type: integer exclusiveMinimum: true minimum: 0 required: - limitType - limit - window type: object default: [] maxItems: 20 x-auditable: true store_id: type: string nullable: true stripe: type: object nullable: true properties: authorization: type: string usage_events: type: array items: properties: payload: type: string required: - payload type: object required: - authorization - usage_events x-auditable: true workers_ai_billing_mode: description: Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway. type: string default: postpaid enum: - postpaid - unified x-auditable: true zdr: type: boolean x-auditable: true required: - id - rate_limiting_interval - rate_limiting_limit - collect_logs - cache_ttl - cache_invalidate_on_update - created_at - modified_at type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Gateways x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: aig-config-create-gateway summary: Create a new Gateway description: Creates a new AI Gateway. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 requestBody: content: application/json: schema: type: object properties: authentication: type: boolean x-auditable: true cache_invalidate_on_update: type: boolean x-auditable: true cache_ttl: type: integer minimum: 0 nullable: true x-auditable: true collect_logs: type: boolean x-auditable: true id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true log_management: type: integer maximum: 10000000 minimum: 10000 nullable: true x-auditable: true log_management_strategy: type: string enum: - STOP_INSERTING - DELETE_OLDEST nullable: true x-auditable: true logpush: type: boolean x-auditable: true logpush_public_key: type: string maxLength: 1024 minLength: 16 nullable: true x-auditable: true rate_limiting_interval: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_limit: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_technique: type: string enum: - fixed - sliding nullable: true x-auditable: true retry_backoff: description: Backoff strategy for retry delays type: string enum: - constant - linear - exponential nullable: true x-auditable: true retry_delay: description: Delay between retry attempts in milliseconds (0-5000) type: integer maximum: 5000 minimum: 0 nullable: true x-auditable: true retry_max_attempts: description: Maximum number of retry attempts for failed requests (1-5) type: integer maximum: 5 minimum: 1 nullable: true x-auditable: true store_id: type: string nullable: true workers_ai_billing_mode: description: Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway. type: string default: postpaid enum: - postpaid - unified x-auditable: true zdr: type: boolean x-auditable: true required: - id - rate_limiting_interval - rate_limiting_limit - collect_logs - cache_ttl - cache_invalidate_on_update responses: '200': description: Returns the created Object content: application/json: schema: type: object properties: result: type: object properties: authentication: type: boolean x-auditable: true cache_invalidate_on_update: type: boolean x-auditable: true cache_ttl: type: integer minimum: 0 nullable: true x-auditable: true collect_logs: type: boolean x-auditable: true created_at: type: string format: date-time dlp: anyOf: - properties: action: type: string enum: - BLOCK - FLAG enabled: type: boolean profiles: type: array items: type: string required: - profiles - enabled - action type: object - properties: enabled: type: boolean policies: type: array items: properties: action: type: string enum: - FLAG - BLOCK check: type: array items: enum: - REQUEST - RESPONSE type: string enabled: type: boolean id: type: string profiles: type: array items: type: string required: - id - enabled - action - profiles - check type: object required: - enabled - policies type: object guardrails: type: object nullable: true properties: prompt: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: type: string enum: - FLAG - BLOCK 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK response: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK required: - prompt - response x-auditable: true id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true is_default: type: boolean x-auditable: true log_classification: type: boolean x-auditable: true log_management: type: integer maximum: 10000000 minimum: 10000 nullable: true x-auditable: true log_management_strategy: type: string enum: - STOP_INSERTING - DELETE_OLDEST nullable: true x-auditable: true logpush: type: boolean x-auditable: true logpush_public_key: type: string maxLength: 1024 minLength: 16 nullable: true x-auditable: true modified_at: type: string format: date-time otel: type: array items: properties: authorization: type: string maxLength: 256 content_type: type: string default: json enum: - json - protobuf headers: type: object additionalProperties: maxLength: 4096 type: string url: type: string format: uri maxLength: 2048 required: - url - headers type: object maxItems: 5 nullable: true x-auditable: true rate_limiting_interval: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_limit: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_technique: type: string enum: - fixed - sliding nullable: true x-auditable: true retry_backoff: description: Backoff strategy for retry delays type: string enum: - constant - linear - exponential nullable: true x-auditable: true retry_delay: description: Delay between retry attempts in milliseconds (0-5000) type: integer maximum: 5000 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: 4a08df85 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ limit: type: number exclusiveMinimum: true minimum: 0 limitType: type: string enum: - cost metadata: type: object additionalProperties: oneOf: - properties: mode: type: string enum: - partition required: - mode type: object - properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values type: object model: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values provider: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values technique: type: string default: sliding enum: - fixed - sliding window: type: integer exclusiveMinimum: true minimum: 0 required: - limitType - limit - window type: object default: [] maxItems: 20 x-auditable: true store_id: type: string nullable: true stripe: type: object nullable: true properties: authorization: type: string usage_events: type: array items: properties: payload: type: string required: - payload type: object required: - authorization - usage_events x-auditable: true workers_ai_billing_mode: description: Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway. type: string default: postpaid enum: - postpaid - unified x-auditable: true zdr: type: boolean x-auditable: true required: - id - rate_limiting_interval - rate_limiting_limit - collect_logs - cache_ttl - cache_invalidate_on_update - created_at - modified_at success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Gateways x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/custom-domains: get: operationId: aig-config-list-custom-domain summary: List Custom Domains description: Lists all AI Gateway evaluator types configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: status in: query schema: type: string enum: - initializing - pending_dcv - active - blocked - error x-auditable: true - name: search in: query schema: description: Search by hostname type: string responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: created_at: description: epoch milliseconds type: integer example: 1717459200000 gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true hostname: description: the customer-owned custom hostname type: string example: ai.acme.com maxLength: 253 minLength: 1 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$ x-auditable: true modified_at: description: epoch milliseconds type: integer example: 1717459200000 ssl_hostname_id: type: string nullable: true x-auditable: true status: type: string enum: - initializing - pending_dcv - active - blocked - error x-auditable: true required: - hostname - gateway_id - ssl_hostname_id - status - created_at - modified_at type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Custom Domains x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.custom-domains x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: aig-config-create-custom-domain summary: Create a custom domain for a gateway description: Provisions a Cloudflare-for-SaaS custom hostname and returns the CNAME target to point DNS at. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true requestBody: content: application/json: schema: type: object properties: domain: description: the customer-owned custom hostname type: string example: ai.acme.com maxLength: 253 minLength: 1 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$ x-auditable: true minTLS: type: string enum: - '1.0' - '1.1' - '1.2' - '1.3' x-auditable: true zone_id: description: Cloudflare Zone ID owning the custom hostname type: string example: 395566f4c8a5b9d2a5fc0d457b007c44 pattern: ^[0-9a-f]{32}$ x-auditable: true required: - domain - zone_id responses: '200': description: The created custom domain and the CNAME target to configure. content: application/json: schema: type: object properties: result: type: object properties: cname_target: type: string created_at: description: epoch milliseconds type: integer example: 1717459200000 gateway_id: type: string hostname: type: string modified_at: description: epoch milliseconds type: integer example: 1717459200000 status: type: string enum: - initializing - pending_dcv - active - blocked - error required: - hostname - gateway_id - status - cname_target - created_at - modified_at success: type: boolean enum: - true required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Custom Domains x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.custom-domains x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/custom-domains/{hostname}: delete: operationId: aig-config-delete-custom-domain summary: Delete a Custom Domain description: Deletes an AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: hostname in: path required: true schema: description: the customer-owned custom hostname type: string example: ai.acme.com maxLength: 253 minLength: 1 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$ x-auditable: true responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: created_at: description: epoch milliseconds type: integer example: 1717459200000 gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true hostname: description: the customer-owned custom hostname type: string example: ai.acme.com maxLength: 253 minLength: 1 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$ x-auditable: true modified_at: description: epoch milliseconds type: integer example: 1717459200000 ssl_hostname_id: type: string nullable: true x-auditable: true status: type: string enum: - initializing - pending_dcv - active - blocked - error x-auditable: true required: - hostname - gateway_id - ssl_hostname_id - status - created_at - modified_at success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Custom Domains x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.custom-domains x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-config-fetch-custom-domain summary: Fetch a Custom Domain description: Retrieves details for a specific AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: hostname in: path required: true schema: description: the customer-owned custom hostname type: string example: ai.acme.com maxLength: 253 minLength: 1 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$ x-auditable: true responses: '200': description: Returns a single object if found content: application/json: schema: type: object properties: result: type: object properties: created_at: description: epoch milliseconds type: integer example: 1717459200000 gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true hostname: description: the customer-owned custom hostname type: string example: ai.acme.com maxLength: 253 minLength: 1 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$ x-auditable: true modified_at: description: epoch milliseconds type: integer example: 1717459200000 ssl_hostname_id: type: string nullable: true x-auditable: true status: type: string enum: - initializing - pending_dcv - active - blocked - error x-auditable: true required: - hostname - gateway_id - ssl_hostname_id - status - created_at - modified_at success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Custom Domains x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.custom-domains x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/datasets: get: operationId: aig-config-list-dataset summary: List Datasets description: Lists all AI Gateway evaluator types configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: name in: query schema: type: string x-auditable: true - name: enable in: query schema: type: boolean x-auditable: true - name: search in: query schema: description: Search by id, name, filters type: string responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - created_at - modified_at type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Datasets x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.datasets x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: aig-config-create-dataset summary: Create a new Dataset description: Creates a new AI Gateway. parameters: - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 requestBody: content: application/json: schema: type: object properties: enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true name: type: string x-auditable: true required: - name - filters - enable responses: '200': description: Returns the created Object content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - created_at - modified_at success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Datasets x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.datasets x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/datasets/{id}: delete: operationId: aig-config-delete-dataset summary: Delete a Dataset description: Deletes an AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: id in: path required: true schema: type: string x-auditable: true responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - created_at - modified_at success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Datasets x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.datasets x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-config-fetch-dataset summary: Fetch a Dataset description: Retrieves details for a specific AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: id in: path required: true schema: type: string x-auditable: true responses: '200': description: Returns a single object if found content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - created_at - modified_at success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Datasets x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.datasets x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: aig-config-update-dataset summary: Update a Dataset description: Updates an existing AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: id in: path required: true schema: type: string x-auditable: true requestBody: content: application/json: schema: type: object properties: enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true name: type: string x-auditable: true required: - name - filters - enable responses: '200': description: Returns the updated Object content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - created_at - modified_at success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Datasets x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.datasets x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/evaluations: get: operationId: aig-config-list-evaluations summary: List Evaluations description: Lists all AI Gateway evaluator types configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: name in: query schema: type: string x-auditable: true - name: processed in: query schema: type: boolean x-auditable: true - name: search in: query schema: description: Search by id, name type: string responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: created_at: type: string format: date-time datasets: type: array items: properties: account_id: type: string account_tag: type: string created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - account_id - account_tag - created_at - modified_at type: object gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true processed: type: boolean x-auditable: true results: type: array items: properties: created_at: type: string format: date-time evaluation_id: type: string evaluation_type_id: type: string id: type: string modified_at: type: string format: date-time result: type: string status: type: number status_description: type: string total_logs: type: number required: - evaluation_id - evaluation_type_id - result - total_logs - status - status_description - id - created_at - modified_at type: object total_logs: type: number x-auditable: true required: - id - gateway_id - name - created_at - modified_at - datasets - results - processed - total_logs type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Evaluations x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.evaluations x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: aig-config-create-evaluations summary: Create a new Evaluation description: Creates a new AI Gateway. parameters: - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 requestBody: content: application/json: schema: type: object properties: dataset_ids: type: array items: type: string maxItems: 5 minItems: 1 evaluation_type_ids: type: array items: type: string name: type: string x-auditable: true required: - name - dataset_ids - evaluation_type_ids responses: '200': description: Returns the created Object content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time datasets: type: array items: properties: account_id: type: string account_tag: type: string created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - account_id - account_tag - created_at - modified_at type: object gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true processed: type: boolean x-auditable: true results: type: array items: properties: created_at: type: string format: date-time evaluation_id: type: string evaluation_type_id: type: string id: type: string modified_at: type: string format: date-time result: type: string status: type: number status_description: type: string total_logs: type: number required: - evaluation_id - evaluation_type_id - result - total_logs - status - status_description - id - created_at - modified_at type: object total_logs: type: number x-auditable: true required: - id - gateway_id - name - created_at - modified_at - datasets - results - processed - total_logs success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Evaluations x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.evaluations x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/evaluations/{id}: delete: operationId: aig-config-delete-evaluations summary: Delete a Evaluation description: Deletes an AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: id in: path required: true schema: type: string x-auditable: true responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time datasets: type: array items: properties: account_id: type: string account_tag: type: string created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - account_id - account_tag - created_at - modified_at type: object gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true processed: type: boolean x-auditable: true results: type: array items: properties: created_at: type: string format: date-time evaluation_id: type: string evaluation_type_id: type: string id: type: string modified_at: type: string format: date-time result: type: string status: type: number status_description: type: string total_logs: type: number required: - evaluation_id - evaluation_type_id - result - total_logs - status - status_description - id - created_at - modified_at type: object total_logs: type: number x-auditable: true required: - id - gateway_id - name - created_at - modified_at - datasets - results - processed - total_logs success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Evaluations x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.evaluations x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-config-fetch-evaluations summary: Fetch a Evaluation description: Retrieves details for a specific AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: id in: path required: true schema: type: string x-auditable: true responses: '200': description: Returns a single object if found content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time datasets: type: array items: properties: account_id: type: string account_tag: type: string created_at: type: string format: date-time enable: type: boolean x-auditable: true filters: type: array items: properties: key: type: string enum: - created_at - request_content_type - response_content_type - success - cached - provider - model - cost - tokens - tokens_in - tokens_out - duration - feedback x-auditable: true operator: type: string enum: - eq - contains - lt - gt x-auditable: true value: type: array items: anyOf: - type: string - type: number - type: boolean x-auditable: true required: - key - operator - value type: object x-auditable: true gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - gateway_id - name - filters - enable - id - account_id - account_tag - created_at - modified_at type: object gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true processed: type: boolean x-auditable: true results: type: array items: properties: created_at: type: string format: date-time evaluation_id: type: string evaluation_type_id: type: string id: type: string modified_at: type: string format: date-time result: type: string status: type: number status_description: type: string total_logs: type: number required: - evaluation_id - evaluation_type_id - result - total_logs - status - status_description - id - created_at - modified_at type: object total_logs: type: number x-auditable: true required: - id - gateway_id - name - created_at - modified_at - datasets - results - processed - total_logs success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Evaluations x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.evaluations x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs: delete: operationId: aig-config-delete-gateway-logs summary: Delete Gateway Logs description: Deletes gateway log entries matching the specified criteria. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: order_by in: query schema: type: string default: created_at enum: - created_at - provider - model - model_type - success - cached - cost - tokens_in - tokens_out - duration - feedback - name: order_by_direction in: query schema: type: string default: asc enum: - asc - desc - name: filters in: query schema: type: array items: properties: key: type: string enum: - id - created_at - request_content_type - response_content_type - request_type - success - cached - provider - model - model_type - cost - tokens - tokens_in - tokens_out - duration - feedback - event_id - metadata.key - metadata.value - authentication - wholesale - compatibilityMode - dlp_action - user_agent operator: type: string enum: - eq - neq - contains - lt - gt value: type: array items: anyOf: - nullable: true type: string - type: number - type: boolean required: - key - operator - value type: object - name: limit in: query schema: type: integer default: 10000 maximum: 10000 minimum: 1 responses: '200': description: Returns if the delete was successful content: application/json: schema: type: object properties: success: type: boolean required: - success '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Logs x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.logs x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-config-list-gateway-logs summary: List Gateway Logs description: Lists request/response log entries for the AI gateway with filtering and pagination. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: search in: query schema: type: string - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 50 minimum: 1 - name: order_by in: query schema: type: string default: created_at enum: - created_at - provider - model - model_type - success - cached - name: order_by_direction in: query schema: type: string default: desc enum: - asc - desc - name: filters in: query schema: type: array items: properties: key: type: string enum: - id - created_at - request_content_type - response_content_type - request_type - success - cached - provider - model - model_type - cost - tokens - tokens_in - tokens_out - duration - feedback - event_id - metadata.key - metadata.value - authentication - wholesale - compatibilityMode - dlp_action - user_agent operator: type: string enum: - eq - neq - contains - lt - gt value: type: array items: anyOf: - nullable: true type: string - type: number - type: boolean required: - key - operator - value type: object - name: meta_info in: query schema: type: boolean - name: direction in: query schema: type: string deprecated: true enum: - asc - desc - name: start_date in: query schema: type: string format: date-time deprecated: true - name: end_date in: query schema: type: string format: date-time deprecated: true - name: min_cost in: query schema: type: number deprecated: true - name: max_cost in: query schema: type: number deprecated: true - name: min_tokens_in in: query schema: type: number deprecated: true - name: max_tokens_in in: query schema: type: number deprecated: true - name: min_tokens_out in: query schema: type: number deprecated: true - name: max_tokens_out in: query schema: type: number deprecated: true - name: min_total_tokens in: query schema: type: number deprecated: true - name: max_total_tokens in: query schema: type: number deprecated: true - name: min_duration in: query schema: type: number deprecated: true - name: max_duration in: query schema: type: number deprecated: true - name: feedback in: query schema: anyOf: - enum: - -1 type: number - enum: - 0 type: number - enum: - 1 type: number deprecated: true - name: success in: query schema: type: boolean deprecated: true - name: cached in: query schema: type: boolean deprecated: true - name: model in: query schema: type: string deprecated: true - name: model_type in: query schema: type: string deprecated: true - name: provider in: query schema: type: string deprecated: true - name: request_content_type in: query schema: type: string deprecated: true - name: response_content_type in: query schema: type: string deprecated: true responses: '200': description: Returns a list of Gateway Logs content: application/json: schema: type: object properties: result: type: array items: properties: cached: type: boolean cost: type: number created_at: type: string format: date-time custom_cost: type: boolean duration: type: integer id: type: string metadata: type: string model: type: string model_type: type: string path: type: string provider: type: string request_content_type: type: string request_type: type: string response_content_type: type: string status_code: type: integer step: type: integer success: type: boolean tokens_in: type: integer nullable: true tokens_out: type: integer nullable: true required: - id - created_at - provider - model - path - duration - success - cached - tokens_in - tokens_out type: object result_info: type: object properties: count: type: number max_cost: type: number max_duration: type: number max_tokens_in: type: number max_tokens_out: type: number max_total_tokens: type: number min_cost: type: number min_duration: type: number min_tokens_in: type: number min_tokens_out: type: number min_total_tokens: type: number page: type: number per_page: type: number total_count: type: number success: type: boolean required: - success - result - result_info '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Logs x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.logs x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs/{id}: get: operationId: aig-config-get-gateway-log-detail summary: Get Gateway Log Detail description: Retrieves detailed information for a specific AI Gateway log entry. parameters: - name: id in: path required: true schema: type: string - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a responses: '200': description: Returns the log details content: application/json: schema: type: object properties: result: type: object properties: cached: type: boolean cost: type: number created_at: type: string format: date-time custom_cost: type: boolean duration: type: integer id: type: string metadata: type: string model: type: string model_type: type: string path: type: string provider: type: string request_content_type: type: string request_head: type: string request_head_complete: type: boolean request_size: type: integer request_type: type: string response_content_type: type: string response_head: type: string response_head_complete: type: boolean response_size: type: integer status_code: type: integer step: type: integer success: type: boolean tokens_in: type: integer nullable: true tokens_out: type: integer nullable: true required: - id - created_at - provider - model - path - duration - success - cached - tokens_in - tokens_out success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Logs x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.logs x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: aig-config-patch-gateway-log summary: Patch Gateway Log description: Updates metadata for an AI Gateway log entry. parameters: - name: id in: path required: true schema: type: string - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a requestBody: content: application/json: schema: type: object properties: feedback: type: number maximum: 1 minimum: -1 nullable: true metadata: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean nullable: true score: type: number maximum: 100 minimum: 0 nullable: true responses: '200': description: Returns the log details content: application/json: schema: type: object properties: result: type: object success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Logs x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.logs x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs/{id}/request: get: operationId: aig-config-get-gateway-log-request summary: Get Gateway Log Request description: Retrieves the original request payload for an AI Gateway log entry. parameters: - name: id in: path required: true schema: type: string - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a responses: '200': description: Returns the request body from a specific log content: application/json: schema: type: object '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Logs x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.logs x-fern-sdk-method-name: request x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs/{id}/response: get: operationId: aig-config-get-gateway-log-response summary: Get Gateway Log Response description: Retrieves the response payload for an AI Gateway log entry. parameters: - name: id in: path required: true schema: type: string - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a responses: '200': description: Returns the response body from a specific log content: application/json: schema: type: object '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Logs x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.logs x-fern-sdk-method-name: response x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/provider_configs: get: operationId: aig-config-list-providers summary: List Provider Configs description: Lists all AI Gateway evaluator types configured for the account. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 100 minimum: 1 responses: '200': description: List objects content: application/json: schema: type: object properties: result: type: array items: properties: alias: type: string default_config: type: boolean gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string modified_at: type: string format: date-time provider_slug: type: string rate_limit: type: number rate_limit_period: type: number default: 60 secret_id: type: string secret_preview: type: string required: - id - provider_slug - secret_preview - default_config - gateway_id - modified_at - alias - secret_id type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Provider Configs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways.providers x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: aig-config-create-providers summary: Create a new Provider Configs description: Creates a new AI Gateway. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true requestBody: content: application/json: schema: type: object properties: alias: type: string default_config: type: boolean provider_slug: type: string rate_limit: type: number rate_limit_period: type: number default: 60 secret: type: string secret_id: type: string required: - provider_slug - default_config - alias responses: '200': description: Returns the created Object content: application/json: schema: type: object properties: result: type: object properties: alias: type: string default_config: type: boolean gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string modified_at: type: string format: date-time provider_slug: type: string rate_limit: type: number rate_limit_period: type: number default: 60 secret_id: type: string secret_preview: type: string required: - id - provider_slug - secret_preview - default_config - gateway_id - modified_at - alias - secret_id success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Provider Configs x-api-token-group: - Secrets Store Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways.providers x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/provider_configs/{id}: delete: operationId: aig-config-delete-providers summary: Delete a Provider Configs description: Deletes an AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: id in: path required: true schema: type: string responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: alias: type: string default_config: type: boolean gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string modified_at: type: string format: date-time provider_slug: type: string rate_limit: type: number rate_limit_period: type: number default: 60 secret_id: type: string secret_preview: type: string required: - id - provider_slug - secret_preview - default_config - gateway_id - modified_at - alias - secret_id success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Provider Configs x-api-token-group: - Secrets Store Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways.providers x-fern-sdk-method-name: delete x-forge-hidden: true put: operationId: aig-config-update-providers summary: Update a Provider Configs description: Updates an existing AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: secret: type: string required: - secret responses: '200': description: Returns the updated Object content: application/json: schema: type: object properties: result: type: object properties: alias: type: string default_config: type: boolean gateway_id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true id: type: string modified_at: type: string format: date-time provider_slug: type: string rate_limit: type: number rate_limit_period: type: number default: 60 secret_id: type: string secret_preview: type: string required: - id - provider_slug - secret_preview - default_config - gateway_id - modified_at - alias - secret_id success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Provider Configs x-api-token-group: - Secrets Store Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways.providers x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes: get: operationId: aig-config-list-gateway-dynamic-routes summary: List all AI Gateway Dynamic Routes. description: List all AI Gateway Dynamic Routes. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: page in: query description: Page number schema: description: Page number type: integer example: 1 - name: per_page in: query description: Number of routes per page schema: description: Number of routes per page type: integer example: 20 responses: '200': description: Success content: application/json: schema: type: object properties: data: type: object properties: order_by: type: string order_by_direction: type: string page: type: number per_page: type: number routes: type: array items: properties: account_tag: type: string created_at: type: string format: date-time deployment: type: object properties: created_at: type: string deployment_id: type: string version_id: type: string required: - deployment_id - version_id - created_at elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string modified_at: type: string format: date-time name: type: string version: type: object properties: active: type: string enum: - 'true' - 'false' created_at: type: string data: type: string is_valid: type: boolean version_id: type: string required: - version_id - data - active - created_at required: - id - name - elements - created_at - modified_at - account_tag - gateway_id - version - deployment type: object required: - routes - page - per_page - order_by - order_by_direction success: type: boolean required: - success - data '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: aig-config-post-gateway-dynamic-route summary: Create a new AI Gateway Dynamic Route. description: Create a new AI Gateway Dynamic Route. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' requestBody: content: application/json: schema: type: object properties: elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object name: type: string required: - name - elements responses: '200': description: Success content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time deployment: type: object properties: created_at: type: string deployment_id: type: string version_id: type: string required: - deployment_id - version_id - created_at elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string modified_at: type: string format: date-time name: type: string version: type: object properties: active: type: string enum: - 'true' - 'false' created_at: type: string data: type: string is_valid: type: boolean version_id: type: string required: - version_id - data - active - created_at required: - id - name - elements - created_at - modified_at - gateway_id - version - deployment success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}: delete: operationId: aig-config-delete-gateway-dynamic-route summary: Delete an AI Gateway Dynamic Route. description: Delete an AI Gateway Dynamic Route. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: id in: path required: true schema: type: string example: '54442216' responses: '200': description: Success content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string modified_at: type: string format: date-time name: type: string required: - id - name - elements - created_at - modified_at - gateway_id success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-config-get-gateway-dynamic-route summary: Get an AI Gateway Dynamic Route. description: Get an AI Gateway Dynamic Route. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: id in: path required: true schema: type: string example: '54442216' responses: '200': description: Success content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time deployment: type: object properties: created_at: type: string deployment_id: type: string version_id: type: string required: - deployment_id - version_id - created_at elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string modified_at: type: string format: date-time name: type: string version: type: object properties: active: type: string enum: - 'true' - 'false' created_at: type: string data: type: string is_valid: type: boolean version_id: type: string required: - version_id - data - active - created_at required: - id - name - elements - created_at - modified_at - gateway_id - version - deployment success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: aig-config-update-gateway-dynamic-route summary: Update an AI Gateway Dynamic Route. description: Update an AI Gateway Dynamic Route. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: id in: path required: true schema: type: string example: '54442216' requestBody: content: application/json: schema: type: object properties: name: type: string example: Route Name required: - name responses: '200': description: Success content: application/json: schema: type: object properties: route: type: object properties: account_tag: type: string created_at: type: string format: date-time deployment: type: object properties: created_at: type: string deployment_id: type: string version_id: type: string required: - deployment_id - version_id - created_at elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string modified_at: type: string format: date-time name: type: string version: type: object properties: active: type: string enum: - 'true' - 'false' created_at: type: string data: type: string is_valid: type: boolean version_id: type: string required: - version_id - data - active - created_at required: - id - name - elements - created_at - modified_at - account_tag - gateway_id - version - deployment success: type: boolean required: - success - route '400': description: Input Error content: application/json: schema: type: object properties: route: type: object properties: account_tag: type: string created_at: type: string format: date-time elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string modified_at: type: string format: date-time name: type: string required: - id - name - elements - created_at - modified_at - account_tag - gateway_id success: type: boolean required: - success - route security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/deployments: get: operationId: aig-config-list-gateway-dynamic-route-deployments summary: List all AI Gateway Dynamic Route Deployments. description: List all AI Gateway Dynamic Route Deployments. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: id in: path required: true schema: type: string example: '54442216' responses: '200': description: Success content: application/json: schema: type: object properties: data: type: object properties: deployments: type: array items: properties: created_at: type: string deployment_id: type: string version_id: type: string required: - deployment_id - version_id - created_at type: object order_by: type: string order_by_direction: type: string page: type: number per_page: type: number required: - deployments - page - per_page - order_by - order_by_direction success: type: boolean required: - success - data '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: list-deployments x-forge-hidden: true post: operationId: aig-config-post-gateway-dynamic-route-deployment summary: Create a new AI Gateway Dynamic Route Deployment. description: Create a new AI Gateway Dynamic Route Deployment. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: id in: path required: true schema: type: string example: '54442216' requestBody: content: application/json: schema: type: object properties: version_id: type: string example: '54442216' required: - version_id responses: '200': description: Success content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string modified_at: type: string format: date-time name: type: string required: - id - name - elements - created_at - modified_at - gateway_id success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: create-deployment x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/versions: get: operationId: aig-config-list-gateway-dynamic-route-versions summary: List all AI Gateway Dynamic Route Versions. description: List all AI Gateway Dynamic Route Versions. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: id in: path required: true schema: type: string example: '54442216' responses: '200': description: Success content: application/json: schema: type: object properties: data: type: object properties: order_by: type: string order_by_direction: type: string page: type: number per_page: type: number versions: type: array items: properties: active: type: string enum: - 'true' - 'false' created_at: type: string data: type: string is_valid: type: boolean version_id: type: string required: - version_id - data - active - created_at type: object required: - versions - page - per_page - order_by - order_by_direction success: type: boolean required: - success - data '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: list-versions x-forge-hidden: true post: operationId: aig-config-post-gateway-dynamic-route-version summary: Create a new AI Gateway Dynamic Route Version. description: Create a new AI Gateway Dynamic Route Version. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: id in: path required: true schema: type: string example: '54442216' requestBody: content: application/json: schema: type: object properties: elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object required: - elements responses: '200': description: Success content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string modified_at: type: string format: date-time name: type: string required: - id - name - elements - created_at - modified_at - gateway_id success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: create-version x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/versions/{version_id}: get: operationId: aig-config-get-gateway-dynamic-route-version summary: Get an AI Gateway Dynamic Route Version. description: Get an AI Gateway Dynamic Route Version. parameters: - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: gateway_id in: path required: true schema: type: string example: '54442216' - name: id in: path required: true schema: type: string example: '54442216' - name: version_id in: path required: true schema: type: string example: '54442216' responses: '200': description: Success content: application/json: schema: type: object properties: result: type: object properties: active: type: string enum: - 'true' - 'false' created_at: type: string data: type: string elements: type: array items: oneOf: - properties: id: type: string outputs: type: object properties: next: type: object properties: elementId: type: string required: - elementId required: - next type: type: string enum: - start required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: 'false': type: object properties: elementId: type: string required: - elementId 'true': type: object properties: elementId: type: string required: - elementId required: - 'true' - 'false' properties: type: object properties: conditions: type: object type: type: string enum: - conditional required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - percentage required: - id - outputs - type type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: key: type: string limit: type: number limitType: enum: - count - cost type: string window: type: number required: - limitType - key - limit - window type: type: string enum: - rate required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object properties: fallback: type: object properties: elementId: type: string required: - elementId success: type: object properties: elementId: type: string required: - elementId required: - success - fallback properties: type: object properties: model: type: string provider: type: string retries: type: number timeout: type: number required: - provider - model - timeout - retries type: type: string enum: - model required: - id - outputs - type - properties type: object - properties: id: type: string outputs: type: object additionalProperties: properties: elementId: type: string required: - elementId type: object type: type: string enum: - end required: - id - outputs - type type: object gateway_id: type: string id: type: string is_valid: type: boolean modified_at: type: string format: date-time name: type: string version_id: type: string required: - id - name - elements - created_at - modified_at - gateway_id - version_id - data - active success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Dynamic Routes x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.dynamic-routing x-fern-sdk-method-name: get-version x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/url/{provider}: get: operationId: aig-config-get-gateway-url summary: Get Gateway URL description: Retrieves the endpoint URL for an AI Gateway. parameters: - name: gateway_id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: 0d37909e38d3e99c29fa2cd343ac421a - name: provider in: path required: true schema: type: string example: workers-ai responses: '200': description: Returns the log details content: application/json: schema: type: object properties: result: type: string success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Gateways x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.urls x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/ai-gateway/gateways/{id}: delete: operationId: aig-config-delete-gateway summary: Delete a Gateway description: Deletes an AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true responses: '200': description: Returns the Object if it was successfully deleted content: application/json: schema: type: object properties: result: type: object properties: authentication: type: boolean x-auditable: true cache_invalidate_on_update: type: boolean x-auditable: true cache_ttl: type: integer minimum: 0 nullable: true x-auditable: true collect_logs: type: boolean x-auditable: true created_at: type: string format: date-time dlp: anyOf: - properties: action: type: string enum: - BLOCK - FLAG enabled: type: boolean profiles: type: array items: type: string required: - profiles - enabled - action type: object - properties: enabled: type: boolean policies: type: array items: properties: action: type: string enum: - FLAG - BLOCK check: type: array items: enum: - REQUEST - RESPONSE type: string enabled: type: boolean id: type: string profiles: type: array items: type: string required: - id - enabled - action - profiles - check type: object required: - enabled - policies type: object guardrails: type: object nullable: true properties: prompt: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: type: string enum: - FLAG - BLOCK 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK response: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK required: - prompt - response x-auditable: true id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true is_default: type: boolean x-auditable: true log_classification: type: boolean x-auditable: true log_management: type: integer maximum: 10000000 minimum: 10000 nullable: true x-auditable: true log_management_strategy: type: string enum: - STOP_INSERTING - DELETE_OLDEST nullable: true x-auditable: true logpush: type: boolean x-auditable: true logpush_public_key: type: string maxLength: 1024 minLength: 16 nullable: true x-auditable: true modified_at: type: string format: date-time otel: type: array items: properties: authorization: type: string maxLength: 256 content_type: type: string default: json enum: - json - protobuf headers: type: object additionalProperties: maxLength: 4096 type: string url: type: string format: uri maxLength: 2048 required: - url - headers type: object maxItems: 5 nullable: true x-auditable: true rate_limiting_interval: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_limit: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_technique: type: string enum: - fixed - sliding nullable: true x-auditable: true retry_backoff: description: Backoff strategy for retry delays type: string enum: - constant - linear - exponential nullable: true x-auditable: true retry_delay: description: Delay between retry attempts in milliseconds (0-5000) type: integer maximum: 5000 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: 91cc05d8 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ limit: type: number exclusiveMinimum: true minimum: 0 limitType: type: string enum: - cost metadata: type: object additionalProperties: oneOf: - properties: mode: type: string enum: - partition required: - mode type: object - properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values type: object model: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values provider: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values technique: type: string default: sliding enum: - fixed - sliding window: type: integer exclusiveMinimum: true minimum: 0 required: - limitType - limit - window type: object default: [] maxItems: 20 x-auditable: true store_id: type: string nullable: true stripe: type: object nullable: true properties: authorization: type: string usage_events: type: array items: properties: payload: type: string required: - payload type: object required: - authorization - usage_events x-auditable: true workers_ai_billing_mode: description: Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway. type: string default: postpaid enum: - postpaid - unified x-auditable: true zdr: type: boolean x-auditable: true required: - id - rate_limiting_interval - rate_limiting_limit - collect_logs - cache_ttl - cache_invalidate_on_update - created_at - modified_at success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Gateways x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: aig-config-fetch-gateway summary: Fetch a Gateway description: Retrieves details for a specific AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true responses: '200': description: Returns a single object if found content: application/json: schema: type: object properties: result: type: object properties: authentication: type: boolean x-auditable: true cache_invalidate_on_update: type: boolean x-auditable: true cache_ttl: type: integer minimum: 0 nullable: true x-auditable: true collect_logs: type: boolean x-auditable: true created_at: type: string format: date-time dlp: anyOf: - properties: action: type: string enum: - BLOCK - FLAG enabled: type: boolean profiles: type: array items: type: string required: - profiles - enabled - action type: object - properties: enabled: type: boolean policies: type: array items: properties: action: type: string enum: - FLAG - BLOCK check: type: array items: enum: - REQUEST - RESPONSE type: string enabled: type: boolean id: type: string profiles: type: array items: type: string required: - id - enabled - action - profiles - check type: object required: - enabled - policies type: object guardrails: type: object nullable: true properties: prompt: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: type: string enum: - FLAG - BLOCK 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK response: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK required: - prompt - response x-auditable: true id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true is_default: type: boolean x-auditable: true log_classification: type: boolean x-auditable: true log_management: type: integer maximum: 10000000 minimum: 10000 nullable: true x-auditable: true log_management_strategy: type: string enum: - STOP_INSERTING - DELETE_OLDEST nullable: true x-auditable: true logpush: type: boolean x-auditable: true logpush_public_key: type: string maxLength: 1024 minLength: 16 nullable: true x-auditable: true modified_at: type: string format: date-time otel: type: array items: properties: authorization: type: string maxLength: 256 content_type: type: string default: json enum: - json - protobuf headers: type: object additionalProperties: maxLength: 4096 type: string url: type: string format: uri maxLength: 2048 required: - url - headers type: object maxItems: 5 nullable: true x-auditable: true rate_limiting_interval: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_limit: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_technique: type: string enum: - fixed - sliding nullable: true x-auditable: true retry_backoff: description: Backoff strategy for retry delays type: string enum: - constant - linear - exponential nullable: true x-auditable: true retry_delay: description: Delay between retry attempts in milliseconds (0-5000) type: integer maximum: 5000 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: b1430861 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ limit: type: number exclusiveMinimum: true minimum: 0 limitType: type: string enum: - cost metadata: type: object additionalProperties: oneOf: - properties: mode: type: string enum: - partition required: - mode type: object - properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values type: object model: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values provider: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values technique: type: string default: sliding enum: - fixed - sliding window: type: integer exclusiveMinimum: true minimum: 0 required: - limitType - limit - window type: object default: [] maxItems: 20 x-auditable: true store_id: type: string nullable: true stripe: type: object nullable: true properties: authorization: type: string usage_events: type: array items: properties: payload: type: string required: - payload type: object required: - authorization - usage_events x-auditable: true workers_ai_billing_mode: description: Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway. type: string default: postpaid enum: - postpaid - unified x-auditable: true zdr: type: boolean x-auditable: true required: - id - rate_limiting_interval - rate_limiting_limit - collect_logs - cache_ttl - cache_invalidate_on_update - created_at - modified_at success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Gateways x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: aig-config-update-gateway summary: Update a Gateway description: Updates an existing AI Gateway dataset. parameters: - name: account_id in: path required: true schema: type: string example: 3ebbcb006d4d46d7bb6a8c7f14676cb0 - name: id in: path required: true schema: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true requestBody: content: application/json: schema: type: object properties: authentication: type: boolean x-auditable: true 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 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK response: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK required: - prompt - response x-auditable: true log_classification: type: boolean x-auditable: true log_management: type: integer maximum: 10000000 minimum: 10000 nullable: true x-auditable: true log_management_strategy: type: string enum: - STOP_INSERTING - DELETE_OLDEST nullable: true x-auditable: true logpush: type: boolean x-auditable: true logpush_public_key: type: string maxLength: 1024 minLength: 16 nullable: true x-auditable: true otel: type: array items: properties: authorization: type: string maxLength: 256 content_type: type: string default: json enum: - json - protobuf headers: type: object additionalProperties: maxLength: 4096 type: string url: type: string format: uri maxLength: 2048 required: - url - headers type: object maxItems: 5 nullable: true x-auditable: true rate_limiting_interval: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_limit: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_technique: type: string enum: - fixed - sliding nullable: true x-auditable: true retry_backoff: description: Backoff strategy for retry delays type: string enum: - constant - linear - exponential nullable: true x-auditable: true retry_delay: description: Delay between retry attempts in milliseconds (0-5000) type: integer maximum: 5000 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: bdd858ab minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ limit: type: number exclusiveMinimum: true minimum: 0 limitType: type: string enum: - cost metadata: type: object additionalProperties: oneOf: - properties: mode: type: string enum: - partition required: - mode type: object - properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values type: object model: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values provider: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values technique: type: string default: sliding enum: - fixed - sliding window: type: integer exclusiveMinimum: true minimum: 0 required: - limitType - limit - window type: object default: [] maxItems: 20 x-auditable: true store_id: type: string nullable: true stripe: type: object nullable: true properties: authorization: type: string usage_events: type: array items: properties: payload: type: string required: - payload type: object required: - authorization - usage_events x-auditable: true workers_ai_billing_mode: description: Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway. type: string default: postpaid enum: - postpaid - unified x-auditable: true zdr: type: boolean x-auditable: true required: - rate_limiting_interval - rate_limiting_limit - collect_logs - cache_ttl - cache_invalidate_on_update responses: '200': description: Returns the updated Object content: application/json: schema: type: object properties: result: type: object properties: authentication: type: boolean x-auditable: true cache_invalidate_on_update: type: boolean x-auditable: true cache_ttl: type: integer minimum: 0 nullable: true x-auditable: true collect_logs: type: boolean x-auditable: true created_at: type: string format: date-time dlp: anyOf: - properties: action: type: string enum: - BLOCK - FLAG enabled: type: boolean profiles: type: array items: type: string required: - profiles - enabled - action type: object - properties: enabled: type: boolean policies: type: array items: properties: action: type: string enum: - FLAG - BLOCK check: type: array items: enum: - REQUEST - RESPONSE type: string enabled: type: boolean id: type: string profiles: type: array items: type: string required: - id - enabled - action - profiles - check type: object required: - enabled - policies type: object guardrails: type: object nullable: true properties: prompt: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: type: string enum: - FLAG - BLOCK 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK response: type: object properties: P1: type: string enum: - FLAG - BLOCK S1: 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 S10: type: string enum: - FLAG - BLOCK S11: type: string enum: - FLAG - BLOCK S12: type: string enum: - FLAG - BLOCK S13: type: string enum: - FLAG - BLOCK required: - prompt - response x-auditable: true id: description: gateway id type: string example: my-gateway maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true is_default: type: boolean x-auditable: true log_classification: type: boolean x-auditable: true log_management: type: integer maximum: 10000000 minimum: 10000 nullable: true x-auditable: true log_management_strategy: type: string enum: - STOP_INSERTING - DELETE_OLDEST nullable: true x-auditable: true logpush: type: boolean x-auditable: true logpush_public_key: type: string maxLength: 1024 minLength: 16 nullable: true x-auditable: true modified_at: type: string format: date-time otel: type: array items: properties: authorization: type: string maxLength: 256 content_type: type: string default: json enum: - json - protobuf headers: type: object additionalProperties: maxLength: 4096 type: string url: type: string format: uri maxLength: 2048 required: - url - headers type: object maxItems: 5 nullable: true x-auditable: true rate_limiting_interval: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_limit: type: integer minimum: 0 nullable: true x-auditable: true rate_limiting_technique: type: string enum: - fixed - sliding nullable: true x-auditable: true retry_backoff: description: Backoff strategy for retry delays type: string enum: - constant - linear - exponential nullable: true x-auditable: true retry_delay: description: Delay between retry attempts in milliseconds (0-5000) type: integer maximum: 5000 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: f8a208a9 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ limit: type: number exclusiveMinimum: true minimum: 0 limitType: type: string enum: - cost metadata: type: object additionalProperties: oneOf: - properties: mode: type: string enum: - partition required: - mode type: object - properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values type: object model: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values provider: type: object properties: mode: type: string enum: - filter values: type: array items: type: string required: - mode - values technique: type: string default: sliding enum: - fixed - sliding window: type: integer exclusiveMinimum: true minimum: 0 required: - limitType - limit - window type: object default: [] maxItems: 20 x-auditable: true store_id: type: string nullable: true stripe: type: object nullable: true properties: authorization: type: string usage_events: type: array items: properties: payload: type: string required: - payload type: object required: - authorization - usage_events x-auditable: true workers_ai_billing_mode: description: Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway. type: string default: postpaid enum: - postpaid - unified x-auditable: true zdr: type: boolean x-auditable: true required: - id - rate_limiting_interval - rate_limiting_limit - collect_logs - cache_ttl - cache_invalidate_on_update - created_at - modified_at success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7001 message: type: string example: Input Validation Error path: type: array items: example: body type: string required: - code - message - path type: object success: type: boolean required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Gateway Gateways x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-gateway.gateways x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/ai-gateway/logging-state: get: operationId: aig-config-get-logging-state summary: Get AI Gateway logging state description: Returns the canonical logging platform and migration availability for an account. parameters: - name: account_id in: path required: true schema: type: string responses: '200': description: Returns the account logging state content: application/json: schema: type: object properties: result: type: object properties: migrated_at: type: integer minimum: 0 nullable: true migration_available: type: boolean platform: type: string enum: - legacy - workers_observability required: - platform - migrated_at - migration_available success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors '503': description: Logging state is temporarily unavailable content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object result: type: object success: type: boolean required: - success - result - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Account x-api-token-group: - AI Gateway Write - AI Gateway Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: ai-gateway.logging-state x-fern-sdk-method-name: get patch: operationId: aig-config-patch-logging-state summary: Migrate AI Gateway logging to Workers Observability description: Irreversibly migrates an eligible account to Workers Observability logging. parameters: - name: account_id in: path required: true schema: type: string responses: '200': description: Returns the migrated account logging state content: application/json: schema: type: object properties: result: type: object properties: migrated_at: type: integer minimum: 0 nullable: true migration_available: type: boolean platform: type: string enum: - legacy - workers_observability required: - platform - migrated_at - migration_available success: type: boolean required: - success - result '409': description: Migration is not available for this account content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object result: type: object success: type: boolean required: - success - result - errors '503': description: Logging state is temporarily unavailable content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object result: type: object success: type: boolean required: - success - result - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Account x-api-token-group: - AI Gateway Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.aig x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: ai-gateway.logging-state x-fern-sdk-method-name: update /accounts/{account_id}/ai-search/instances: get: operationId: ai-search-list-instances summary: List AI Search instances. description: List all AI Search instances in the account. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query description: Page number (1-indexed). schema: description: Page number (1-indexed). type: integer example: 1 default: 1 minimum: 1 - name: per_page in: query description: Number of results per page. schema: description: Number of results per page. type: integer example: 20 default: 20 maximum: 100 minimum: 1 - name: search in: query description: Filter instances whose id contains this string (case-insensitive). schema: description: Filter instances whose id contains this string (case-insensitive). type: string maxLength: 64 - name: namespace in: query description: Filter by namespace. schema: description: Filter by namespace. type: string pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ - name: order_by in: query description: Field to order results by. schema: description: Field to order results by. type: string default: created_at enum: - created_at - name: order_by_direction in: query description: Order direction. schema: description: Order direction. type: string default: desc enum: - asc - desc responses: '200': description: List of instances. content: application/json: schema: type: object properties: result: type: array items: additionalProperties: false properties: ai_gateway_id: type: string nullable: true ai_search_model: type: string nullable: true cache: type: boolean cache_threshold: type: string enum: - super_strict_match - close_enough - flexible_friend - anything_goes - null nullable: true cache_ttl: anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number chunk: type: boolean chunk_overlap: type: number nullable: true chunk_size: type: number nullable: true created_at: type: string format: date-time created_by: type: string nullable: true custom_metadata: type: array items: additionalProperties: false properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string required: - field_name - data_type type: object nullable: true embedding_model: type: string nullable: true enable: type: boolean engine_version: type: number fusion_method: type: string enum: - max - rrf hybrid_search_enabled: type: boolean id: type: string index_method: type: object additionalProperties: true properties: keyword: type: boolean vector: type: boolean required: - vector - keyword indexing_options: type: object additionalProperties: true nullable: true properties: keyword_tokenizer: type: string enum: - porter - trigram last_activity: type: string format: date-time nullable: true max_num_results: type: number nullable: true metadata: type: object additionalProperties: true nullable: true properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string modified_at: type: string format: date-time modified_by: type: string nullable: true namespace: type: string pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ paused: type: boolean public_endpoint_id: type: string nullable: true public_endpoint_params: type: object additionalProperties: true nullable: true properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object additionalProperties: true properties: disabled: type: boolean custom_domains: type: array items: maxLength: 253 minLength: 1 pattern: ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$ type: string maxItems: 1 nullable: true default_domain_enabled: type: boolean enabled: type: boolean mcp: type: object additionalProperties: true properties: description: type: string disabled: type: boolean rate_limit: type: object additionalProperties: true properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object additionalProperties: true properties: disabled: type: boolean reranking: type: boolean reranking_model: type: string nullable: true retrieval_options: type: object additionalProperties: true nullable: true properties: boost_by: type: array items: additionalProperties: true properties: dataType: type: string enum: - number - datetime - text - boolean direction: type: string enum: - asc - desc - exists - not_exists field: type: string maxLength: 64 minLength: 1 required: - field type: object maxItems: 3 keyword_match_mode: type: string enum: - and - or rewrite_model: type: string nullable: true rewrite_query: type: boolean score_threshold: type: number nullable: true source: type: string nullable: true source_params: type: object additionalProperties: true nullable: true properties: exclude_items: type: array items: type: string include_items: type: array items: type: string prefix: type: string r2_jurisdiction: type: string web_crawler: type: object additionalProperties: true properties: discover_options: type: object additionalProperties: true properties: depth: type: number maximum: 100000 minimum: 1 include_external_links: type: boolean include_subdomains: type: boolean limit: description: Maximum number of pages to crawl. New values are capped at 100000; instances configured before that cap may report a higher stored value, which the crawler clamps at run time. type: number maximum: 100000 minimum: 1 max_age: type: number maximum: 604800 minimum: 0 source: type: string enum: - all - sitemaps - links parse_options: type: object additionalProperties: true properties: content_selector: type: array items: additionalProperties: true properties: path: type: string maxLength: 200 minLength: 1 selector: type: string maxLength: 200 minLength: 1 required: - path - selector type: object maxItems: 10 include_headers: type: object additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean specific_sitemaps: type: array items: format: uri type: string maxItems: 10 use_browser_rendering: type: boolean parse_type: type: string enum: - sitemap - discover status: type: string summarization: type: boolean summarization_model: type: string nullable: true sync_interval: anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number system_prompt_ai_search: type: string nullable: true system_prompt_index_summarization: type: string nullable: true system_prompt_rewrite_query: type: string nullable: true token_id: type: string nullable: true type: type: string enum: - r2 - web-crawler - null nullable: true required: - id - engine_version - enable - type - source - source_params - ai_gateway_id - token_id - cache - cache_threshold - cache_ttl - summarization - rewrite_query - reranking - index_method - hybrid_search_enabled - fusion_method - indexing_options - retrieval_options - summarization_model - embedding_model - rewrite_model - ai_search_model - reranking_model - system_prompt_ai_search - system_prompt_index_summarization - system_prompt_rewrite_query - chunk - chunk_size - chunk_overlap - score_threshold - max_num_results - public_endpoint_id - public_endpoint_params - paused - status - metadata - custom_metadata - sync_interval - created_at - created_by - modified_at - modified_by - last_activity - namespace type: object result_info: type: object properties: count: type: number page: type: number per_page: type: number total_count: type: number required: - page - per_page - count - total_count success: type: boolean enum: - true required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: list post: operationId: ai-search-create-instance summary: Create an AI Search instance. description: Create a new AI Search instance with the given configuration. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk: type: boolean default: true x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id responses: '201': description: Returns the new instance. content: application/json: schema: type: object properties: result: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true enable: type: boolean default: true x-auditable: true engine_version: type: number default: 3 readOnly: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true last_activity: type: string format: date-time nullable: true readOnly: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true namespace: type: string nullable: true pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ readOnly: true paused: type: boolean default: false x-auditable: true public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true status: type: string default: waiting readOnly: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id - created_at - modified_at success: type: boolean required: - success - result '400': description: Ai search instance invalid token. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '403': description: Max instances reached. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: create /accounts/{account_id}/ai-search/instances/{id}: delete: operationId: ai-search-delete-instance summary: Delete an AI Search instance. description: Permanently delete an AI Search instance and all its indexed data. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string example: my-ai-search responses: '200': description: Returns the deleted instance. content: application/json: schema: type: object properties: result: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true enable: type: boolean default: true x-auditable: true engine_version: type: number default: 3 readOnly: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true last_activity: type: string format: date-time nullable: true readOnly: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true namespace: type: string nullable: true pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ readOnly: true paused: type: boolean default: false x-auditable: true public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true status: type: string default: waiting readOnly: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id - created_at - modified_at success: type: boolean required: - success - result '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: delete x-forge-require-confirmation: This operation permanently deletes the AI Search instance and all its indexed data. get: operationId: ai-search-fetch-instance summary: Get an AI Search instance. description: Retrieve the configuration and status of an AI Search instance. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string example: my-ai-search responses: '200': description: Returns the instance. content: application/json: schema: type: object properties: result: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true enable: type: boolean default: true x-auditable: true engine_version: type: number default: 3 readOnly: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true last_activity: type: string format: date-time nullable: true readOnly: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true namespace: type: string nullable: true pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ readOnly: true paused: type: boolean default: false x-auditable: true public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true status: type: string default: waiting readOnly: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id - created_at - modified_at success: type: boolean required: - success - result '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: get put: operationId: ai-search-update-instance summary: Update an AI Search instance. description: Update the configuration of an AI Search instance. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string example: my-ai-search requestBody: content: application/json: schema: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk: type: boolean default: true x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true paused: type: boolean default: false x-auditable: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true summarization: type: boolean default: false x-auditable: true summarization_model: type: string nullable: true x-auditable: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true system_prompt_ai_search: type: string nullable: true x-auditable: true system_prompt_index_summarization: type: string nullable: true x-auditable: true system_prompt_rewrite_query: type: string nullable: true x-auditable: true token_id: type: string format: uuid x-auditable: true responses: '200': description: Returns the updated instance. content: application/json: schema: type: object properties: result: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true enable: type: boolean default: true x-auditable: true engine_version: type: number default: 3 readOnly: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true last_activity: type: string format: date-time nullable: true readOnly: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true namespace: type: string nullable: true pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ readOnly: true paused: type: boolean default: false x-auditable: true public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true status: type: string default: waiting readOnly: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id - created_at - modified_at success: type: boolean required: - success - result '400': description: Ai search instance invalid token. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: update /accounts/{account_id}/ai-search/instances/{id}/chat/completions: post: operationId: ai-search-instance-chat-completion summary: Chat Completions description: Performs a chat completion request against an AI Search instance, using indexed content as context for generating responses. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: ai_search_options: type: object properties: cache: type: object properties: cache_threshold: type: string enum: - super_strict_match - close_enough - flexible_friend - anything_goes enabled: type: boolean query_rewrite: type: object properties: enabled: type: boolean model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string rewrite_prompt: type: string reranking: type: object properties: enabled: type: boolean match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 model: type: string retrieval: type: object properties: boost_by: description: Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 context_expansion: type: integer default: 0 maximum: 3 minimum: 0 filters: type: object additionalProperties: true fusion_method: type: string enum: - max - rrf keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'. type: string enum: - and - or match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 max_num_results: type: integer default: 10 maximum: 50 minimum: 1 retrieval_type: type: string enum: - vector - keyword - hybrid return_on_failure: type: boolean default: true messages: type: array items: additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content type: object minItems: 1 model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string stream: type: boolean additionalProperties: true required: - messages responses: '200': description: Returns the chat completions results with retrieved files. content: application/json: schema: type: object properties: choices: type: array items: properties: index: type: integer message: type: object additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content required: - message type: object chunks: type: array items: properties: id: type: string item: type: object properties: key: type: string metadata: type: object additionalProperties: true timestamp: type: number required: - key score: type: number maximum: 1 minimum: 0 scoring_details: type: object properties: fusion_method: type: string enum: - rrf - max keyword_rank: type: number keyword_score: type: number minimum: 0 reranking_score: type: number maximum: 1 minimum: 0 vector_rank: type: number vector_score: type: number maximum: 1 minimum: 0 text: type: string type: type: string required: - id - type - score - text type: object id: type: string model: type: string object: type: string additionalProperties: true required: - choices - chunks '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-ignore: true x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: chat-completions /accounts/{account_id}/ai-search/instances/{id}/jobs: get: operationId: ai-search-instance-list-jobs summary: List Jobs description: Lists indexing jobs for an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 50 minimum: 0 responses: '200': description: Returns a list of AI Search Jobs. content: application/json: schema: type: object properties: result: type: array items: properties: description: type: string end_reason: type: string ended_at: type: string id: type: string x-auditable: true last_seen_at: type: string source: type: string enum: - user - schedule x-auditable: true started_at: type: string required: - id - source type: object result_info: type: object properties: count: type: integer page: type: integer per_page: type: integer total_count: type: integer required: - count - page - per_page - total_count success: type: boolean required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: list post: operationId: ai-search-instance-create-job summary: Create new job description: Creates a new indexing job for an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: description: type: string maxLength: 255 responses: '200': description: Returns the AI Search job id. content: application/json: schema: type: object properties: result: type: object properties: description: type: string end_reason: type: string ended_at: type: string id: type: string x-auditable: true last_seen_at: type: string source: type: string enum: - user - schedule x-auditable: true started_at: type: string required: - id - source success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '429': description: Sync in cooldown. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: create /accounts/{account_id}/ai-search/instances/{id}/jobs/{job_id}: get: operationId: ai-search-instance-get-job summary: Get a Job Details description: Retrieves details for a specific AI Search indexing job. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: job_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 responses: '200': description: Returns a AI Search Job Details. content: application/json: schema: type: object properties: result: type: object properties: description: type: string end_reason: type: string ended_at: type: string id: type: string x-auditable: true last_seen_at: type: string source: type: string enum: - user - schedule x-auditable: true started_at: type: string required: - id - source success: type: boolean required: - success - result '404': description: Job not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: get patch: operationId: ai-search-instance-change-job-status summary: Cancel an indexing job. description: Cancel an in-progress indexing job for an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: job_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: action: type: string enum: - cancel required: - action responses: '200': description: Returns the updated AI Search Job. content: application/json: schema: type: object properties: result: type: object properties: description: type: string end_reason: type: string ended_at: type: string id: type: string x-auditable: true last_seen_at: type: string source: type: string enum: - user - schedule x-auditable: true started_at: type: string required: - id - source success: type: boolean required: - success - result '400': description: Job cannot be cancelled. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Job not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: cancel x-forge-require-confirmation: This operation cancels the running indexing job. /accounts/{account_id}/ai-search/instances/{id}/jobs/{job_id}/logs: get: operationId: ai-search-instance-list-job-logs summary: List Job Logs description: Lists log entries for an AI Search indexing job. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: job_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 500 minimum: 0 responses: '200': description: Returns a list of AI Search Job Logs. content: application/json: schema: type: object properties: result: type: array items: properties: created_at: type: number id: type: integer message: type: string message_type: type: integer required: - id - message - message_type - created_at type: object result_info: type: object properties: count: type: integer page: type: integer per_page: type: integer total_count: type: integer required: - count - page - per_page - total_count success: type: boolean required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: logs /accounts/{account_id}/ai-search/instances/{id}/search: post: operationId: ai-search-instance-search summary: Search description: Executes a semantic search query against an AI Search instance to find relevant indexed content. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: ai_search_options: type: object properties: cache: type: object properties: cache_threshold: type: string enum: - super_strict_match - close_enough - flexible_friend - anything_goes enabled: type: boolean query_rewrite: type: object properties: enabled: type: boolean model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string rewrite_prompt: type: string reranking: type: object properties: enabled: type: boolean match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 model: type: string retrieval: type: object properties: boost_by: description: Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 context_expansion: type: integer default: 0 maximum: 3 minimum: 0 filters: type: object additionalProperties: true fusion_method: type: string enum: - max - rrf keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'. type: string enum: - and - or match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 max_num_results: type: integer default: 10 maximum: 50 minimum: 1 retrieval_type: type: string enum: - vector - keyword - hybrid return_on_failure: type: boolean default: true messages: description: "OpenAI-compatible message array. For multimodal queries, set the last user message's `content` to an array of typed parts: `[{type:'text', text:'…'}, {type:'image_url', image_url:{url:'…'}}]`. Image inputs require the RAG's embedding_model to declare 'image' in supported_modalities." type: array items: additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content type: object minItems: 1 query: description: A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both. minLength: 1 type: string responses: '200': description: Returns the search results. content: application/json: schema: type: object properties: result: type: object properties: chunks: type: array items: properties: id: type: string item: type: object properties: key: type: string metadata: type: object additionalProperties: true timestamp: type: number required: - key score: type: number maximum: 1 minimum: 0 scoring_details: type: object properties: fusion_method: type: string enum: - rrf - max keyword_rank: type: number keyword_score: type: number minimum: 0 reranking_score: type: number maximum: 1 minimum: 0 vector_rank: type: number vector_score: type: number maximum: 1 minimum: 0 text: type: string type: type: string required: - id - type - score - text type: object query_kind: type: string enum: - text - image - multimodal search_query: type: string required: - query_kind - chunks success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: search /accounts/{account_id}/ai-search/instances/{id}/stats: get: operationId: ai-search-stats summary: Get instance statistics. description: Retrieve usage and indexing statistics for an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 responses: '200': description: Returns the AI Search stats. content: application/json: schema: type: object properties: result: type: object properties: completed: type: integer degraded: description: True when status counts are unavailable (e.g. legacy stats query exceeded D1 statement-size limit). Counts are omitted in this case. type: boolean engine: description: Engine-specific metadata. Present only for managed (v3) instances. type: object properties: r2: description: R2 bucket storage usage in bytes. type: object properties: metadataSizeBytes: type: integer objectCount: type: integer payloadSizeBytes: type: integer required: - payloadSizeBytes - metadataSizeBytes - objectCount vectorize: description: Vectorize index metadata (dimensions, vector count). type: object properties: dimensions: type: integer vectorsCount: type: integer required: - vectorsCount - dimensions error: type: integer file_embed_errors: type: object additionalProperties: true index_source_errors: type: object additionalProperties: true last_activity: type: string format: date-time outdated: type: integer queued: type: integer running: type: integer skipped: type: integer success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-ignore: true x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: stats /accounts/{account_id}/ai-search/namespaces: get: operationId: ai-search-list-namespaces summary: List namespaces description: List namespaces in the account, including their descriptions and creation times. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query description: Page number (1-indexed). schema: description: Page number (1-indexed). type: integer example: 1 default: 1 minimum: 1 - name: per_page in: query description: Number of results per page. schema: description: Number of results per page. type: integer example: 20 default: 20 maximum: 100 minimum: 1 - name: search in: query description: Filter namespaces whose name or description contains this string (case-insensitive). schema: description: Filter namespaces whose name or description contains this string (case-insensitive). type: string example: prod maxLength: 256 responses: '200': description: List of namespaces. content: application/json: schema: type: object properties: result: type: array items: properties: created_at: type: string format: date-time readOnly: true description: description: Optional description for the namespace. Max 256 characters. type: string example: Production environment maxLength: 256 nullable: true name: type: string example: production pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object nullable: true properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false instances_allowed: description: Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit. type: array items: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ type: string x-auditable: true example: - docs - blog default: [] maxItems: 10 x-auditable: true mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true required: - name - created_at type: object result_info: type: object properties: count: type: number page: type: number per_page: type: number total_count: type: number required: - page - per_page - count - total_count success: type: boolean enum: - true required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Namespaces x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.namespace x-fern-sdk-method-name: list post: operationId: ai-search-create-namespace summary: Create a namespace description: Create a namespace for organizing AI Search instances. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: description: description: Optional description for the namespace. Max 256 characters. type: string example: Production environment maxLength: 256 nullable: true name: type: string pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false instances_allowed: description: Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit. type: array items: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ type: string x-auditable: true example: - docs - blog default: [] maxItems: 10 x-auditable: true mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false required: - name responses: '201': description: Namespace created. content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time readOnly: true description: description: Optional description for the namespace. Max 256 characters. type: string example: Production environment maxLength: 256 nullable: true name: type: string example: production pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object nullable: true properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false instances_allowed: description: Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit. type: array items: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ type: string x-auditable: true example: - docs - blog default: [] maxItems: 10 x-auditable: true mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true required: - name - created_at success: type: boolean enum: - true required: - success - result '400': description: Instances allowed contains unknown instances. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '403': description: Max namespaces reached. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '409': description: Namespace already exists. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Namespaces x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.namespace x-fern-sdk-method-name: create x-forge-params: name: description: Name for the new namespace. flagName: namespace positional: true /accounts/{account_id}/ai-search/namespaces/{name}: delete: operationId: ai-search-delete-namespace summary: Delete a namespace description: Permanently delete a namespace. The namespace must be empty (no instances), and the default namespace cannot be deleted. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path required: true schema: type: string example: production responses: '200': description: Namespace deleted. content: application/json: schema: type: object properties: result: type: object additionalProperties: false success: type: boolean enum: - true required: - success - result '400': description: Namespace not empty. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Namespace not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Namespaces x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.namespace x-fern-sdk-method-name: delete x-forge-params: name: description: Namespace to delete. flagName: namespace x-forge-require-confirmation: This operation permanently deletes the namespace. get: operationId: ai-search-fetch-namespace summary: Get a namespace description: Retrieve a namespace and its description. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path required: true schema: type: string example: production responses: '200': description: Namespace details. content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time readOnly: true description: description: Optional description for the namespace. Max 256 characters. type: string example: Production environment maxLength: 256 nullable: true name: type: string example: production pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object nullable: true properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false instances_allowed: description: Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit. type: array items: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ type: string x-auditable: true example: - docs - blog default: [] maxItems: 10 x-auditable: true mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true required: - name - created_at success: type: boolean enum: - true required: - success - result '404': description: Namespace not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Namespaces x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.namespace x-fern-sdk-method-name: get x-forge-params: name: description: Namespace to retrieve. flagName: namespace put: operationId: ai-search-update-namespace summary: Update a namespace description: Update the description and/or the public endpoint configuration of an existing namespace. The default namespace's description cannot be modified, but its public endpoint can. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path required: true schema: type: string example: production requestBody: content: application/json: schema: type: object properties: description: description: Optional description for the namespace. Max 256 characters. type: string example: Production environment maxLength: 256 nullable: true public_endpoint_params: type: object nullable: true properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false instances_allowed: description: Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit. type: array items: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ type: string x-auditable: true example: - docs - blog default: [] maxItems: 10 x-auditable: true mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false responses: '200': description: Returns the updated namespace. content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time readOnly: true description: description: Optional description for the namespace. Max 256 characters. type: string example: Production environment maxLength: 256 nullable: true name: type: string example: production pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object nullable: true properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false instances_allowed: description: Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit. type: array items: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ type: string x-auditable: true example: - docs - blog default: [] maxItems: 10 x-auditable: true mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true required: - name - created_at success: type: boolean enum: - true required: - success - result '400': description: Instances allowed contains unknown instances. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Namespace not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '409': description: Namespace modified concurrently please retry. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Namespaces x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.namespace x-fern-sdk-method-name: update x-forge-params: name: description: Namespace to update. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/chat/completions: post: operationId: ai-search-namespace-multi-instance-chat-completion summary: Multi-Instance Chat Completions description: Performs a chat completion request against multiple AI Search instances in parallel, merging retrieved content as context for generating a response. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: ai_search_options: type: object properties: cache: type: object properties: cache_threshold: type: string enum: - super_strict_match - close_enough - flexible_friend - anything_goes enabled: type: boolean instance_ids: type: array items: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ type: string x-auditable: true minItems: 1 query_rewrite: type: object properties: enabled: type: boolean model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string rewrite_prompt: type: string reranking: type: object properties: enabled: type: boolean match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 model: type: string retrieval: type: object properties: boost_by: description: Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 context_expansion: type: integer default: 0 maximum: 3 minimum: 0 filters: type: object additionalProperties: true fusion_method: type: string enum: - max - rrf keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'. type: string enum: - and - or match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 max_num_results: type: integer default: 10 maximum: 50 minimum: 1 retrieval_type: type: string enum: - vector - keyword - hybrid return_on_failure: type: boolean default: true required: - instance_ids messages: type: array items: additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content type: object minItems: 1 model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string stream: type: boolean additionalProperties: true required: - messages - ai_search_options responses: '200': description: Returns the chat completion result with merged chunks from all instances. content: application/json: schema: type: object properties: choices: type: array items: properties: index: type: integer message: type: object additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content required: - message type: object chunks: type: array items: properties: id: type: string instance_id: type: string item: type: object properties: key: type: string metadata: type: object additionalProperties: true timestamp: type: number required: - key score: type: number maximum: 1 minimum: 0 scoring_details: type: object properties: fusion_method: type: string enum: - rrf - max keyword_rank: type: number keyword_score: type: number minimum: 0 reranking_score: type: number maximum: 1 minimum: 0 vector_rank: type: number vector_score: type: number maximum: 1 minimum: 0 text: type: string type: type: string required: - id - type - score - text - instance_id type: object errors: type: array items: properties: instance_id: type: string message: type: string required: - instance_id - message type: object id: type: string model: type: string object: type: string additionalProperties: true required: - choices - chunks '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Account Search x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: multi-chat-completions x-forge-params: name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/instances: get: operationId: ai-search-namespace-list-instances summary: List AI Search instances. description: List all AI Search instances in the account. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query description: Page number (1-indexed). schema: description: Page number (1-indexed). type: integer example: 1 default: 1 minimum: 1 - name: per_page in: query description: Number of results per page. schema: description: Number of results per page. type: integer example: 20 default: 20 maximum: 100 minimum: 1 - name: search in: query description: Filter instances whose id contains this string (case-insensitive). schema: description: Filter instances whose id contains this string (case-insensitive). type: string maxLength: 64 - name: namespace in: query description: Filter by namespace. schema: description: Filter by namespace. type: string pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ - name: order_by in: query description: Field to order results by. schema: description: Field to order results by. type: string default: created_at enum: - created_at - name: order_by_direction in: query description: Order direction. schema: description: Order direction. type: string default: desc enum: - asc - desc - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: List of instances. content: application/json: schema: type: object properties: result: type: array items: additionalProperties: false properties: ai_gateway_id: type: string nullable: true ai_search_model: type: string nullable: true cache: type: boolean cache_threshold: type: string enum: - super_strict_match - close_enough - flexible_friend - anything_goes - null nullable: true cache_ttl: anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number chunk: type: boolean chunk_overlap: type: number nullable: true chunk_size: type: number nullable: true created_at: type: string format: date-time created_by: type: string nullable: true custom_metadata: type: array items: additionalProperties: false properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string required: - field_name - data_type type: object nullable: true embedding_model: type: string nullable: true enable: type: boolean engine_version: type: number fusion_method: type: string enum: - max - rrf hybrid_search_enabled: type: boolean id: type: string index_method: type: object additionalProperties: true properties: keyword: type: boolean vector: type: boolean required: - vector - keyword indexing_options: type: object additionalProperties: true nullable: true properties: keyword_tokenizer: type: string enum: - porter - trigram last_activity: type: string format: date-time nullable: true max_num_results: type: number nullable: true metadata: type: object additionalProperties: true nullable: true properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string modified_at: type: string format: date-time modified_by: type: string nullable: true namespace: type: string pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ paused: type: boolean public_endpoint_id: type: string nullable: true public_endpoint_params: type: object additionalProperties: true nullable: true properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object additionalProperties: true properties: disabled: type: boolean custom_domains: type: array items: maxLength: 253 minLength: 1 pattern: ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$ type: string maxItems: 1 nullable: true default_domain_enabled: type: boolean enabled: type: boolean mcp: type: object additionalProperties: true properties: description: type: string disabled: type: boolean rate_limit: type: object additionalProperties: true properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object additionalProperties: true properties: disabled: type: boolean reranking: type: boolean reranking_model: type: string nullable: true retrieval_options: type: object additionalProperties: true nullable: true properties: boost_by: type: array items: additionalProperties: true properties: dataType: type: string enum: - number - datetime - text - boolean direction: type: string enum: - asc - desc - exists - not_exists field: type: string maxLength: 64 minLength: 1 required: - field type: object maxItems: 3 keyword_match_mode: type: string enum: - and - or rewrite_model: type: string nullable: true rewrite_query: type: boolean score_threshold: type: number nullable: true source: type: string nullable: true source_params: type: object additionalProperties: true nullable: true properties: exclude_items: type: array items: type: string include_items: type: array items: type: string prefix: type: string r2_jurisdiction: type: string web_crawler: type: object additionalProperties: true properties: discover_options: type: object additionalProperties: true properties: depth: type: number maximum: 100000 minimum: 1 include_external_links: type: boolean include_subdomains: type: boolean limit: description: Maximum number of pages to crawl. New values are capped at 100000; instances configured before that cap may report a higher stored value, which the crawler clamps at run time. type: number maximum: 100000 minimum: 1 max_age: type: number maximum: 604800 minimum: 0 source: type: string enum: - all - sitemaps - links parse_options: type: object additionalProperties: true properties: content_selector: type: array items: additionalProperties: true properties: path: type: string maxLength: 200 minLength: 1 selector: type: string maxLength: 200 minLength: 1 required: - path - selector type: object maxItems: 10 include_headers: type: object additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean specific_sitemaps: type: array items: format: uri type: string maxItems: 10 use_browser_rendering: type: boolean parse_type: type: string enum: - sitemap - discover status: type: string summarization: type: boolean summarization_model: type: string nullable: true sync_interval: anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number system_prompt_ai_search: type: string nullable: true system_prompt_index_summarization: type: string nullable: true system_prompt_rewrite_query: type: string nullable: true token_id: type: string nullable: true type: type: string enum: - r2 - web-crawler - null nullable: true required: - id - engine_version - enable - type - source - source_params - ai_gateway_id - token_id - cache - cache_threshold - cache_ttl - summarization - rewrite_query - reranking - index_method - hybrid_search_enabled - fusion_method - indexing_options - retrieval_options - summarization_model - embedding_model - rewrite_model - ai_search_model - reranking_model - system_prompt_ai_search - system_prompt_index_summarization - system_prompt_rewrite_query - chunk - chunk_size - chunk_overlap - score_threshold - max_num_results - public_endpoint_id - public_endpoint_params - paused - status - metadata - custom_metadata - sync_interval - created_at - created_by - modified_at - modified_by - last_activity - namespace type: object result_info: type: object properties: count: type: number page: type: number per_page: type: number total_count: type: number required: - page - per_page - count - total_count success: type: boolean enum: - true required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: list x-forge-params: name: default: default description: Namespace to use for this operation. flagName: namespace namespace: hidden: true post: operationId: ai-search-namespace-create-instance summary: Create an AI Search instance. description: Create a new AI Search instance with the given configuration. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk: type: boolean default: true x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id responses: '201': description: Returns the new instance. content: application/json: schema: type: object properties: result: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true enable: type: boolean default: true x-auditable: true engine_version: type: number default: 3 readOnly: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true last_activity: type: string format: date-time nullable: true readOnly: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true namespace: type: string nullable: true pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ readOnly: true paused: type: boolean default: false x-auditable: true public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true status: type: string default: waiting readOnly: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id - created_at - modified_at success: type: boolean required: - success - result '400': description: Ai search instance invalid token. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '403': description: Max instances reached. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: create x-forge-params: id: description: Unique ID for the new AI Search instance. positional: true name: default: default description: Namespace to use for this operation. flagName: namespace source: description: R2 bucket name or root website URL to index. source_params: description: Optional data source settings as a JSON object. type: description: 'Data source type: r2 or web-crawler.' /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}: delete: operationId: ai-search-namespace-delete-instance summary: Delete an AI Search instance. description: Permanently delete an AI Search instance and all its indexed data. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string example: my-ai-search - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns the deleted instance. content: application/json: schema: type: object properties: result: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true enable: type: boolean default: true x-auditable: true engine_version: type: number default: 3 readOnly: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true last_activity: type: string format: date-time nullable: true readOnly: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true namespace: type: string nullable: true pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ readOnly: true paused: type: boolean default: false x-auditable: true public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true status: type: string default: waiting readOnly: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id - created_at - modified_at success: type: boolean required: - success - result '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: delete x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace x-forge-require-confirmation: This operation permanently deletes the AI Search instance and all its indexed data. get: operationId: ai-search-namespace-fetch-instance summary: Get an AI Search instance. description: Retrieve the configuration and status of an AI Search instance. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string example: my-ai-search - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns the instance. content: application/json: schema: type: object properties: result: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true enable: type: boolean default: true x-auditable: true engine_version: type: number default: 3 readOnly: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true last_activity: type: string format: date-time nullable: true readOnly: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true namespace: type: string nullable: true pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ readOnly: true paused: type: boolean default: false x-auditable: true public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true status: type: string default: waiting readOnly: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id - created_at - modified_at success: type: boolean required: - success - result '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: get x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace patch: operationId: ai-search-move-instance summary: Move an instance to a different namespace. description: Moves an instance from its current namespace to the specified target namespace. Use 'default' with --destination-namespace to move the instance back to the default namespace. Fails with 400 if the target namespace already has an instance with the same id (ids must be unique within a namespace — the same id can exist in different namespaces). parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Current namespace of the instance. required: true schema: description: Current namespace of the instance. type: string example: production - name: id in: path description: Instance id. required: true schema: description: Instance id. type: string example: my-blog requestBody: content: application/json: schema: type: object properties: new_namespace: description: Target namespace to move the instance into. type: string example: staging pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ required: - new_namespace responses: '200': description: Instance moved. content: application/json: schema: type: object properties: result: type: object additionalProperties: false success: type: boolean enum: - true required: - success - result '400': description: Ai search with this name already exist. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Namespaces x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: move x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace currently containing the instance. flagName: source-namespace new_namespace: description: Namespace to move the instance into. flagName: destination-namespace put: operationId: ai-search-namespace-update-instance summary: Update an AI Search instance. description: Update the configuration of an AI Search instance. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string example: my-ai-search - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk: type: boolean default: true x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true paused: type: boolean default: false x-auditable: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true summarization: type: boolean default: false x-auditable: true summarization_model: type: string nullable: true x-auditable: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true system_prompt_ai_search: type: string nullable: true x-auditable: true system_prompt_index_summarization: type: string nullable: true x-auditable: true system_prompt_rewrite_query: type: string nullable: true x-auditable: true token_id: type: string format: uuid x-auditable: true responses: '200': description: Returns the updated instance. content: application/json: schema: type: object properties: result: type: object properties: ai_gateway_id: type: string nullable: true x-auditable: true ai_search_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true cache: type: boolean default: true x-auditable: true cache_threshold: type: string default: close_enough enum: - super_strict_match - close_enough - flexible_friend - anything_goes x-auditable: true cache_ttl: description: 'Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).' default: 172800 anyOf: - enum: - 600 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number - enum: - 172800 type: number - enum: - 259200 type: number - enum: - 518400 type: number x-auditable: true chunk_overlap: type: integer default: 10 maximum: 30 minimum: 0 x-auditable: true chunk_size: type: integer minimum: 64 x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true custom_metadata: type: array items: properties: data_type: type: string enum: - text - number - boolean - datetime field_name: type: string maxLength: 64 minLength: 1 required: - field_name - data_type type: object maxItems: 5 x-auditable: true embedding_model: type: string nullable: true x-auditable: true enable: type: boolean default: true x-auditable: true engine_version: type: number default: 3 readOnly: true fusion_method: type: string default: rrf enum: - max - rrf x-auditable: true hybrid_search_enabled: description: Deprecated — use index_method instead. type: boolean default: false deprecated: true x-auditable: true id: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true index_method: description: Controls which storage backends are used during indexing. Defaults to vector-only. type: object default: keyword: false vector: true properties: keyword: description: Enable keyword (BM25) storage backend. type: boolean vector: description: Enable vector (embedding) storage backend. type: boolean required: - vector - keyword x-auditable: true indexing_options: type: object nullable: true properties: keyword_tokenizer: description: Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter. type: string default: porter enum: - porter - trigram x-auditable: true last_activity: type: string format: date-time nullable: true readOnly: true max_num_results: type: integer default: 10 maximum: 50 minimum: 1 x-auditable: true metadata: type: object properties: created_from_aisearch_wizard: type: boolean worker_domain: type: string x-auditable: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true namespace: type: string nullable: true pattern: ^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$ readOnly: true paused: type: boolean default: false x-auditable: true public_endpoint_id: type: string nullable: true readOnly: true public_endpoint_params: type: object properties: authorized_hosts: type: array items: type: string chat_completions_endpoint: type: object properties: disabled: description: Disable chat completions endpoint for this public endpoint type: boolean default: false custom_domains: description: Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged). type: array items: description: Custom domain hostname (must be a Verified zone on this account). example: search.example.com maxLength: 253 minLength: 1 type: string maxItems: 1 nullable: true x-auditable: true default_domain_enabled: description: When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true. type: boolean default: true x-auditable: true enabled: type: boolean default: false mcp: type: object properties: description: type: string default: Finds exactly what you're looking for disabled: description: Disable MCP endpoint for this public endpoint type: boolean default: false rate_limit: type: object properties: period_ms: type: integer maximum: 3600000 minimum: 60000 requests: type: integer minimum: 1 technique: type: string enum: - fixed - sliding search_endpoint: type: object properties: disabled: description: Disable search endpoint for this public endpoint type: boolean default: false x-auditable: true reranking: type: boolean default: false x-auditable: true reranking_model: type: string nullable: true x-auditable: true retrieval_options: type: object nullable: true properties: boost_by: description: Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'. type: string enum: - and - or x-auditable: true rewrite_model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string nullable: true x-auditable: true rewrite_query: type: boolean default: false x-auditable: true score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 x-auditable: true source: type: string nullable: true x-auditable: true source_params: type: object nullable: true properties: exclude_items: description: 'List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /admin/** - /private/** - '**\temp\**' maxItems: 10 include_items: description: 'List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.' type: array items: maxLength: 500 pattern: ^[*/\\]?[\w\-/.\\?*:=&%]+$ type: string example: - /blog/** - /docs/**/*.html - '**\blog\**.html' maxItems: 10 prefix: type: string r2_jurisdiction: type: string default: default web_crawler: type: object default: parse_type: sitemap properties: discover_options: description: Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'. type: object properties: depth: description: Maximum link-follow depth from the seed URL. type: number example: 5 default: 5 maximum: 100000 minimum: 1 include_external_links: description: Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own. type: boolean example: false default: false include_subdomains: description: Follow links to subdomains of the source host. type: boolean example: false default: false limit: description: Maximum number of pages to crawl (1-100000). type: number example: 10000 default: 100000 maximum: 100000 minimum: 1 max_age: description: Maximum content age in seconds to accept (0–604800). type: number example: 86400 default: 86400 maximum: 604800 minimum: 0 source: description: "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both." type: string example: all default: all enum: - all - sitemaps - links parse_options: type: object properties: content_selector: description: List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected. type: array items: properties: path: description: 'Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.' type: string example: '**/article/**' maxLength: 200 minLength: 1 selector: description: CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \). Must target a single element; if multiple elements match, the selector is ignored and the full page is used. type: string example: article div.post-body maxLength: 200 minLength: 1 required: - path - selector type: object example: - path: '**/blog/**' selector: article div.post-body - path: '**/docs/**' selector: main maxItems: 10 minItems: 1 include_headers: description: Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF). type: object example: cache-control: no-cache, no-store additionalProperties: maxLength: 8192 pattern: ^[\t\x20-\x7E]*$ type: string include_images: type: boolean default: false specific_sitemaps: description: List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'. type: array items: format: uri type: string example: - https://example.com/sitemap.xml - https://example.com/blog-sitemap.xml maxItems: 10 use_browser_rendering: type: boolean default: true parse_type: description: How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account. type: string example: sitemap default: sitemap enum: - sitemap - discover x-auditable: true status: type: string default: waiting readOnly: true sync_interval: description: 'Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).' default: 21600 anyOf: - enum: - 900 type: number - enum: - 1800 type: number - enum: - 3600 type: number - enum: - 7200 type: number - enum: - 14400 type: number - enum: - 21600 type: number - enum: - 43200 type: number - enum: - 86400 type: number x-auditable: true token_id: type: string format: uuid x-auditable: true type: type: string enum: - r2 - web-crawler - null nullable: true x-auditable: true required: - id - created_at - modified_at success: type: boolean required: - success - result '400': description: Ai search instance invalid token. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: update x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace source: description: R2 bucket name or root website URL to index. source_params: description: Optional data source settings as a JSON object. /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/chat/completions: post: operationId: ai-search-namespace-instance-chat-completion summary: Chat Completions description: Performs a chat completion request against an AI Search instance, using indexed content as context for generating responses. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: ai_search_options: type: object properties: cache: type: object properties: cache_threshold: type: string enum: - super_strict_match - close_enough - flexible_friend - anything_goes enabled: type: boolean query_rewrite: type: object properties: enabled: type: boolean model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string rewrite_prompt: type: string reranking: type: object properties: enabled: type: boolean match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 model: type: string retrieval: type: object properties: boost_by: description: Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 context_expansion: type: integer default: 0 maximum: 3 minimum: 0 filters: type: object additionalProperties: true fusion_method: type: string enum: - max - rrf keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'. type: string enum: - and - or match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 max_num_results: type: integer default: 10 maximum: 50 minimum: 1 retrieval_type: type: string enum: - vector - keyword - hybrid return_on_failure: type: boolean default: true messages: type: array items: additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content type: object minItems: 1 model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string stream: type: boolean additionalProperties: true required: - messages responses: '200': description: Returns the chat completions results with retrieved files. content: application/json: schema: type: object properties: choices: type: array items: properties: index: type: integer message: type: object additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content required: - message type: object chunks: type: array items: properties: id: type: string item: type: object properties: key: type: string metadata: type: object additionalProperties: true timestamp: type: number required: - key score: type: number maximum: 1 minimum: 0 scoring_details: type: object properties: fusion_method: type: string enum: - rrf - max keyword_rank: type: number keyword_score: type: number minimum: 0 reranking_score: type: number maximum: 1 minimum: 0 vector_rank: type: number vector_score: type: number maximum: 1 minimum: 0 text: type: string type: type: string required: - id - type - score - text type: object id: type: string model: type: string object: type: string additionalProperties: true required: - choices - chunks '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: chat-completions x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items: get: operationId: ai-search-namespace-instance-list-items summary: Items List. description: Lists indexed items in an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 50 minimum: 0 - name: search in: query schema: type: string maxLength: 256 - name: sort_by in: query description: Sort order for items. "status" (default) sorts by status priority then last_seen_at. "modified_at" sorts by file modification time (most recent first), falling back to created_at. schema: description: Sort order for items. "status" (default) sorts by status priority then last_seen_at. "modified_at" sorts by file modification time (most recent first), falling back to created_at. type: string default: status enum: - status - modified_at - name: status in: query schema: type: string enum: - queued - running - completed - error - skipped - outdated - name: source in: query description: Filter items by source_id. Use "builtin" for uploaded files, or a source identifier like "web-crawler:https://example.com". schema: description: Filter items by source_id. Use "builtin" for uploaded files, or a source identifier like "web-crawler:https://example.com". type: string maxLength: 512 - name: metadata_filter in: query description: 'JSON-encoded metadata filter using Vectorize filter syntax. Examples: {"folder":"reports/"}, {"timestamp":{"$gte":1700000000000}}, {"folder":{"$in":["docs/","reports/"]}}' schema: description: 'JSON-encoded metadata filter using Vectorize filter syntax. Examples: {"folder":"reports/"}, {"timestamp":{"$gte":1700000000000}}, {"folder":{"$in":["docs/","reports/"]}}' type: string maxLength: 2048 - name: item_id in: query description: Filter items by their unique ID. Returns at most one item. schema: description: Filter items by their unique ID. Returns at most one item. type: string maxLength: 64 - name: key in: query description: Filter items by their exact key (object key / filename). Keys are unique per source, so combine with `source` to disambiguate across data sources. schema: description: Filter items by their exact key (object key / filename). Keys are unique per source, so combine with `source` to disambiguate across data sources. type: string maxLength: 1024 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns the AI Search items. content: application/json: schema: type: object properties: result: type: array items: properties: checksum: type: string readOnly: true chunks_count: type: integer nullable: true readOnly: true x-auditable: true created_at: type: string format: date-time readOnly: true error: type: string readOnly: true file_size: type: number nullable: true readOnly: true x-auditable: true id: type: string readOnly: true key: type: string readOnly: true last_seen_at: type: string format: date-time readOnly: true metadata: description: Built-in, configured filterable, and retained source metadata for the item. type: object additionalProperties: anyOf: - type: string - type: number - type: boolean nullable: true readOnly: true namespace: type: string readOnly: true next_action: type: string enum: - INDEX - DELETE - null nullable: true readOnly: true source_id: description: Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items. type: string nullable: true readOnly: true status: type: string enum: - queued - running - completed - error - skipped - outdated readOnly: true required: - id - key - status - next_action - checksum - namespace - chunks_count - file_size - metadata - source_id - last_seen_at - created_at type: object result_info: type: object properties: count: type: integer page: type: integer per_page: type: integer default: 20 maximum: 50 minimum: 5 total_count: type: integer required: - count - page - total_count success: type: boolean required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: list x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace post: operationId: ai-search-namespace-instance-upload-item summary: Upload Item. description: Uploads a file to a managed AI Search instance via multipart/form-data. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: multipart/form-data: schema: type: object properties: file: description: The file to upload. Filename must not exceed 128 characters. type: string format: binary metadata: description: JSON string of custom metadata key-value pairs. type: string wait_for_completion: description: Wait for indexing to fully complete before responding. On RAGs with vector indexing enabled, this additionally waits for Vectorize ingestion confirmation (up to 40s) so the returned item reflects a queryable state. On timeout the item is returned in `running` state and the background alarm continues polling. Defaults to false. type: boolean default: false required: - file responses: '200': description: Item uploaded successfully. content: application/json: schema: type: object properties: result: type: object properties: checksum: type: string readOnly: true chunks_count: type: integer nullable: true readOnly: true x-auditable: true created_at: type: string format: date-time readOnly: true error: type: string readOnly: true file_size: type: number nullable: true readOnly: true x-auditable: true id: type: string readOnly: true key: type: string readOnly: true last_seen_at: type: string format: date-time readOnly: true metadata: description: Built-in, configured filterable, and retained source metadata for the item. type: object additionalProperties: anyOf: - type: string - type: number - type: boolean nullable: true readOnly: true namespace: type: string readOnly: true next_action: type: string enum: - INDEX - DELETE - null nullable: true readOnly: true source_id: description: Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items. type: string nullable: true readOnly: true status: type: string enum: - queued - running - completed - error - skipped - outdated readOnly: true warnings: type: array items: oneOf: - properties: code: type: string enum: - custom_metadata_value_not_indexed expected_type: type: string enum: - text - number - boolean - datetime field: type: string maxLength: 512 required: - code - field - expected_type type: object - properties: code: type: string enum: - custom_metadata_field_not_filterable field: type: string maxLength: 512 required: - code - field type: object maxItems: 10 required: - id - key - status - next_action - checksum - namespace - chunks_count - file_size - metadata - source_id - last_seen_at - created_at success: type: boolean required: - success - result '400': description: Invalid metadata format. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '409': description: Item key already exist. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '413': description: File exceeds maximum size. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '429': description: Item write rate limited. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: upload x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace put: operationId: ai-search-namespace-instance-create-or-update-item summary: Create or Update Item. description: Creates or updates an indexed item in an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: key: description: Item key / filename. Must not exceed 128 characters. type: string next_action: type: string enum: - INDEX wait_for_completion: description: Wait for indexing to fully complete before responding. On RAGs with vector indexing enabled, this additionally waits for Vectorize ingestion confirmation (up to 40s) so the returned item reflects a queryable state. On timeout the item is returned in `running` state and the background alarm continues polling. Defaults to false. type: boolean default: false required: - key - next_action responses: '200': description: Returns a AI Search Item detail. content: application/json: schema: type: object properties: result: type: object properties: checksum: type: string readOnly: true chunks_count: type: integer nullable: true readOnly: true x-auditable: true created_at: type: string format: date-time readOnly: true error: type: string readOnly: true file_size: type: number nullable: true readOnly: true x-auditable: true id: type: string readOnly: true key: type: string readOnly: true last_seen_at: type: string format: date-time readOnly: true metadata: description: Built-in, configured filterable, and retained source metadata for the item. type: object additionalProperties: anyOf: - type: string - type: number - type: boolean nullable: true readOnly: true namespace: type: string readOnly: true next_action: type: string enum: - INDEX - DELETE - null nullable: true readOnly: true source_id: description: Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items. type: string nullable: true readOnly: true status: type: string enum: - queued - running - completed - error - skipped - outdated readOnly: true required: - id - key - status - next_action - checksum - namespace - chunks_count - file_size - metadata - source_id - last_seen_at - created_at success: type: boolean required: - success - result '400': description: Filename exceeds maximum length. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '409': description: Item key already exist. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to sync item. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: upsert x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace next_action: default: INDEX hidden: true /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}: delete: operationId: ai-search-namespace-instance-delete-item summary: Delete Item. description: Deletes a file from a managed AI Search instance and triggers a reindex. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: item_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Item deleted successfully. content: application/json: schema: type: object properties: result: type: object properties: key: type: string required: - key success: type: boolean required: - success - result '400': description: This operation requires a managed instance. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Item not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: delete x-forge-params: id: description: AI Search instance ID. flagName: instance-id item_id: description: Indexed item ID. flagName: item-id name: default: default description: Namespace to use for this operation. flagName: namespace get: operationId: ai-search-namespace-instance-get-item summary: Get Item. description: Retrieves a specific indexed item from an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: item_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns a AI Search Item detail. content: application/json: schema: type: object properties: result: type: object properties: checksum: type: string readOnly: true chunks_count: type: integer nullable: true readOnly: true x-auditable: true created_at: type: string format: date-time readOnly: true error: type: string readOnly: true file_size: type: number nullable: true readOnly: true x-auditable: true id: type: string readOnly: true key: type: string readOnly: true last_seen_at: type: string format: date-time readOnly: true metadata: description: Built-in, configured filterable, and retained source metadata for the item. type: object additionalProperties: anyOf: - type: string - type: number - type: boolean nullable: true readOnly: true namespace: type: string readOnly: true next_action: type: string enum: - INDEX - DELETE - null nullable: true readOnly: true source_id: description: Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items. type: string nullable: true readOnly: true status: type: string enum: - queued - running - completed - error - skipped - outdated readOnly: true required: - id - key - status - next_action - checksum - namespace - chunks_count - file_size - metadata - source_id - last_seen_at - created_at success: type: boolean required: - success - result '404': description: Job not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: get x-forge-params: id: description: AI Search instance ID. flagName: instance-id item_id: description: Indexed item ID. flagName: item-id name: default: default description: Namespace to use for this operation. flagName: namespace patch: operationId: ai-search-namespace-instance-sync-item summary: Sync Item. description: Syncs an item to an AI Search instance index. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: item_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: next_action: type: string enum: - INDEX wait_for_completion: description: Wait for indexing to fully complete before responding. On RAGs with vector indexing enabled, this additionally waits for Vectorize ingestion confirmation (up to 40s) so the returned item reflects a queryable state. On timeout the item is returned in `running` state and the background alarm continues polling. Defaults to false. type: boolean default: false required: - next_action responses: '200': description: Returns a AI Search Item detail. content: application/json: schema: type: object properties: result: type: object properties: checksum: type: string readOnly: true chunks_count: type: integer nullable: true readOnly: true x-auditable: true created_at: type: string format: date-time readOnly: true error: type: string readOnly: true file_size: type: number nullable: true readOnly: true x-auditable: true id: type: string readOnly: true key: type: string readOnly: true last_seen_at: type: string format: date-time readOnly: true metadata: description: Built-in, configured filterable, and retained source metadata for the item. type: object additionalProperties: anyOf: - type: string - type: number - type: boolean nullable: true readOnly: true namespace: type: string readOnly: true next_action: type: string enum: - INDEX - DELETE - null nullable: true readOnly: true source_id: description: Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items. type: string nullable: true readOnly: true status: type: string enum: - queued - running - completed - error - skipped - outdated readOnly: true required: - id - key - status - next_action - checksum - namespace - chunks_count - file_size - metadata - source_id - last_seen_at - created_at success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to sync item. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: sync x-forge-params: id: description: AI Search instance ID. flagName: instance-id item_id: description: Indexed item ID. flagName: item-id name: default: default description: Namespace to use for this operation. flagName: namespace next_action: default: INDEX hidden: true /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/chunks: get: operationId: ai-search-namespace-instance-list-item-chunks summary: List Item Chunks. description: Lists chunks for a specific item in an AI Search instance, including their text content. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: item_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: limit in: query schema: type: integer default: 20 maximum: 100 minimum: 1 - name: offset in: query schema: type: integer default: 0 minimum: 0 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns the AI Search item chunks with text content. content: application/json: schema: type: object properties: result: type: array items: properties: end_byte: type: number id: type: string item: type: object properties: key: type: string metadata: type: object additionalProperties: true timestamp: type: number required: - key start_byte: type: number text: type: string required: - id - text - item type: object result_info: type: object properties: count: type: integer limit: type: integer offset: type: integer total: type: integer required: - count - total - limit - offset success: type: boolean required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Item not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: chunks x-forge-params: id: description: AI Search instance ID. flagName: instance-id item_id: description: Indexed item ID. flagName: item-id name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/download: get: operationId: ai-search-namespace-instance-get-item-content summary: Download Item Content. description: Downloads the raw file content for a specific item from the managed AI Search instance storage. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: item_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Raw file content. content: application/octet-stream: schema: type: string format: binary '400': description: Content download not available for external source items. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '403': description: Items in this instance were crawled from a public site for search and AI input only. Full page content isn't available for download; use the search endpoint to retrieve cited excerpts. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Item not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: download x-forge-params: id: description: AI Search instance ID. flagName: instance-id item_id: description: Indexed item ID. flagName: item-id name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/logs: get: operationId: ai-search-namespace-instance-logs-item summary: Item Logs. description: Lists processing logs for a specific item in an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: item_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: limit in: query schema: type: integer default: 50 maximum: 100 minimum: 1 - name: cursor in: query schema: type: string maxLength: 512 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns the AI Search item logs. content: application/json: schema: type: object properties: result: type: array items: properties: action: type: string chunkCount: type: integer nullable: true errorType: type: string nullable: true fileKey: type: string message: type: string nullable: true processingTimeMs: type: integer nullable: true timestamp: type: string format: date-time required: - timestamp - action - message - fileKey - chunkCount - processingTimeMs - errorType type: object result_info: type: object properties: count: type: integer cursor: type: string nullable: true per_page: type: integer truncated: type: boolean required: - count - per_page - cursor - truncated success: type: boolean required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Item not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Items x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.items x-fern-sdk-method-name: logs x-forge-params: id: description: AI Search instance ID. flagName: instance-id item_id: description: Indexed item ID. flagName: item-id name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs: get: operationId: ai-search-namespace-instance-list-jobs summary: List Jobs description: Lists indexing jobs for an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 50 minimum: 0 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns a list of AI Search Jobs. content: application/json: schema: type: object properties: result: type: array items: properties: description: type: string end_reason: type: string ended_at: type: string id: type: string x-auditable: true last_seen_at: type: string source: type: string enum: - user - schedule x-auditable: true started_at: type: string required: - id - source type: object result_info: type: object properties: count: type: integer page: type: integer per_page: type: integer total_count: type: integer required: - count - page - per_page - total_count success: type: boolean required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: list x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace post: operationId: ai-search-namespace-instance-create-job summary: Create new job description: Creates a new indexing job for an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: description: type: string maxLength: 255 responses: '200': description: Returns the AI Search job id. content: application/json: schema: type: object properties: result: type: object properties: description: type: string end_reason: type: string ended_at: type: string id: type: string x-auditable: true last_seen_at: type: string source: type: string enum: - user - schedule x-auditable: true started_at: type: string required: - id - source success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '429': description: Sync in cooldown. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: create x-forge-params: description: description: Optional description for the indexing job. id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs/{job_id}: get: operationId: ai-search-namespace-instance-get-job summary: Get a Job Details description: Retrieves details for a specific AI Search indexing job. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: job_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns a AI Search Job Details. content: application/json: schema: type: object properties: result: type: object properties: description: type: string end_reason: type: string ended_at: type: string id: type: string x-auditable: true last_seen_at: type: string source: type: string enum: - user - schedule x-auditable: true started_at: type: string required: - id - source success: type: boolean required: - success - result '404': description: Job not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: get x-forge-params: id: description: AI Search instance ID. flagName: instance-id job_id: description: Indexing job ID. flagName: job-id name: default: default description: Namespace to use for this operation. flagName: namespace patch: operationId: ai-search-namespace-instance-change-job-status summary: Cancel an indexing job. description: Cancel an in-progress indexing job for an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: job_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: action: type: string enum: - cancel required: - action responses: '200': description: Returns the updated AI Search Job. content: application/json: schema: type: object properties: result: type: object properties: description: type: string end_reason: type: string ended_at: type: string id: type: string x-auditable: true last_seen_at: type: string source: type: string enum: - user - schedule x-auditable: true started_at: type: string required: - id - source success: type: boolean required: - success - result '400': description: Job cannot be cancelled. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Job not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: cancel x-forge-params: action: default: cancel hidden: true id: description: AI Search instance ID. flagName: instance-id job_id: description: Indexing job ID. flagName: job-id name: default: default description: Namespace to use for this operation. flagName: namespace x-forge-require-confirmation: This operation cancels the running indexing job. /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs/{job_id}/logs: get: operationId: ai-search-namespace-instance-list-job-logs summary: List Job Logs description: Lists log entries for an AI Search indexing job. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: job_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 500 minimum: 0 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns a list of AI Search Job Logs. content: application/json: schema: type: object properties: result: type: array items: properties: created_at: type: number id: type: integer message: type: string message_type: type: integer required: - id - message - message_type - created_at type: object result_info: type: object properties: count: type: integer page: type: integer per_page: type: integer total_count: type: integer required: - count - page - per_page - total_count success: type: boolean required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: Unable to connect to ai search. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances Jobs x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.jobs x-fern-sdk-method-name: logs x-forge-params: id: description: AI Search instance ID. flagName: instance-id job_id: description: Indexing job ID. flagName: job-id name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/purge_cache: post: operationId: ai-search-namespace-purge-instance-cache summary: Purge search cache. description: Purges all cached search results for an AI Search instance. A new internal cache key is generated, immediately orphaning all prior cached entries. parameters: - name: account_id in: path required: true schema: type: string - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Cache purged successfully. content: application/json: schema: type: object properties: success: type: boolean required: - success '404': description: Ai search not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: purge-cache x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/search: post: operationId: ai-search-namespace-instance-search summary: Search description: Executes a semantic search query against an AI Search instance to find relevant indexed content. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: ai_search_options: type: object properties: cache: type: object properties: cache_threshold: type: string enum: - super_strict_match - close_enough - flexible_friend - anything_goes enabled: type: boolean query_rewrite: type: object properties: enabled: type: boolean model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string rewrite_prompt: type: string reranking: type: object properties: enabled: type: boolean match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 model: type: string retrieval: type: object properties: boost_by: description: Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 context_expansion: type: integer default: 0 maximum: 3 minimum: 0 filters: type: object additionalProperties: true fusion_method: type: string enum: - max - rrf keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'. type: string enum: - and - or match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 max_num_results: type: integer default: 10 maximum: 50 minimum: 1 retrieval_type: type: string enum: - vector - keyword - hybrid return_on_failure: type: boolean default: true messages: description: "OpenAI-compatible message array. For multimodal queries, set the last user message's `content` to an array of typed parts: `[{type:'text', text:'…'}, {type:'image_url', image_url:{url:'…'}}]`. Image inputs require the RAG's embedding_model to declare 'image' in supported_modalities." type: array items: additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content type: object minItems: 1 query: description: A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both. minLength: 1 type: string responses: '200': description: Returns the search results. content: application/json: schema: type: object properties: result: type: object properties: chunks: type: array items: properties: id: type: string item: type: object properties: key: type: string metadata: type: object additionalProperties: true timestamp: type: number required: - key score: type: number maximum: 1 minimum: 0 scoring_details: type: object properties: fusion_method: type: string enum: - rrf - max keyword_rank: type: number keyword_score: type: number minimum: 0 reranking_score: type: number maximum: 1 minimum: 0 vector_rank: type: number vector_score: type: number maximum: 1 minimum: 0 text: type: string type: type: string required: - id - type - score - text type: object query_kind: type: string enum: - text - image - multimodal search_query: type: string required: - query_kind - chunks success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: search x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace query: description: Text to search for. positional: true /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/stats: get: operationId: ai-search-namespace-stats summary: Get instance statistics. description: Retrieve usage and indexing statistics for an AI Search instance. parameters: - name: id in: path description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. required: true schema: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. type: string example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ x-auditable: true - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace responses: '200': description: Returns the AI Search stats. content: application/json: schema: type: object properties: result: type: object properties: completed: type: integer degraded: description: True when status counts are unavailable (e.g. legacy stats query exceeded D1 statement-size limit). Counts are omitted in this case. type: boolean engine: description: Engine-specific metadata. Present only for managed (v3) instances. type: object properties: r2: description: R2 bucket storage usage in bytes. type: object properties: metadataSizeBytes: type: integer objectCount: type: integer payloadSizeBytes: type: integer required: - payloadSizeBytes - metadataSizeBytes - objectCount vectorize: description: Vectorize index metadata (dimensions, vector count). type: object properties: dimensions: type: integer vectorsCount: type: integer required: - vectorsCount - dimensions error: type: integer file_embed_errors: type: object additionalProperties: true index_source_errors: type: object additionalProperties: true last_activity: type: string format: date-time outdated: type: integer queued: type: integer running: type: integer skipped: type: integer success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Instances x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: stats x-forge-params: id: description: AI Search instance ID. flagName: instance-id name: default: default description: Namespace to use for this operation. flagName: namespace /accounts/{account_id}/ai-search/namespaces/{name}/search: post: operationId: ai-search-namespace-multi-instance-search summary: Multi-Instance Search description: Performs a semantic search query against multiple AI Search instances in parallel, merging the retrieved results into a single ranked response. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: name in: path description: Namespace name required: true schema: type: string example: my-namespace requestBody: content: application/json: schema: type: object properties: ai_search_options: type: object properties: cache: type: object properties: cache_threshold: type: string enum: - super_strict_match - close_enough - flexible_friend - anything_goes enabled: type: boolean instance_ids: type: array items: description: AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores. example: my-ai-search maxLength: 64 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ type: string x-auditable: true minItems: 1 query_rewrite: type: object properties: enabled: type: boolean model: description: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model. type: string rewrite_prompt: type: string reranking: type: object properties: enabled: type: boolean match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 model: type: string retrieval: type: object properties: boost_by: description: Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field. type: array items: properties: direction: description: Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. type: string enum: - asc - desc - exists - not_exists field: description: Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists. type: string example: timestamp maxLength: 64 minLength: 1 required: - field type: object example: - direction: desc field: timestamp maxItems: 3 context_expansion: type: integer default: 0 maximum: 3 minimum: 0 filters: type: object additionalProperties: true fusion_method: type: string enum: - max - rrf keyword_match_mode: description: Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'. type: string enum: - and - or match_threshold: type: number default: 0.4 maximum: 1 minimum: 0 max_num_results: type: integer default: 10 maximum: 50 minimum: 1 retrieval_type: type: string enum: - vector - keyword - hybrid return_on_failure: type: boolean default: true required: - instance_ids messages: description: "OpenAI-compatible message array. For multimodal queries, set the last user message's `content` to an array of typed parts: `[{type:'text', text:'…'}, {type:'image_url', image_url:{url:'…'}}]`. Image inputs require the RAG's embedding_model to declare 'image' in supported_modalities." type: array items: additionalProperties: true properties: content: anyOf: - type: string - items: oneOf: - properties: text: type: string minLength: 1 type: type: string enum: - text required: - type - text type: object - properties: image_url: type: object properties: url: type: string maxLength: 20971520 minLength: 1 required: - url type: type: string enum: - image_url required: - type - image_url type: object - properties: file: type: object properties: file_data: type: string maxLength: 13981144 minLength: 1 file_id: type: string filename: type: string maxLength: 255 minLength: 1 required: - filename type: type: string enum: - file required: - type - file type: object minItems: 1 type: array - enum: - null nullable: true type: string role: type: string enum: - system - developer - user - assistant - tool required: - role - content type: object minItems: 1 query: description: A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both. minLength: 1 type: string required: - ai_search_options responses: '200': description: Returns the merged search results from all instances. content: application/json: schema: type: object properties: result: type: object properties: chunks: type: array items: properties: id: type: string instance_id: type: string item: type: object properties: key: type: string metadata: type: object additionalProperties: true timestamp: type: number required: - key score: type: number maximum: 1 minimum: 0 scoring_details: type: object properties: fusion_method: type: string enum: - rrf - max keyword_rank: type: number keyword_score: type: number minimum: 0 reranking_score: type: number maximum: 1 minimum: 0 vector_rank: type: number vector_score: type: number maximum: 1 minimum: 0 text: type: string type: type: string required: - id - type - score - text - instance_id type: object errors: type: array items: properties: instance_id: type: string message: type: string required: - instance_id - message type: object query_kind: type: string enum: - text - image - multimodal search_query: type: string required: - query_kind - chunks success: type: boolean required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Account Search x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search x-fern-sdk-method-name: multi-search x-forge-params: name: default: default description: Namespace to use for this operation. flagName: namespace query: description: Text to search for. positional: true /accounts/{account_id}/ai-search/tokens: get: operationId: ai-search-list-tokens summary: List tokens description: List stored AI Search credentials in the account without exposing their secrets. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query description: Page number (1-indexed). schema: description: Page number (1-indexed). type: integer example: 1 default: 1 maximum: 100 minimum: 1 - name: per_page in: query description: Number of results per page. schema: description: Number of results per page. type: integer example: 20 default: 20 maximum: 100 minimum: 1 - name: search in: query description: Filter tokens whose name contains this string (case-insensitive). schema: description: Filter tokens whose name contains this string (case-insensitive). type: string example: my-token maxLength: 256 responses: '200': description: List of tokens. content: application/json: schema: type: object properties: result: type: array items: properties: cf_api_id: type: string x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true enabled: type: boolean default: true x-auditable: true id: type: string format: uuid x-auditable: true legacy: type: boolean default: true readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true name: type: string x-auditable: true required: - id - name - cf_api_id - created_at - modified_at type: object result_info: type: object properties: count: type: number page: type: number per_page: type: number total_count: type: number required: - page - per_page - count - total_count success: type: boolean enum: - true required: - success - result - result_info '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Tokens x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.tokens x-fern-sdk-method-name: list post: operationId: ai-search-create-tokens summary: Create a token description: Create a stored Cloudflare credential for an AI Search instance to access its data source. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: cf_api_id: type: string example: a1b2c3d4e5f6 cf_api_key: type: string example: abc123 writeOnly: true x-sensitive: true legacy: type: boolean default: true name: type: string example: my-token required: - name - cf_api_id - cf_api_key responses: '201': description: Token created. content: application/json: schema: type: object properties: result: type: object properties: cf_api_id: type: string x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true enabled: type: boolean default: true x-auditable: true id: type: string format: uuid x-auditable: true legacy: type: boolean default: true readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true name: type: string x-auditable: true required: - id - name - cf_api_id - created_at - modified_at success: type: boolean enum: - true required: - success - result '400': description: Ai search instance invalid token. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Tokens x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.tokens x-fern-sdk-method-name: create x-forge-params: cf_api_id: description: Cloudflare API token ID. flagName: api-token-id cf_api_key: description: Cloudflare API token value. flagName: api-token legacy: description: Whether the credential uses the legacy API key format. name: description: Human-readable name for the credential. positional: true /accounts/{account_id}/ai-search/tokens/{id}: delete: operationId: ai-search-delete-tokens summary: Delete a token description: Permanently delete a stored AI Search credential. Credentials in use by an instance cannot be deleted. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string format: uuid example: 62af0db3-c410-40b2-9ee3-0e93f6dd1de0 responses: '200': description: Token deleted. content: application/json: schema: type: object properties: result: type: object additionalProperties: false success: type: boolean enum: - true required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Token not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '409': description: Token in use by instances. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Tokens x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.tokens x-fern-sdk-method-name: delete x-forge-params: id: description: Stored credential record ID. flagName: token-id x-forge-require-confirmation: This operation permanently deletes the stored credential. get: operationId: ai-search-fetch-tokens summary: Get a token description: Retrieve a stored AI Search credential without exposing its secret. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string format: uuid example: 62af0db3-c410-40b2-9ee3-0e93f6dd1de0 responses: '200': description: Token details. content: application/json: schema: type: object properties: result: type: object properties: cf_api_id: type: string x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true enabled: type: boolean default: true x-auditable: true id: type: string format: uuid x-auditable: true legacy: type: boolean default: true readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true name: type: string x-auditable: true required: - id - name - cf_api_id - created_at - modified_at success: type: boolean enum: - true required: - success - result '400': description: Input Validation Error content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string path: type: array items: type: string required: - code - message - path type: object success: type: boolean enum: - false required: - success - errors '404': description: Token not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Tokens x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.tokens x-fern-sdk-method-name: get x-forge-params: id: description: Stored credential record ID. flagName: token-id put: operationId: ai-search-update-tokens summary: Update a token description: Replace a stored AI Search credential and invalidate cached credentials for instances that use it. parameters: - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: id in: path required: true schema: type: string format: uuid example: 62af0db3-c410-40b2-9ee3-0e93f6dd1de0 requestBody: content: application/json: schema: type: object properties: cf_api_id: type: string example: a1b2c3d4e5f6 cf_api_key: type: string example: abc123 writeOnly: true x-sensitive: true legacy: type: boolean default: true name: type: string example: my-token required: - name - cf_api_id - cf_api_key responses: '200': description: Returns the updated token. content: application/json: schema: type: object properties: result: type: object properties: cf_api_id: type: string x-auditable: true created_at: type: string format: date-time readOnly: true created_by: type: string nullable: true readOnly: true enabled: type: boolean default: true x-auditable: true id: type: string format: uuid x-auditable: true legacy: type: boolean default: true readOnly: true modified_at: type: string format: date-time readOnly: true modified_by: type: string nullable: true readOnly: true name: type: string x-auditable: true required: - id - name - cf_api_id - created_at - modified_at success: type: boolean enum: - true required: - success - result '400': description: Ai search instance invalid token. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: Token not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AI Search Tokens x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai-search x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: beta x-fern-sdk-group-name: ai-search.tokens x-fern-sdk-method-name: update x-forge-params: cf_api_id: description: Cloudflare API token ID. flagName: api-token-id cf_api_key: description: Cloudflare API token value. flagName: api-token id: description: Stored credential record ID. flagName: token-id legacy: description: Whether the credential uses the legacy API key format. name: description: Human-readable name for the credential. /accounts/{account_id}/ai/authors/search: get: operationId: workers-ai-search-author summary: Author Search description: Searches Workers AI models by author or organization name. parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 responses: '200': description: Returns a list of authors. content: application/json: schema: type: object properties: errors: type: array items: type: object messages: type: array items: type: string result: type: array items: type: object success: type: boolean required: - success - result - errors - messages '400': description: Bad Request. content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai.authors x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/ai/finetunes: get: operationId: workers-ai-list-finetunes summary: List Finetunes description: Lists all fine-tuning jobs created by the account, including status and metrics. parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 responses: '200': description: Returns all finetunes. content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time description: type: string id: type: string format: uuid x-auditable: true model: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true required: - id - model - name - created_at - modified_at success: type: boolean required: - success - result '400': description: Bad Request. content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI Finetune x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai.finetunes x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: workers-ai-create-finetune summary: Create a new Finetune description: Creates a new fine-tuning job for a Workers AI model using custom training data. parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 requestBody: content: application/json: schema: type: object properties: description: type: string model: type: string x-auditable: true name: type: string x-auditable: true public: type: boolean default: false x-auditable: true required: - model - name responses: '200': description: Returns the created finetune. content: application/json: schema: type: object properties: result: type: object properties: created_at: type: string format: date-time description: type: string id: type: string format: uuid x-auditable: true model: type: string x-auditable: true modified_at: type: string format: date-time name: type: string x-auditable: true public: type: boolean x-auditable: true required: - id - created_at - modified_at - public - name - model success: type: boolean required: - success - result '400': description: Finetune creation failed. content: application/json: schema: type: object properties: errors: type: array items: type: object success: type: boolean required: - errors - success security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI Finetune x-api-token-group: - Workers AI Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai.finetunes x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/ai/finetunes/{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/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/models/schema: get: operationId: workers-ai-get-model-schema summary: Get Model Schema description: Retrieves the input and output JSON schema definition for a Workers AI model. parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 - name: model in: query description: Model Name required: true schema: description: Model Name type: string responses: '200': description: Model Schema content: application/json: schema: type: object properties: result: type: object properties: input: type: object properties: additionalProperties: type: boolean example: true description: type: string example: JSON Schema definition for the model's input parameters type: type: string example: object required: - type - description - additionalProperties output: type: object properties: additionalProperties: type: boolean example: true description: type: string example: JSON Schema definition for the model's output format type: type: string example: object required: - type - description - additionalProperties required: - input - output success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: ai x-fern-sdk-method-name: getModelSchema /accounts/{account_id}/ai/models/search: get: operationId: workers-ai-search-model summary: Model Search description: Searches Workers AI models by name or description. parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 - name: per_page in: query schema: type: integer default: 100 - name: page in: query schema: type: integer default: 1 - name: task in: query description: Filter by Task Name. schema: description: Filter by Task Name. type: string example: Text Generation default: '' - name: author in: query description: Filter by Author. schema: description: Filter by Author. type: string default: '' - name: source in: query description: Filter by Source Id. schema: description: Filter by Source Id. type: number - name: hide_experimental in: query description: Filter to hide experimental models. schema: description: Filter to hide experimental models. type: boolean default: false - name: search in: query description: Search. schema: description: Search. type: string default: '' - name: include_deprecated in: query description: If true, include models for up to three months after their deprecation date. Defaults to false. schema: description: If true, include models for up to three months after their deprecation date. Defaults to false. type: boolean default: false - name: format in: query description: If set, return models in the requested marketplace format instead of the default response. schema: description: If set, return models in the requested marketplace format instead of the default response. type: string enum: - openrouter responses: '200': description: Returns a list of models. Default shape is the standard envelope; when `format` is supplied the marketplace-specific shape is returned instead. content: application/json: schema: anyOf: - properties: errors: type: array items: type: object messages: type: array items: type: string result: type: array items: type: object success: type: boolean required: - success - result - errors - messages type: object - description: Marketplace-format response. See https://openrouter.ai/docs/guides/get-started/for-providers. properties: data: type: array items: type: object required: - data type: object '404': description: Object not found. content: application/json: schema: type: object properties: errors: type: array items: type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai.models x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/ai/run: post: operationId: workers-ai-post-run-generic summary: Execute AI Model (Generic) description: |- Execute an AI model by specifying the model name in the request body. This endpoint provides a generic interface for running AI models where the model name is part of the request payload rather than the URL path. It supports all AI Gateway features including caching, custom headers, and request options. Model-specific inputs available in [Cloudflare Docs](https://developers.cloudflare.com/workers-ai/models/). parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 requestBody: content: application/json: schema: type: object properties: input: description: Model-specific input data. Format varies by model type. type: object example: prompt: Tell me a joke model: description: The AI model to execute (e.g., openai/gpt-5.5, anthropic/claude-opus-4.7) type: string example: openai/gpt-5.5 options: type: object properties: extraHeaders: description: Additional headers to pass to the AI provider type: object additionalProperties: type: string gateway: type: object properties: cacheTtl: description: Cache TTL in seconds type: number example: 3600 id: description: AI Gateway ID for caching and logging type: string example: my-gateway skipCache: description: Skip cache lookup for this request type: boolean required: - model - input responses: '200': description: Model response content: application/json: schema: type: object properties: errors: type: array items: type: object messages: type: array items: type: object result: description: Model-specific output. Format varies by model type. type: object success: type: boolean required: - success - result - errors - messages '400': description: Bad request - missing required fields or invalid input content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number message: type: string required: - code - message type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai x-fern-sdk-method-name: run x-forge-hidden: true /accounts/{account_id}/ai/run/{model_name}: post: operationId: workers-ai-post-run-model summary: Execute AI model description: |- This endpoint provides users with the capability to run specific AI models on-demand. By submitting the required input data, users can receive real-time predictions or results generated by the chosen AI model. The endpoint supports various AI model types, ensuring flexibility and adaptability for diverse use cases. Model specific inputs available in [Cloudflare Docs](https://developers.cloudflare.com/workers-ai/models/). parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 - name: model_name in: path required: true schema: type: string requestBody: content: application/json: schema: type: object oneOf: - properties: text: description: The text that you want to classify type: string minLength: 1 required: - text title: Text Classification type: object - properties: guidance: description: Controls how closely the generated image should adhere to the prompt; higher values make the image more aligned with the prompt type: number default: 7.5 height: description: The height of the generated image in pixels type: integer maximum: 2048 minimum: 256 image: description: For use with img2img tasks. An array of integers that represent the image data constrained to 8-bit unsigned integer values type: array items: description: A value between 0 and 255 type: number image_b64: description: For use with img2img tasks. A base64-encoded string of the input image type: string mask: description: An array representing An array of integers that represent mask image data for inpainting constrained to 8-bit unsigned integer values type: array items: description: A value between 0 and 255 type: number negative_prompt: description: Text describing elements to avoid in the generated image type: string num_steps: description: The number of diffusion steps; higher values can improve quality but take longer type: integer default: 20 maximum: 20 prompt: description: A text description of the image you want to generate type: string minLength: 1 seed: description: Random seed for reproducibility of the image generation type: integer strength: description: A value between 0 and 1 indicating how strongly to apply the transformation during img2img tasks; lower values make the output closer to the input image type: number default: 1 width: description: The width of the generated image in pixels type: integer maximum: 2048 minimum: 256 required: - prompt title: Text To Image type: object - properties: lang: description: The speech language (e.g., 'en' for English, 'fr' for French). Defaults to 'en' if not specified type: string default: en prompt: description: A text description of the audio you want to generate type: string minLength: 1 required: - prompt title: Text To Speech type: object - properties: text: oneOf: - description: The text to embed minLength: 1 type: string - description: Batch of text values to embed items: description: The text to embed minLength: 1 type: string maxItems: 100 type: array required: - text title: Text Embeddings type: object - oneOf: - format: binary type: string - properties: audio: description: An array of integers that represent the audio data constrained to 8-bit unsigned integer values type: array items: description: A value between 0 and 255 type: number source_lang: description: The language of the recorded audio type: string target_lang: description: The language to translate the transcription into. Currently only English is supported. type: string required: - audio type: object title: Automatic Speech Recognition type: object - oneOf: - description: The image to classify format: binary type: string - properties: image: description: An array of integers that represent the image data constrained to 8-bit unsigned integer values type: array items: description: A value between 0 and 255 (unsigned 8bit) type: number required: - image type: object title: Image Classification type: object - oneOf: - description: The image to use for detection format: binary type: string - properties: image: description: An array of integers that represent the image data constrained to 8-bit unsigned integer values type: array items: description: A value between 0 and 255 (unsigned 8bit) type: number type: object title: Object Detection type: object - oneOf: - properties: frequency_penalty: description: Decreases the likelihood of the model repeating the same lines verbatim. type: number maximum: 2 minimum: -2 lora: description: Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model. type: string max_tokens: description: The maximum number of tokens to generate in the response. type: integer default: 256 presence_penalty: description: Increases the likelihood of the model introducing new topics. type: number maximum: 2 minimum: -2 prompt: description: The input text prompt for the model to generate a response. type: string minLength: 1 raw: description: If true, a chat template is not applied and you must adhere to the specific model's expected formatting. type: boolean default: false repetition_penalty: description: Penalty for repeated tokens; higher values discourage repetition. type: number maximum: 2 minimum: 0 response_format: type: object properties: json_schema: {} type: type: string enum: - json_object - json_schema title: JSON Mode seed: description: Random seed for reproducibility of the generation. type: integer maximum: 9999999999 minimum: 1 stream: description: If true, the response will be streamed back incrementally using SSE, Server Sent Events. type: boolean default: false temperature: description: Controls the randomness of the output; higher values produce more random results. type: number default: 0.6 maximum: 5 minimum: 0 top_k: description: Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. type: integer maximum: 50 minimum: 1 top_p: description: Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. type: number maximum: 1 minimum: 0.001 required: - prompt title: Prompt - properties: frequency_penalty: description: Decreases the likelihood of the model repeating the same lines verbatim. type: number maximum: 2 minimum: -2 functions: type: array items: properties: code: type: string name: type: string required: - name - code type: object max_tokens: description: The maximum number of tokens to generate in the response. type: integer default: 256 messages: description: An array of message objects representing the conversation history. type: array items: properties: content: oneOf: - description: The content of the message as a string. type: string - description: Array of text content parts. items: properties: text: description: Text content type: string type: description: Type of the content (text) type: string type: object type: array role: description: The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). type: string required: - role - content type: object presence_penalty: description: Increases the likelihood of the model introducing new topics. type: number maximum: 2 minimum: -2 raw: description: If true, a chat template is not applied and you must adhere to the specific model's expected formatting. type: boolean default: false repetition_penalty: description: Penalty for repeated tokens; higher values discourage repetition. type: number maximum: 2 minimum: 0 response_format: type: object properties: json_schema: {} type: type: string enum: - json_object - json_schema title: JSON Mode seed: description: Random seed for reproducibility of the generation. type: integer maximum: 9999999999 minimum: 1 stream: description: If true, the response will be streamed back incrementally using SSE, Server Sent Events. type: boolean default: false temperature: description: Controls the randomness of the output; higher values produce more random results. type: number default: 0.6 maximum: 5 minimum: 0 tools: description: A list of tools available for the assistant to use. type: array items: oneOf: - properties: description: description: A brief description of what the tool does. type: string name: description: The name of the tool. More descriptive the better. type: string parameters: description: Schema defining the parameters accepted by the tool. required: - type - properties properties: properties: description: Definitions of each parameter. type: object additionalProperties: properties: description: description: A description of the expected parameter. type: string type: description: The data type of the parameter. type: string required: - type - description type: object required: description: List of required parameter names. type: array items: type: string type: description: The type of the parameters object (usually 'object'). type: string type: object required: - name - description - parameters - properties: function: description: Details of the function tool. type: object properties: description: description: A brief description of what the function does. type: string name: description: The name of the function. type: string parameters: description: Schema defining the parameters accepted by the function. required: - type - properties properties: properties: description: Definitions of each parameter. type: object additionalProperties: properties: description: description: A description of the expected parameter. type: string type: description: The data type of the parameter. type: string required: - type - description type: object required: description: List of required parameter names. type: array items: type: string type: description: The type of the parameters object (usually 'object'). type: string type: object required: - name - description - parameters type: description: Specifies the type of tool (e.g., 'function'). type: string required: - type - function type: object top_k: description: Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. type: integer maximum: 50 minimum: 1 top_p: description: Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. type: number maximum: 1 minimum: 0.001 required: - messages title: Messages title: Text Generation type: object - properties: source_lang: description: The language code of the source text (e.g., 'en' for English). Defaults to 'en' if not specified type: string default: en target_lang: description: The language code to translate the text into (e.g., 'es' for Spanish) type: string text: description: The text to be translated type: string minLength: 1 required: - text - target_lang title: Translation type: object - properties: input_text: description: The text that you want the model to summarize type: string minLength: 1 max_length: description: The maximum length of the generated summary in tokens type: integer default: 1024 required: - input_text title: Summarization type: object - oneOf: - description: Binary string representing the image contents. format: binary type: string - properties: frequency_penalty: description: Decreases the likelihood of the model repeating the same lines verbatim. type: number image: oneOf: - description: An array of integers that represent the image data constrained to 8-bit unsigned integer values items: description: A value between 0 and 255 type: number type: array - description: Binary string representing the image contents. format: binary type: string max_tokens: description: The maximum number of tokens to generate in the response. type: integer default: 512 presence_penalty: description: Increases the likelihood of the model introducing new topics. type: number prompt: description: The input text prompt for the model to generate a response. type: string raw: description: If true, a chat template is not applied and you must adhere to the specific model's expected formatting. type: boolean default: false repetition_penalty: description: Penalty for repeated tokens; higher values discourage repetition. type: number seed: description: Random seed for reproducibility of the generation. type: number temperature: description: Controls the randomness of the output; higher values produce more random results. type: number top_k: description: Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. type: number top_p: description: Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. type: number required: - image type: object title: Image To Text type: object - oneOf: - properties: frequency_penalty: description: Decreases the likelihood of the model repeating the same lines verbatim. type: number ignore_eos: description: Whether to ignore the EOS token and continue generating tokens after the EOS token is generated. type: boolean image: description: Image in base64 encoded format. type: string max_tokens: description: The maximum number of tokens to generate in the response. type: integer default: 512 presence_penalty: description: Increases the likelihood of the model introducing new topics. type: number prompt: description: The input text prompt for the model to generate a response. type: string minLength: 1 repetition_penalty: description: Penalty for repeated tokens; higher values discourage repetition. type: number seed: description: Random seed for reproducibility of the generation. type: number temperature: description: Controls the randomness of the output; higher values produce more random results. type: number top_k: description: Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. type: number top_p: description: Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. type: number required: - prompt - image type: object - properties: frequency_penalty: description: Decreases the likelihood of the model repeating the same lines verbatim. type: number ignore_eos: description: Whether to ignore the EOS token and continue generating tokens after the EOS token is generated. type: boolean image: description: Image in base64 encoded format. type: string max_tokens: description: The maximum number of tokens to generate in the response. type: integer default: 512 messages: description: An array of message objects representing the conversation history. type: array items: properties: content: anyOf: - description: The content of the message as a string. type: string - description: Array of content parts (text, image_url, etc.). items: properties: image_url: description: Image URL object (when type is 'image_url'). type: object properties: url: description: Image URI with data (e.g. data:image/jpeg;base64,/9j/...). type: string required: - url text: description: Text content (when type is 'text'). type: string type: description: Type of the content part (e.g. 'text', 'image_url'). type: string required: - type type: object type: array role: description: The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). type: string required: - role - content type: object presence_penalty: description: Increases the likelihood of the model introducing new topics. type: number repetition_penalty: description: Penalty for repeated tokens; higher values discourage repetition. type: number seed: description: Random seed for reproducibility of the generation. type: number temperature: description: Controls the randomness of the output; higher values produce more random results. type: number top_k: description: Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises. type: number top_p: description: Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses. type: number required: - messages - image type: object title: Image Text To Text type: object - properties: image: description: Image in base64 encoded format. type: string minLength: 1 text: type: array items: minLength: 1 type: string title: Multimodal Embeddings type: object responses: '200': description: Model response content: application/json: schema: type: object properties: result: type: object oneOf: - description: An array of classification results for the input text items: properties: label: description: The classification label assigned to the text (e.g., 'POSITIVE' or 'NEGATIVE') type: string score: description: Confidence score indicating the likelihood that the text belongs to the specified label type: number type: object title: Text Classification type: array - description: The generated image in PNG format format: binary title: Text To Image type: string - oneOf: - properties: audio: description: The generated audio in MP3 format, base64-encoded type: string type: object - description: The generated audio in MP3 format format: binary type: string title: Text To Speech type: object - properties: data: description: Embeddings of the requested text values type: array items: description: Floating point embedding representation shaped by the embedding model items: type: number type: array shape: type: array items: type: number title: Text Embeddings type: object - properties: text: description: The transcription type: string vtt: type: string word_count: type: number words: type: array items: properties: end: description: The ending second when the word completes type: number start: description: The second this word begins in the recording type: number word: type: string type: object required: - text title: Automatic Speech Recognition type: object - items: properties: label: description: The predicted category or class for the input image based on analysis type: string score: description: A confidence value, between 0 and 1, indicating how certain the model is about the predicted label type: number type: object title: Image Classification type: array - description: An array of detected objects within the input image items: properties: box: description: Coordinates defining the bounding box around the detected object type: object properties: xmax: description: The x-coordinate of the bottom-right corner of the bounding box type: number xmin: description: The x-coordinate of the top-left corner of the bounding box type: number ymax: description: The y-coordinate of the bottom-right corner of the bounding box type: number ymin: description: The y-coordinate of the top-left corner of the bounding box type: number label: description: The class label or name of the detected object type: string score: description: Confidence score indicating the likelihood that the detection is correct type: number type: object title: Object Detection type: array - oneOf: - properties: response: description: The generated text response from the model type: string tool_calls: description: An array of tool calls requests made during the response generation type: array items: properties: arguments: description: The arguments passed to be passed to the tool call request type: object name: description: The name of the tool to be called type: string type: object usage: description: Usage statistics for the inference request type: object properties: completion_tokens: description: Total number of tokens in output type: number default: 0 prompt_tokens: description: Total number of tokens in input type: number default: 0 total_tokens: description: Total number of input and output tokens type: number default: 0 required: - response type: object - format: binary type: string title: Text Generation type: object - properties: translated_text: description: The translated text in the target language type: string title: Translation type: object - properties: summary: description: The summarized version of the input text type: string title: Summarization type: object - properties: description: type: string title: Image To Text type: object - properties: description: type: string title: Image Text To Text type: object - properties: data: type: array items: items: type: number type: array shape: type: array items: type: number title: Multimodal Embeddings type: object '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: ai x-fern-sdk-method-name: runModel /accounts/{account_id}/ai/tasks/search: get: operationId: workers-ai-search-task summary: Task Search description: Searches Workers AI models by task type (e.g., text-generation, embeddings). parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 responses: '200': description: Returns a list of tasks content: application/json: schema: type: object properties: errors: type: array items: type: object messages: type: array items: type: string result: type: array items: type: object success: type: boolean x-auditable: true required: - success - result - errors - messages '404': description: Object not found. content: application/json: schema: type: object properties: errors: type: array items: type: object success: type: boolean required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: ai.tasks x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/ai/tomarkdown: post: operationId: workers-ai-post-to-markdown summary: Convert Files into Markdown description: Converts uploaded files into Markdown format using Workers AI. parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 requestBody: content: multipart/form-data: schema: type: object properties: files: type: array items: format: binary type: string required: - files responses: '200': description: Model Schema content: application/json: schema: type: object properties: result: type: array items: properties: data: type: string x-auditable: true format: type: string x-auditable: true mimeType: type: string x-auditable: true name: type: string x-auditable: true tokens: type: string x-auditable: true required: - name - mimeType - format - tokens - data type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: ai x-fern-sdk-method-name: toMarkdown /accounts/{account_id}/ai/tomarkdown/supported: get: operationId: workers-ai-get-to-markdown-supported summary: Get all converted formats supported description: Lists all file formats supported for conversion to Markdown. parameters: - name: account_id in: path required: true schema: type: string example: 023e105f4ecef8ad9ca31a8372d0c353 responses: '200': description: Successful response content: application/json: schema: type: object properties: result: type: array items: properties: extension: type: string x-auditable: true mimeType: type: string x-auditable: true required: - extension - mimeType type: object success: type: boolean required: - success - result '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: properties: message: type: string required: - message type: object result: type: object success: type: boolean example: false required: - result - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - Workers AI x-api-token-group: - Workers AI Write - Workers AI Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.ai x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: ai x-fern-sdk-method-name: listMarkdownSupportedFormats /accounts/{account_id}/alerting/v3/available_alerts: get: operationId: notification-alert-types-get-alert-types summary: Get Alert Types description: Gets a list of all alert types for which an account is eligible. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '200': description: Get Alert Types response content: application/json: schema: $ref: '#/components/schemas/aaa_alerts-response_collection' 4XX: description: Get Alert Types response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification Alert Types x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-fern-availability: generally-available x-fern-sdk-group-name: alerting.available-alerts x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/alerting/v3/destinations/eligible: get: operationId: notification-mechanism-eligibility-get-delivery-mechanism-eligibility summary: Get delivery mechanism eligibility description: Get a list of all delivery mechanism types for which an account is eligible. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '200': description: Get delivery mechanism eligibility response content: application/json: schema: $ref: '#/components/schemas/aaa_schemas-response_collection' 4XX: description: Get delivery mechanism eligibility response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification Mechanism Eligibility x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.eligible x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/alerting/v3/destinations/pagerduty: delete: operationId: notification-destinations-with-pager-duty-delete-pager-duty-services summary: Delete PagerDuty Services description: Deletes all the PagerDuty Services connected to the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '200': description: Delete PagerDuty Services response content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-common-2' 4XX: description: Delete PagerDuty Services response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification destinations with PagerDuty x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.pagerduty x-fern-sdk-method-name: delete x-forge-hidden: true x-forge-require-confirmation: This operation deletes all PagerDuty services connected to the account. get: operationId: notification-destinations-with-pager-duty-list-pager-duty-services summary: List PagerDuty services description: Get a list of all configured PagerDuty services. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '200': description: List PagerDuty services response content: application/json: schema: $ref: '#/components/schemas/aaa_components-schemas-response_collection' 4XX: description: List PagerDuty services response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification destinations with PagerDuty x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-cfPlanAvailability: business: true enterprise: true free: false pro: false x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.pagerduty x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/alerting/v3/destinations/pagerduty/connect: post: operationId: notification-destinations-with-pager-duty-connect-pager-duty summary: Create PagerDuty integration token description: Creates a new token for integrating with PagerDuty. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '201': description: Token for PagerDuty integration content: application/json: schema: $ref: '#/components/schemas/aaa_sensitive_id_response' 4XX: description: Create a token for PagerDuty integration failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_id_response' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification destinations with PagerDuty x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.pagerduty x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/alerting/v3/destinations/pagerduty/connect/{token_id}: get: operationId: notification-destinations-with-pager-duty-connect-pager-duty-token summary: Connect PagerDuty description: Links PagerDuty with the account using the integration token. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: token_id in: path required: true schema: $ref: '#/components/schemas/aaa_integration-token' responses: '200': description: Create a Notification policy response content: application/json: schema: $ref: '#/components/schemas/aaa_id_response' 4XX: description: Create a Notification policy response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_id_response' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification destinations with PagerDuty x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.pagerduty x-fern-sdk-method-name: link x-forge-hidden: true /accounts/{account_id}/alerting/v3/destinations/webhooks: get: operationId: notification-webhooks-list-webhooks summary: List webhooks description: Gets a list of all configured webhook destinations. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '200': description: List webhooks response content: application/json: schema: $ref: '#/components/schemas/aaa_webhooks_components-schemas-response_collection' 4XX: description: List webhooks response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_webhooks_components-schemas-response_collection' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification webhooks x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-cfPlanAvailability: business: true enterprise: true free: false pro: true x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.webhooks x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: notification-webhooks-create-a-webhook summary: Create a webhook description: Creates a new webhook destination. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' requestBody: required: true content: application/json: schema: properties: name: $ref: '#/components/schemas/aaa_components-schemas-name' secret: $ref: '#/components/schemas/aaa_secret' url: $ref: '#/components/schemas/aaa_url' required: - name - url responses: '201': description: Create a webhook response content: application/json: schema: $ref: '#/components/schemas/aaa_id_response' 4XX: description: Create a webhook response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_id_response' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification webhooks x-api-token-group: - Notifications Write - Account Settings Write x-cfPlanAvailability: business: true enterprise: true free: false pro: true x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.webhooks x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/alerting/v3/destinations/webhooks/{webhook_id}: delete: operationId: notification-webhooks-delete-a-webhook summary: Delete a webhook description: Delete a configured webhook destination. parameters: - name: webhook_id in: path required: true schema: $ref: '#/components/schemas/aaa_webhook-id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '200': description: Delete a webhook response content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-common-2' 4XX: description: Delete a webhook response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification webhooks x-api-token-group: - Notifications Write - Account Settings Write x-cfPlanAvailability: business: true enterprise: true free: false pro: true x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.webhooks x-fern-sdk-method-name: delete x-forge-hidden: true x-forge-require-confirmation: This operation deletes the webhook destination. get: operationId: notification-webhooks-get-a-webhook summary: Get a webhook description: Get details for a single webhooks destination. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: webhook_id in: path required: true schema: $ref: '#/components/schemas/aaa_webhook-id' responses: '200': description: Get a webhook response content: application/json: schema: $ref: '#/components/schemas/aaa_schemas-single_response' 4XX: description: Get a webhook response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_schemas-single_response' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification webhooks x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-cfPlanAvailability: business: true enterprise: true free: false pro: true x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.webhooks x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: notification-webhooks-update-a-webhook summary: Update a webhook description: Update a webhook destination. parameters: - name: webhook_id in: path required: true schema: $ref: '#/components/schemas/aaa_webhook-id' - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' requestBody: required: true content: application/json: schema: properties: name: $ref: '#/components/schemas/aaa_components-schemas-name' secret: $ref: '#/components/schemas/aaa_secret' url: $ref: '#/components/schemas/aaa_url' required: - name - url responses: '200': description: Update a webhook response content: application/json: schema: $ref: '#/components/schemas/aaa_id_response' 4XX: description: Update a webhook response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_id_response' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification webhooks x-api-token-group: - Notifications Write - Account Settings Write x-cfPlanAvailability: business: true enterprise: true free: false pro: true x-fern-availability: generally-available x-fern-sdk-group-name: alerting.destinations.webhooks x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/alerting/v3/history: get: operationId: notification-history-list-history summary: List History description: Gets a list of history records for notifications sent to an account. The records are displayed for last `x` number of days based on the zone plan (free = 30, pro = 30, biz = 30, ent = 90). parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: per_page in: query schema: $ref: '#/components/schemas/aaa_per_page' - name: before in: query schema: $ref: '#/components/schemas/aaa_before' - name: page in: query schema: description: Page number of paginated results. type: number default: 1 minimum: 1 - name: since in: query schema: description: Limit the returned results to history records newer than the specified date. This must be a timestamp that conforms to RFC3339. type: string format: date-time example: 2022-05-19T20:29:58.679897Z responses: '200': description: List History response content: application/json: schema: $ref: '#/components/schemas/aaa_history_components-schemas-response_collection' 4XX: description: List History response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_history_components-schemas-response_collection' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification History x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-fern-availability: generally-available x-fern-sdk-group-name: alerting.history x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/alerting/v3/policies: get: operationId: notification-policies-list-notification-policies summary: List Notification policies description: Get a list of all Notification policies. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '200': description: List Notification policies response content: application/json: schema: $ref: '#/components/schemas/aaa_policies_components-schemas-response_collection' 4XX: description: List Notification policies response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification policies x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-fern-availability: generally-available x-fern-sdk-group-name: alerting.policies x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: notification-policies-create-a-notification-policy summary: Create a Notification policy description: Creates a new Notification policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' requestBody: required: true content: application/json: schema: properties: alert_interval: $ref: '#/components/schemas/aaa_alert_interval' alert_type: $ref: '#/components/schemas/aaa_alert_type' description: $ref: '#/components/schemas/aaa_schemas-description' enabled: $ref: '#/components/schemas/aaa_enabled' filters: $ref: '#/components/schemas/aaa_filters' mechanisms: $ref: '#/components/schemas/aaa_mechanisms' name: $ref: '#/components/schemas/aaa_schemas-name' required: - name - alert_type - enabled - mechanisms responses: '200': description: Create a Notification policy response content: application/json: schema: $ref: '#/components/schemas/aaa_id_response' 4XX: description: Create a Notification policy response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_id_response' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification policies x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.policies x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/alerting/v3/policies/{policy_id}: delete: operationId: notification-policies-delete-a-notification-policy summary: Delete a Notification policy description: Delete a Notification policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/aaa_policy-id' responses: '200': description: Delete a Notification policy response content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-collection' 4XX: description: Delete a Notification policy response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_api-response-collection' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification policies x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.policies x-fern-sdk-method-name: delete x-forge-hidden: true x-forge-require-confirmation: This operation deletes the notification policy. get: operationId: notification-policies-get-a-notification-policy summary: Get a Notification policy description: Get details for a single policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/aaa_policy-id' responses: '200': description: Get a Notification policy response content: application/json: schema: $ref: '#/components/schemas/aaa_single_response' 4XX: description: Get a Notification policy response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_single_response' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification policies x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-fern-availability: generally-available x-fern-sdk-group-name: alerting.policies x-fern-sdk-method-name: get x-forge-hidden: true put: operationId: notification-policies-update-a-notification-policy summary: Update a Notification policy description: Update a Notification policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/aaa_policy-id' requestBody: required: true content: application/json: schema: properties: alert_interval: $ref: '#/components/schemas/aaa_alert_interval' alert_type: $ref: '#/components/schemas/aaa_alert_type' description: $ref: '#/components/schemas/aaa_schemas-description' enabled: $ref: '#/components/schemas/aaa_enabled' filters: $ref: '#/components/schemas/aaa_filters' mechanisms: $ref: '#/components/schemas/aaa_mechanisms' name: $ref: '#/components/schemas/aaa_schemas-name' responses: '200': description: Update a Notification policy response content: application/json: schema: $ref: '#/components/schemas/aaa_id_response' 4XX: description: Update a Notification policy response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_id_response' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification policies x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.policies x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/alerting/v3/policies/{policy_id}/email/unsubscribe: get: operationId: notification-policies-show-email-unsubscribe-details summary: Show email unsubscribe details description: Shows details for unsubscribing an email address from a notification policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/aaa_policy-id' - name: email in: query required: true schema: type: string format: email - name: token in: query required: true schema: type: string responses: '200': description: Show email unsubscribe details response content: application/json: schema: $ref: '#/components/schemas/aaa_unsubscribe_email_single_response' text/html: schema: type: string 4XX: description: Show email unsubscribe details response failure content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: [] tags: - Notification policies x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-fern-availability: generally-available x-fern-sdk-group-name: alerting.policies.email x-fern-sdk-method-name: details x-forge-hidden: true post: operationId: notification-policies-unsubscribe-email-from-notification-policy summary: Unsubscribe email from a Notification policy description: Unsubscribes an email address from a notification policy. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/aaa_policy-id' - name: email in: query required: true schema: type: string format: email - name: token in: query required: true schema: type: string responses: '200': description: Unsubscribe email from Notification policy response content: application/json: schema: $ref: '#/components/schemas/aaa_unsubscribe_email_post_single_response' text/html: schema: type: string 4XX: description: Unsubscribe email from Notification policy response failure content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: [] tags: - Notification policies x-fern-availability: generally-available x-fern-sdk-group-name: alerting.policies.email x-fern-sdk-method-name: unsubscribe x-forge-hidden: true /accounts/{account_id}/alerting/v3/policies/{policy_id}/test: post: operationId: notification-policies-test-a-notification-policy summary: Test a Notification policy description: Send a test notification for a policy to verify delivery mechanisms are working as expected. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: policy_id in: path required: true schema: $ref: '#/components/schemas/aaa_policy-id' requestBody: description: Optional configuration for the test notification. When omitted, a default INFO-severity test alert is sent. content: application/json: schema: type: object properties: severity: description: Severity level for the test alert. Defaults to INFO (1) if omitted. type: integer example: 1 enum: - 0 - 1 - 2 - 3 - 4 source: description: Source identifier for the test alert. type: string state_correlation_id: description: Correlation ID for stateful test alerts. Required when state_event is set. type: string state_event: description: State event type for stateful test alerts. Use with state_correlation_id. type: integer enum: - 0 - 1 - 2 responses: '200': description: Test a Notification policy response content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-common-2' 4XX: description: Test a Notification policy response failure. Common causes include an invalid or non-existent policy ID, or a delivery mechanism that is unreachable. content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification policies x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.policies x-fern-sdk-method-name: test x-forge-hidden: true /accounts/{account_id}/alerting/v3/silences: get: operationId: notification-silences-list-silences summary: List Silences description: Gets a list of silences for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' responses: '200': description: List Silences response content: application/json: schema: $ref: '#/components/schemas/aaa_silences_components-schemas-response_collection' 4XX: description: List Silences response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_silences_components-schemas-response_collection' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification Silences x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-fern-availability: generally-available x-fern-sdk-group-name: alerting.silences x-fern-sdk-method-name: list x-forge-hidden: true post: operationId: notification-silences-create-silences summary: Create Silences description: Creates a new silence for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/aaa_silence_create_request' responses: '200': description: Create Silences response content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-common-2' 4XX: description: Create Silences response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_silences_components-schemas-response_collection' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification Silences x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.silences x-fern-sdk-method-name: create x-forge-hidden: true put: operationId: notification-silences-update-silences summary: Update Silences description: Updates existing silences for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/aaa_silence_update_request' responses: '200': description: Update Silences response content: application/json: schema: $ref: '#/components/schemas/aaa_silences_components-schemas-response_collection' 4XX: description: Update Silences response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_silences_components-schemas-response_collection' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification Silences x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.silences x-fern-sdk-method-name: update x-forge-hidden: true /accounts/{account_id}/alerting/v3/silences/{silence_id}: delete: operationId: notification-silences-delete-silences summary: Delete Silence description: Deletes an existing silence for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: silence_id in: path required: true schema: $ref: '#/components/schemas/aaa_silence-id' responses: '200': description: Delete Silence response content: application/json: schema: $ref: '#/components/schemas/aaa_api-response-common-2' 4XX: description: Delete Silence response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_silence_components-schemas-response_collection' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification Silences x-api-token-group: - Notifications Write - Account Settings Write x-fern-availability: generally-available x-fern-sdk-group-name: alerting.silences x-fern-sdk-method-name: delete x-forge-hidden: true x-forge-require-confirmation: This operation deletes the notification silence. get: operationId: notification-silences-get-silence summary: Get Silence description: Gets a specific silence for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_account-id' - name: silence_id in: path required: true schema: $ref: '#/components/schemas/aaa_silence-id' responses: '200': description: Get Silence response content: application/json: schema: $ref: '#/components/schemas/aaa_silence_components-schemas-response_collection' 4XX: description: Get Silence response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_silence_components-schemas-response_collection' - $ref: '#/components/schemas/aaa_api-response-common-failure-3' security: - api_token: [] - api_email: [] api_key: [] tags: - Notification Silences x-api-token-group: - 'Zero Trust: PII Read' - Notifications Write - Notifications Read - Account Settings Write - Account Settings Read x-fern-availability: generally-available x-fern-sdk-group-name: alerting.silences x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/analytics/query/{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. 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`. required: true schema: type: string example: access-logins requestBody: required: true content: application/json: examples: access_summary: summary: Access login summary for a week value: filters: [] from: 2024-11-01T00:00:00Z groupBy: [] stats: - attemptsTotal to: 2024-11-08T00:00:00Z schema: $ref: '#/components/schemas/art_QuerySummary' responses: '200': description: Summary query result. content: application/json: examples: success: summary: Successful summary result value: errors: [] messages: - code: 1000 message: 'API in beta: expect breaking changes.' result: currentTotal: - attemptsTotal: 48291 previousTotal: - attemptsTotal: 41033 success: true schema: $ref: '#/components/schemas/art_SummaryResponse' '400': $ref: '#/components/responses/art_BadRequest' '401': $ref: '#/components/responses/art_Unauthorized' '403': $ref: '#/components/responses/art_Forbidden' security: - api_token: [] - api_email: [] api_key: [] tags: - ART Analytics x-api-token-group: - Zero Trust Read x-fern-availability: generally-available x-fern-sdk-group-name: analytics.query x-fern-sdk-method-name: artAnalyticsQuerySummary x-forge-hidden: true /accounts/{account_id}/analytics/query/{dataset}/timeseries: post: operationId: art-analytics-query-timeseries summary: Query analytics timeseries description: | Returns time-bucketed analytics data for a dataset. Includes time slots, each containing the requested stats, group-by dimensions, and resolution-controlled bucket size (e.g. `hour`, `day`). 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`. required: true schema: type: string example: shadow_it requestBody: required: true content: application/json: examples: access_logins_daily: summary: Access logins daily timeseries with filter value: filters: - name: allowed op: eq values: - true from: 2024-11-01T00:00:00Z groupBy: - country - allowed resolution: day stats: - attemptsTotal to: 2024-11-08T00:00:00Z shadow_it_hourly: summary: Shadow IT hourly timeseries value: filters: [] from: 2024-11-05T00:00:00Z groupBy: - appName resolution: hour stats: - bytesTotal to: 2024-11-06T00:00:00Z schema: $ref: '#/components/schemas/art_QueryTimeseries' responses: '200': description: Timeseries query result. content: application/json: examples: success: summary: Successful timeseries result value: errors: [] messages: - code: 1000 message: 'API in beta: expect breaking changes.' result: resolution: hour slots: - appName: Slack bytesTotal: 1048576 time_bucket: 2024-11-05T00:00:00Z - appName: Slack bytesTotal: 2097152 time_bucket: 2024-11-05T01:00:00Z success: true schema: $ref: '#/components/schemas/art_TimeseriesResponse' '400': $ref: '#/components/responses/art_BadRequest' '401': $ref: '#/components/responses/art_Unauthorized' '403': $ref: '#/components/responses/art_Forbidden' security: - api_token: [] - api_email: [] api_key: [] tags: - ART Analytics x-api-token-group: - Zero Trust Read x-fern-availability: generally-available x-fern-sdk-group-name: analytics.query x-fern-sdk-method-name: artAnalyticsQueryTimeseries x-forge-hidden: true /accounts/{account_id}/analytics/query/{dataset}/top-n: post: operationId: art-analytics-query-top-n summary: Query analytics top-N description: | Returns the top N results for a dataset by a specified stat. Includes an array of result rows, each containing the requested stats and group-by dimensions. 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`. required: true schema: type: string example: gateway-http requestBody: required: true content: application/json: examples: top_apps_by_bytes: summary: Top 10 shadow IT apps by bytes value: filters: [] from: 2024-11-05T00:00:00Z groupBy: - appName - appCategory n: 10 orderBy: bytesTotal stats: - bytesTotal - requestsTotal to: 2024-11-06T00:00:00Z top_countries_access: summary: Top 5 countries by login attempts value: filters: - name: allowed op: eq values: - false from: 2024-11-01T00:00:00Z groupBy: - country n: 5 orderBy: attemptsTotal stats: - attemptsTotal to: 2024-11-08T00:00:00Z schema: $ref: '#/components/schemas/art_QueryTopN' responses: '200': description: Top-N query result. content: application/json: examples: success: summary: Successful top-N result value: errors: [] messages: - code: 1000 message: 'API in beta: expect breaking changes.' result: - appCategory: Collaboration appName: Slack bytesTotal: 10485760 requestsTotal: 1024 - appCategory: File Storage appName: Dropbox bytesTotal: 5242880 requestsTotal: 512 success: true schema: $ref: '#/components/schemas/art_TopNResponse' '400': $ref: '#/components/responses/art_BadRequest' '401': $ref: '#/components/responses/art_Unauthorized' '403': $ref: '#/components/responses/art_Forbidden' security: - api_token: [] - api_email: [] api_key: [] tags: - ART Analytics x-api-token-group: - Zero Trust Read x-fern-availability: generally-available x-fern-sdk-group-name: analytics.query x-fern-sdk-method-name: artAnalyticsQueryTopN x-forge-hidden: true /accounts/{account_id}/analytics/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. parameters: - $ref: '#/components/parameters/art_account_id' requestBody: required: true content: application/json: examples: top_integrations: summary: Top 10 integrations by content findings value: filters: [] from: 2024-11-01T00:00:00Z n: 10 to: 2024-11-08T00:00:00Z schema: $ref: '#/components/schemas/art_DataSecurityContentFindingsTopNQuery' responses: '200': description: Top integrations result. content: application/json: examples: success: summary: Successful top integrations result value: errors: [] messages: - code: 1000 message: 'API in beta: expect breaking changes.' result: - integrationId: 123e4567-e89b-12d3-a456-426614174000 integrationName: Google Workspace total: 42 - integrationId: 223e4567-e89b-12d3-a456-426614174001 integrationName: Microsoft 365 total: 17 success: true schema: $ref: '#/components/schemas/art_TopNResponse' '400': $ref: '#/components/responses/art_BadRequest' '401': $ref: '#/components/responses/art_Unauthorized' '403': $ref: '#/components/responses/art_Forbidden' security: - api_token: [] - api_email: [] api_key: [] tags: - Data Security x-api-token-group: - Zero Trust Read x-fern-availability: generally-available x-fern-sdk-group-name: analytics.query x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/analytics/query/data-security/findings/summary: post: operationId: data-security-findings-summary summary: Data security findings summary description: | Returns aggregate current-period and previous-period totals for CASB findings. parameters: - $ref: '#/components/parameters/art_account_id' requestBody: required: true content: application/json: examples: findings_summary: summary: Summary for a week value: filters: [] from: 2024-11-01T00:00:00Z to: 2024-11-08T00:00:00Z schema: $ref: '#/components/schemas/art_DataSecurityFindingsSummaryQuery' responses: '200': description: Findings summary result. content: application/json: examples: success: summary: Successful findings summary value: errors: [] messages: - code: 1000 message: 'API in beta: expect breaking changes.' result: currentTotal: - findingProduct: Cloud findingType: Content findingsTotal: 48291 - findingProduct: SaaS findingType: Posture findingsTotal: 1205 previousTotal: - findingProduct: Cloud findingType: Content findingsTotal: 41033 - findingProduct: SaaS findingType: Posture findingsTotal: 982 success: true schema: $ref: '#/components/schemas/art_SummaryResponse' '400': $ref: '#/components/responses/art_BadRequest' '401': $ref: '#/components/responses/art_Unauthorized' '403': $ref: '#/components/responses/art_Forbidden' security: - api_token: [] - api_email: [] api_key: [] tags: - Data Security x-api-token-group: - Zero Trust Read x-fern-availability: generally-available x-fern-sdk-group-name: analytics.query x-fern-sdk-method-name: dataSecurityFindingsSummary x-forge-hidden: true /accounts/{account_id}/analytics/query/data-security/findings/timeseries: post: operationId: data-security-findings-timeseries summary: Data security findings timeseries description: | Returns merged time-bucketed CASB findings. parameters: - $ref: '#/components/parameters/art_account_id' requestBody: required: true content: application/json: examples: findings_timeseries: summary: Weekly findings timeseries value: filters: [] from: 2024-11-01T00:00:00Z to: 2024-11-08T00:00:00Z schema: $ref: '#/components/schemas/art_DataSecurityFindingsTimeseriesQuery' responses: '200': description: Findings timeseries result. content: application/json: examples: success: summary: Successful findings timeseries value: errors: [] messages: - code: 1000 message: 'API in beta: expect breaking changes.' result: slots: - content: cloud: 150 saas: 23 posture: cloud: 0 saas: 5 timestamp: 2024-11-05T00:00:00Z - content: cloud: 180 saas: 30 posture: cloud: 0 saas: 7 timestamp: 2024-11-06T00:00:00Z success: true schema: $ref: '#/components/schemas/art_DataSecurityFindingsTimeseriesResponse' '400': $ref: '#/components/responses/art_BadRequest' '401': $ref: '#/components/responses/art_Unauthorized' '403': $ref: '#/components/responses/art_Forbidden' security: - api_token: [] - api_email: [] api_key: [] tags: - Data Security x-api-token-group: - Zero Trust Read x-fern-availability: generally-available x-fern-sdk-group-name: analytics.query x-fern-sdk-method-name: dataSecurityFindingsTimeseries x-forge-hidden: true /accounts/{account_id}/analytics_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 FROM my_dataset WHERE timestamp > NOW() - INTERVAL '7' DAY GROUP BY blob1 ORDER BY total DESC LIMIT 100 json_format_query: summary: Query with JSON output format value: SELECT blob1, count() FROM my_dataset GROUP BY blob1 FORMAT JSON simple_query: summary: Simple count query value: SELECT count() FROM my_dataset schema: description: Supply a SQL query to run against your Analytics Engine datasets. Use only SELECT statements. The service validates the query against a restricted SQL grammar before execution. type: string responses: '200': $ref: '#/components/responses/analytics-engine_QuerySuccess' '400': $ref: '#/components/responses/analytics-engine_BadRequest' '403': $ref: '#/components/responses/analytics-engine_Forbidden' '422': $ref: '#/components/responses/analytics-engine_UnprocessableQuery' '429': $ref: '#/components/responses/analytics-engine_TooManyRequests' '500': $ref: '#/components/responses/analytics-engine_InternalServerError' '503': $ref: '#/components/responses/analytics-engine_ServiceUnavailable' '504': $ref: '#/components/responses/analytics-engine_GatewayTimeout' security: - api_token: [] tags: - Analytics Engine x-api-token-group: - Account Analytics Read x-fern-availability: generally-available x-fern-sdk-group-name: analytics_engine.sql x-fern-sdk-method-name: query x-forge-hidden: true /accounts/{account_id}/artifacts/namespaces: get: operationId: artifacts_namespaces_list summary: List namespaces description: Lists Artifacts namespaces for an account. parameters: - name: limit in: query schema: type: integer default: 100 maximum: 200 minimum: 1 - name: cursor in: query schema: type: string responses: '200': description: Namespaces. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: array items: properties: created_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ jurisdiction: type: string enum: - unrestricted - us - eu - fedramp namespace: type: string repo_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 updated_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ required: - namespace - jurisdiction - repo_count - created_at - updated_at type: object result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}: get: operationId: artifacts_namespaces_get summary: Get a namespace description: Returns an Artifacts namespace summary. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ responses: '200': description: Namespace. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: created_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ jurisdiction: type: string enum: - unrestricted - us - eu - fedramp namespace: type: string repo_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 updated_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ required: - namespace - jurisdiction - repo_count - created_at - updated_at result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/repos: get: operationId: artifacts_repos_list summary: List repositories description: Lists repositories in a namespace. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: limit in: query schema: type: integer default: 50 maximum: 200 minimum: 1 - name: cursor in: query schema: type: string - name: search in: query schema: type: string - name: sort in: query schema: type: string default: created_at enum: - created_at - updated_at - last_push_at - name - name: direction in: query schema: type: string default: desc enum: - asc - desc responses: '200': description: Repositories. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: array items: properties: created_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ default_branch: description: Default branch name. Must not contain '..' and must not end with '/' or '.'. type: string description: type: string nullable: true id: type: string last_push_at: type: string format: date-time nullable: true pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ name: type: string read_only: type: boolean remote: type: string source: type: string nullable: true updated_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ required: - id - name - description - default_branch - created_at - updated_at - last_push_at - source - read_only - remote type: object result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string post: operationId: artifacts_repos_create summary: Create a repository description: Creates a Git-compatible Artifacts repository in a namespace. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ requestBody: required: true content: application/json: schema: type: object properties: default_branch: description: Git branch name. Must match /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/, must not contain '..', and must not end with '/' or '.'. type: string maxLength: 256 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._/-]*$ description: type: string maxLength: 1024 name: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ read_only: type: boolean required: - name responses: '201': description: Repository created. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: default_branch: type: string description: type: string nullable: true id: type: string name: type: string remote: type: string token: type: string required: - id - name - description - default_branch - remote - token result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '409': description: Operation conflict. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Edit x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: create x-forge-hidden: true x-stability: beta /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}: delete: operationId: artifacts_repos_delete summary: Delete a repository description: Deletes a repository and schedules cleanup of its backing data. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ responses: '202': description: Delete accepted. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: id: type: string required: - id result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Edit x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: delete x-forge-hidden: true x-stability: beta get: operationId: artifacts_repos_get summary: Get a repository description: Returns repository metadata. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ responses: '200': description: Repository. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: created_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ default_branch: description: Default branch name. Must not contain '..' and must not end with '/' or '.'. type: string description: type: string nullable: true id: type: string last_push_at: type: string format: date-time nullable: true pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ name: type: string read_only: type: boolean remote: type: string source: type: string nullable: true updated_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ required: - id - name - description - default_branch - created_at - updated_at - last_push_at - source - read_only - remote result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '409': description: Operation conflict. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/blob/{hash}: get: operationId: artifacts_repos_blob_get summary: Read a Git blob description: Returns raw bytes for an immutable Git blob object. Blob responses are cacheable forever by hash. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: hash in: path description: 40-character lowercase hexadecimal Git object hash. required: true schema: type: string pattern: ^[0-9a-f]{40}$ responses: '200': description: Blob bytes. headers: cache-control: description: Immutable object cache policy. schema: type: string content-length: description: Size of the response body in bytes. schema: type: integer content: application/octet-stream: schema: type: string format: binary '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '413': description: Request entity too large. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/commit/{hash}: get: operationId: artifacts_repos_commit_get summary: Read a Git commit description: Returns decoded metadata for an immutable Git commit object. Commit responses are cacheable forever by hash. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: hash in: path description: 40-character lowercase hexadecimal Git object hash. required: true schema: type: string pattern: ^[0-9a-f]{40}$ responses: '200': description: Commit metadata. headers: cache-control: schema: type: string content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: author: type: object properties: email: type: string name: type: string required: - name - email authoredAt: type: integer maximum: 9007199254740991 minimum: -9007199254740991 committedAt: type: integer maximum: 9007199254740991 minimum: -9007199254740991 committer: type: object properties: email: type: string name: type: string required: - name - email hash: type: string pattern: ^[0-9a-f]{40}$ message: type: string parents: type: array items: pattern: ^[0-9a-f]{40}$ type: string treeHash: type: string pattern: ^[0-9a-f]{40}$ required: - hash - treeHash - message - author - committer - parents - authoredAt - committedAt result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/file: get: operationId: artifacts_repos_file_get summary: Read a file description: Returns raw bytes for a file resolved by ref and path. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: ref in: query description: Git ref, branch, tag, or commit hash. required: true schema: type: string minLength: 1 - name: path in: query description: File path. required: true schema: type: string minLength: 1 responses: '200': description: File bytes. headers: content-length: description: Size of the response body in bytes. schema: type: integer content: application/octet-stream: schema: type: string format: binary '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '413': description: Request entity too large. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/fork: parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string post: operationId: artifacts_repos_fork summary: Fork a repository description: Forks a source repository into a new repository. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ requestBody: required: true content: application/json: schema: type: object properties: default_branch_only: type: boolean description: type: string maxLength: 1024 name: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ read_only: type: boolean required: - name responses: '201': description: Repository forked. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: default_branch: type: string description: type: string nullable: true id: type: string name: type: string objects: type: integer maximum: 9007199254740991 minimum: -9007199254740991 remote: type: string token: type: string required: - id - name - description - default_branch - remote - token - objects result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '409': description: Operation conflict. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '503': description: Service unavailable. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Edit x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: create x-forge-hidden: true x-stability: beta /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/import: parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string post: operationId: artifacts_repos_import summary: Import a repository description: Imports an HTTPS Git repository into an Artifacts repository. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ requestBody: required: true content: application/json: schema: type: object properties: branch: description: Git branch name. Must match /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/, must not contain '..', and must not end with '/' or '.'. type: string maxLength: 256 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._/-]*$ depth: type: integer maximum: 9007199254740991 minimum: 1 read_only: type: boolean url: type: string format: uri required: - url responses: '201': description: Repository import started. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: default_branch: type: string description: type: string nullable: true id: type: string name: type: string remote: type: string token: type: string required: - id - name - description - default_branch - remote - token result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '409': description: Operation conflict. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '413': description: Request entity too large. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '422': description: Unprocessable entity. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '502': description: Upstream unavailable. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '503': description: Service unavailable. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '504': description: Gateway timeout. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Edit x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: create x-forge-hidden: true x-stability: beta /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/log: get: operationId: artifacts_repos_log_get summary: Read commit history description: Returns commit metadata walking backwards from a ref, branch, tag, or HEAD. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: ref in: query description: Git ref, branch, tag, or commit hash. Defaults to HEAD. schema: type: string minLength: 1 - name: limit in: query schema: type: integer maximum: 1000 minimum: 1 - name: offset in: query schema: type: integer minimum: 0 responses: '200': description: Commits. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: array items: properties: author: type: object properties: email: type: string name: type: string required: - name - email authoredAt: type: integer maximum: 9007199254740991 minimum: -9007199254740991 committedAt: type: integer maximum: 9007199254740991 minimum: -9007199254740991 committer: type: object properties: email: type: string name: type: string required: - name - email hash: type: string pattern: ^[0-9a-f]{40}$ message: type: string parents: type: array items: pattern: ^[0-9a-f]{40}$ type: string treeHash: type: string pattern: ^[0-9a-f]{40}$ required: - hash - treeHash - message - author - committer - parents - authoredAt - committedAt type: object result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/raw/{ref}/{path}: get: operationId: artifacts_repos_raw_get summary: Read a raw file with content type description: Returns file bytes resolved by ref and path, with a sniffed content type and browser-safe response headers. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: ref in: path description: Git ref, branch, tag, or 40-character commit hash. required: true schema: type: string minLength: 1 - name: path in: path description: File path. May contain slashes. required: true schema: type: string minLength: 1 responses: '200': description: File bytes with sniffed Content-Type and browser-safe response headers. headers: content-length: description: Size of the response body in bytes. schema: type: integer content-security-policy: schema: type: string content: application/json: schema: type: string application/octet-stream: schema: type: string format: binary text/html: schema: type: string text/plain: schema: type: string '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '413': description: Request entity too large. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/tokens: get: operationId: artifacts_repo_tokens_list summary: List repository tokens description: Lists tokens for a repository. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: state in: query schema: type: string default: active enum: - active - expired - revoked - all - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 30 maximum: 100 minimum: 1 responses: '200': description: Tokens. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: array items: properties: created_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ expires_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ id: type: string scope: type: string enum: - read - write state: type: string enum: - active - expired - revoked required: - id - scope - state - created_at - expires_at type: object result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '409': description: Operation conflict. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/tree/{hash}: get: operationId: artifacts_repos_tree_get summary: Read a Git tree description: Returns decoded entries for an immutable Git tree object. Tree responses are cacheable forever by hash. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: name in: path description: Repository name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: hash in: path description: 40-character lowercase hexadecimal Git object hash. required: true schema: type: string pattern: ^[0-9a-f]{40}$ responses: '200': description: Tree entries. headers: cache-control: schema: type: string content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: array items: properties: hash: type: string pattern: ^[0-9a-f]{40}$ mode: type: string name: type: string type: type: string enum: - tree - blob - symlink - gitlink - exec required: - name - mode - hash - type type: object result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Read x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: get x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/artifacts/namespaces/{namespace}/tokens: parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string post: operationId: artifacts_tokens_create summary: Create a repository token description: Creates a scoped Git token for a repository. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ requestBody: required: true content: application/json: schema: type: object properties: repo: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ scope: type: string enum: - read - write ttl: type: integer maximum: 31536000 minimum: 60 required: - repo responses: '201': description: Token created. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: expires_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ id: type: string plaintext: type: string scope: type: string enum: - read - write required: - id - plaintext - scope - expires_at result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '409': description: Operation conflict. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Edit x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: create x-forge-hidden: true x-stability: beta /accounts/{account_id}/artifacts/namespaces/{namespace}/tokens/{id}: delete: operationId: artifacts_tokens_revoke summary: Revoke a token description: Revokes an Artifacts repository token. parameters: - name: namespace in: path description: Artifacts namespace name. required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ - name: id in: path description: Token ID. Must match /^[0-9a-z]{16}$/. required: true schema: type: string pattern: ^[0-9a-z]{16}$ responses: '200': description: Token revoked. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object properties: id: type: string required: - id result_info: anyOf: - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 cursor: type: string per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - cursor - per_page - count type: object - properties: count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 per_page: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_count: type: integer maximum: 9007199254740991 minimum: -9007199254740991 total_pages: type: integer maximum: 9007199254740991 minimum: -9007199254740991 required: - page - per_page - total_pages - count - total_count type: object success: type: boolean enum: - true required: - result - success - errors - messages '401': description: Authentication required. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '403': description: Insufficient permissions. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '404': description: Resource not found. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages '500': description: Internal server error. content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object minItems: 1 messages: type: array items: properties: code: type: integer maximum: 9007199254740991 minimum: -9007199254740991 documentation_url: type: string format: uri message: type: string source: type: object properties: pointer: type: string required: - code - message type: object result: type: object nullable: true success: type: boolean enum: - false required: - result - success - errors - messages security: - api_token: [] tags: - Artifacts x-api-token-group: - Artifacts Edit x-fern-availability: beta x-fern-sdk-group-name: artifacts.namespaces x-fern-sdk-method-name: delete x-forge-hidden: true x-stability: beta parameters: - name: account_id in: path description: Cloudflare account ID. required: true schema: type: string /accounts/{account_id}/audit_logs: get: operationId: audit-logs-get-account-audit-logs summary: Get account audit logs description: Gets a list of audit logs for an account. Can be filtered by who made the change, on which zone, and the timeframe of the change. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/aaa_identifier' - name: id in: query schema: description: Finds a specific log by its ID. type: string example: f174be97-19b1-40d6-954d-70cd5fbd52db - name: export in: query schema: description: Indicates that this request is an export of logs in CSV format. type: boolean example: true - name: action.type in: query schema: description: Filters by the action type. type: string example: add - name: actor.ip in: query schema: description: Filters by the IP address of the request that made the change by specific IP address or valid CIDR Range. type: string example: 17.168.228.63 - name: actor.email in: query schema: description: Filters by the email address of the actor that made the change. type: string format: email example: alice@example.com - name: since in: query schema: oneOf: - description: Limits the returned results to logs newer than the specified date. A `full-date` that conforms to RFC3339. example: 2019-04-30 format: date type: string - description: Limits the returned results to logs newer than the specified date. A `date-time` that conforms to RFC3339. example: 2019-04-30T01:12:20Z format: date-time type: string - name: before in: query schema: oneOf: - description: Limits the returned results to logs older than the specified date. A `full-date` that conforms to RFC3339. example: 2019-04-30 format: date type: string - description: Limits the returned results to logs older than the specified date. A `date-time` that conforms to RFC3339. example: 2019-04-30T01:12:20Z format: date-time type: string - name: zone.name in: query schema: description: Filters by the name of the zone associated to the change. type: string example: example.com - name: direction in: query schema: description: Changes the direction of the chronological sorting. type: string example: desc default: desc enum: - desc - asc - name: per_page in: query schema: description: Sets the number of results to return per page. type: number example: 25 default: 100 maximum: 1000 minimum: 1 - name: page in: query schema: description: Defines which page of results to return. type: number example: 50 default: 1 minimum: 1 - name: hide_user_logs in: query schema: description: Indicates whether or not to hide user level audit logs. type: boolean default: false responses: '200': description: Get account audit logs response content: application/json: schema: $ref: '#/components/schemas/aaa_audit_logs_response_collection' 4XX: description: Get account audit logs response failure content: application/json: schema: allOf: - $ref: '#/components/schemas/aaa_audit_logs_response_collection' - $ref: '#/components/schemas/aaa_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Audit Logs x-api-token-group: - Account Settings Write - Account Settings Read x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: audit-logs x-fern-sdk-method-name: list x-forge-hidden: true /accounts/{account_id}/autorag/rags/{id}/ai-search: post: operationId: autorag-config-ai-search summary: AI Search description: Runs an AI Search query against an AutoRAG. parameters: - name: id in: path description: rag id required: true schema: description: rag id type: string example: my-rag maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: filters: anyOf: - properties: key: type: string type: type: string enum: - eq - ne - gt - gte - lt - lte value: anyOf: - type: string - type: number - type: boolean required: - key - type - value type: object - properties: filters: type: array items: properties: key: type: string type: type: string enum: - eq - ne - gt - gte - lt - lte value: anyOf: - type: string - type: number - type: boolean required: - key - type - value type: object type: type: string enum: - and - or required: - type - filters type: object max_num_results: type: integer default: 10 maximum: 50 minimum: 1 model: anyOf: - enum: - '@cf/meta/llama-3.3-70b-instruct-fp8-fast' - '@cf/meta/llama-3.1-8b-instruct-fast' - '@cf/meta/llama-3.1-8b-instruct-fp8' - '@cf/meta/llama-4-scout-17b-16e-instruct' - '@cf/qwen/qwen3-30b-a3b-fp8' - '@cf/deepseek-ai/deepseek-r1-distill-qwen-32b' - '@cf/moonshotai/kimi-k2-instruct' - anthropic/claude-3-7-sonnet - anthropic/claude-sonnet-4 - anthropic/claude-opus-4 - anthropic/claude-3-5-haiku - cerebras/qwen-3-235b-a22b-instruct - cerebras/qwen-3-235b-a22b-thinking - cerebras/llama-3.3-70b - cerebras/llama-4-maverick-17b-128e-instruct - cerebras/llama-4-scout-17b-16e-instruct - cerebras/gpt-oss-120b - google-ai-studio/gemini-2.5-flash - google-ai-studio/gemini-2.5-pro - grok/grok-4 - groq/llama-3.3-70b-versatile - groq/llama-3.1-8b-instant - openai/gpt-5 - openai/gpt-5-mini - openai/gpt-5-nano type: string - enum: - '' type: string query: type: string ranking_options: type: object default: {} properties: ranker: type: string score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 reranking: type: object properties: enabled: type: boolean default: false model: anyOf: - enum: - '@cf/baai/bge-reranker-base' type: string - enum: - '' type: string rewrite_query: type: boolean default: false stream: type: boolean default: false system_prompt: type: string required: - query responses: '200': description: Returns the log details content: application/json: schema: type: object properties: result: type: object properties: data: type: array items: properties: attributes: type: object content: items: properties: text: type: string type: type: string type: object type: array file_id: type: string filename: type: string score: type: number required: - score type: object has_more: type: boolean default: false next_page: type: string nullable: true object: type: string response: type: string search_query: type: string required: - search_query - response success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AutoRAG RAG Search x-api-token-group: - Auto Rag Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.rag x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-ignore: true x-fern-sdk-group-name: autorag x-fern-sdk-method-name: ai-search /accounts/{account_id}/autorag/rags/{id}/files: get: operationId: autorag-config-files summary: Files description: Lists files indexed by an AutoRAG. parameters: - name: id in: path description: rag id required: true schema: description: rag id type: string example: my-rag maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 50 minimum: 0 - name: search in: query schema: type: string - name: status in: query schema: type: string enum: - completed - queued - running - error responses: '200': description: Returns the AI Search files content: application/json: schema: type: object properties: result: type: array items: properties: error: type: string key: type: string required: - key - error type: object result_info: type: object properties: count: type: integer page: type: integer per_page: type: integer default: 20 maximum: 50 minimum: 5 total_count: type: integer required: - count - page - total_count success: type: boolean required: - success - result - result_info '404': description: autorag_not_found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: autorag_not_found required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: unable_to_connect_to_autorag content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7017 message: type: string example: unable_to_connect_to_autorag required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AutoRAG RAG x-api-token-group: - Auto Rag Write - Auto Rag Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.rag x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-ignore: true x-fern-sdk-group-name: autorag x-fern-sdk-method-name: files /accounts/{account_id}/autorag/rags/{id}/jobs: get: operationId: autorag-config-list-jobs summary: List Jobs description: Lists jobs for an AutoRAG. parameters: - name: id in: path description: rag id required: true schema: description: rag id type: string example: my-rag maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 50 minimum: 0 responses: '200': description: Returns a list of AutoRAG Jobs content: application/json: schema: type: object properties: result: type: array items: properties: end_reason: type: string ended_at: type: string id: type: string last_seen_at: type: string source: type: string enum: - user - schedule started_at: type: string required: - id - source type: object result_info: type: object properties: count: type: integer page: type: integer per_page: type: integer total_count: type: integer required: - count - page - per_page - total_count success: type: boolean required: - success - result - result_info '404': description: autorag_not_found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: autorag_not_found required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: unable_to_connect_to_autorag content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7017 message: type: string example: unable_to_connect_to_autorag required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AutoRAG Jobs x-api-token-group: - Auto Rag Write - Auto Rag Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.rag x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-ignore: true x-fern-sdk-group-name: autorag.jobs x-fern-sdk-method-name: list /accounts/{account_id}/autorag/rags/{id}/jobs/{job_id}: get: operationId: autorag-config-get-job summary: Get a Job Details description: Returns details for an AutoRAG job. parameters: - name: id in: path description: rag id required: true schema: description: rag id type: string example: my-rag maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: job_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 responses: '200': description: Returns a AutoRAG Job Details content: application/json: schema: type: object properties: result: type: object properties: end_reason: type: string ended_at: type: string id: type: string last_seen_at: type: string source: type: string enum: - user - schedule started_at: type: string required: - id - source success: type: boolean required: - success - result '404': description: job_not_found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7021 message: type: string example: job_not_found required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: unable_to_connect_to_autorag content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7017 message: type: string example: unable_to_connect_to_autorag required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AutoRAG Jobs x-api-token-group: - Auto Rag Write - Auto Rag Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.rag x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-ignore: true x-fern-sdk-group-name: autorag.jobs x-fern-sdk-method-name: get /accounts/{account_id}/autorag/rags/{id}/jobs/{job_id}/logs: get: operationId: autorag-config-list-job-logs summary: List Job Logs description: Lists logs for an AutoRAG job. parameters: - name: id in: path description: rag id required: true schema: description: rag id type: string example: my-rag maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: job_id in: path required: true schema: type: string - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 - name: page in: query schema: type: integer default: 1 minimum: 1 - name: per_page in: query schema: type: integer default: 20 maximum: 500 minimum: 0 responses: '200': description: Returns a list of AutoRAG Job Logs content: application/json: schema: type: object properties: result: type: array items: properties: created_at: type: number id: type: integer message: type: string message_type: type: integer required: - id - message - message_type - created_at type: object result_info: type: object properties: count: type: integer page: type: integer per_page: type: integer total_count: type: integer required: - count - page - per_page - total_count success: type: boolean required: - success - result - result_info '404': description: autorag_not_found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: autorag_not_found required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: unable_to_connect_to_autorag content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7017 message: type: string example: unable_to_connect_to_autorag required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AutoRAG Jobs x-api-token-group: - Auto Rag Write - Auto Rag Read x-cfPermissionsRequired: enum: - com.cloudflare.api.account.rag x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-ignore: true x-fern-sdk-group-name: autorag.jobs x-fern-sdk-method-name: logs /accounts/{account_id}/autorag/rags/{id}/search: post: operationId: autorag-config-search summary: Search description: Searches an AutoRAG. parameters: - name: id in: path description: rag id required: true schema: description: rag id type: string example: my-rag maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 requestBody: content: application/json: schema: type: object properties: filters: anyOf: - properties: key: type: string type: type: string enum: - eq - ne - gt - gte - lt - lte value: anyOf: - type: string - type: number - type: boolean required: - key - type - value type: object - properties: filters: type: array items: properties: key: type: string type: type: string enum: - eq - ne - gt - gte - lt - lte value: anyOf: - type: string - type: number - type: boolean required: - key - type - value type: object type: type: string enum: - and - or required: - type - filters type: object max_num_results: type: integer default: 10 maximum: 50 minimum: 1 query: type: string ranking_options: type: object default: {} properties: ranker: type: string score_threshold: type: number default: 0.4 maximum: 1 minimum: 0 reranking: type: object properties: enabled: type: boolean default: false model: anyOf: - enum: - '@cf/baai/bge-reranker-base' type: string - enum: - '' type: string rewrite_query: type: boolean default: false required: - query responses: '200': description: Returns the log details content: application/json: schema: type: object properties: result: type: object properties: data: type: array items: properties: attributes: type: object content: items: properties: text: type: string type: type: string type: object type: array file_id: type: string filename: type: string score: type: number required: - score type: object has_more: type: boolean default: false next_page: type: string nullable: true object: type: string search_query: type: string required: - search_query success: type: boolean required: - success - result '404': description: Not Found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: Not Found required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AutoRAG RAG Search x-api-token-group: - Auto Rag Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.rag x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-ignore: true x-fern-sdk-group-name: autorag x-fern-sdk-method-name: search /accounts/{account_id}/autorag/rags/{id}/sync: patch: operationId: autorag-config-sync summary: Sync description: Starts synchronization for an AutoRAG. parameters: - name: id in: path description: rag id required: true schema: description: rag id type: string example: my-rag maxLength: 32 minLength: 1 pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ - name: account_id in: path required: true schema: type: string example: c3dc5f0b34a14ff8e1b3ec04895e1b22 responses: '200': description: Returns the autorag sync status content: application/json: schema: type: object properties: result: type: object properties: job_id: type: string required: - job_id success: type: boolean required: - success - result '400': description: autorag_is_paused content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7032 message: type: string example: autorag_is_paused required: - code - message type: object success: type: boolean enum: - false required: - success - errors '404': description: autorag_not_found content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7002 message: type: string example: autorag_not_found required: - code - message type: object success: type: boolean enum: - false required: - success - errors '429': description: sync_in_cooldown content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7020 message: type: string example: sync_in_cooldown required: - code - message type: object success: type: boolean enum: - false required: - success - errors '503': description: unable_to_connect_to_autorag content: application/json: schema: type: object properties: errors: type: array items: properties: code: type: number example: 7017 message: type: string example: unable_to_connect_to_autorag required: - code - message type: object success: type: boolean enum: - false required: - success - errors security: - api_token: [] - api_email: [] api_key: [] tags: - AutoRAG RAG x-api-token-group: - Auto Rag Write x-cfPermissionsRequired: enum: - com.cloudflare.api.account.rag x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-ignore: true x-fern-sdk-group-name: autorag x-fern-sdk-method-name: sync /accounts/{account_id}/billable-usage: get: operationId: billable-usage-get-v1-account-usage summary: Get Account Billable Usage (Version 1, Alpha) description: | Returns billable usage data for the account. When no query parameters are provided, returns usage for the current billing period. 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, and subscription metadata. 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 with the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/) Cost and Usage dataset specification. Each record represents one billable metric for one account on one day. This includes all metered usage, including usage that falls within free-tier allowances and may result in zero cost. **Note:** Cost and pricing fields are not yet populated and will be absent from responses until billing integration is complete. When `from` and `to` are omitted, defaults to the start of the current month through today. The maximum date range is 31 days. 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 with the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/) Cost and Usage dataset specification. This is the filterable counterpart to `GET` on the same path. It is a read-only operation and requires only the `#billing:read` permission; `POST` is used so that filter criteria can be supplied in a request body rather than in the query string. Each record represents one billable metric for one account on one day. This includes all metered usage, including usage that falls within free-tier allowances and may result in zero cost. **Note:** Cost and pricing fields are not yet populated and will be absent from responses until billing integration is complete. The request body is optional. When it is omitted, or when `TimePeriod` is omitted, the range defaults to the start of the current month through today. The maximum date range is 31 days. Filters of different kinds are combined with AND. Values within one tag filter are combined with OR. Filter values that do not match usage produce an empty result set. Results can be grouped by up to two customer resource-tag keys. Grouped values are returned in the `Tags` field. Usage without a requested tag remains in an untagged group, with that key omitted from `Tags`. Requests using tag filtering or grouping return HTTP 400 when tag-aware usage data is unavailable. parameters: - $ref: '#/components/parameters/billable-usage-api_account_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/billable-usage-api_v2_usage_query' responses: '200': description: Account usage data was successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/billable-usage-api_v2_usage_response' 4XX: description: Indicates the request failed. content: application/json: schema: $ref: '#/components/schemas/billable-usage-api_api-response-common-failure' security: - api_token: [] - api_email: [] api_key: [] tags: - Billable Usage V2 x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: billing.usage x-fern-sdk-method-name: query /accounts/{account_id}/billing/bad-debt: get: operationId: account-billing-get-bad-debt summary: Get Account Bad Debt description: Gets bad debt information for an account, including outstanding invoices and total debt amount. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' responses: '200': description: Get Account Bad Debt response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_bad_debt_response_single' 4XX: description: Get Account Bad Debt response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: accounts.billing x-fern-sdk-method-name: getBadDebt /accounts/{account_id}/billing/credits: get: operationId: account-billing-get-credits summary: Get Account Credits description: Gets the credit balance and eligibility for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' responses: '200': description: Get Account Credits response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_account_credits_response' 4XX: description: Get Account Credits response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing x-api-token-group: - Billing Write - Billing Read x-cfPermissionsRequired: enum: - '#billing:read' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: accounts.billing x-fern-sdk-method-name: getCredits /accounts/{account_id}/billing/history: get: operationId: account-billing-history-get-billing-history summary: Get Account Billing History description: Gets the billing history for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' - name: page in: query schema: description: Page number of paginated results. type: integer default: 1 minimum: 1 - name: per_page in: query schema: description: Number of items per page. type: integer default: 20 minimum: 1 - name: status in: query schema: description: Filter billing history by status. type: string responses: '200': description: Get Account Billing History response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_account_billing_history_collection' 4XX: description: Get Account Billing History response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing History x-api-token-group: - Billing Write - Billing Read x-cfPermissionsRequired: enum: - '#billing:read' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: accounts.billing.history x-fern-sdk-method-name: list /accounts/{account_id}/billing/profile: delete: operationId: account-billing-profile-delete-billing-profile summary: Delete Billing Profile description: Deletes the billing profile for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' responses: '204': description: Delete Billing Profile response 4XX: description: Delete Billing Profile response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing Profile x-api-token-group: - Billing Write x-cfPermissionsRequired: enum: - '#billing:edit' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: billing.profiles x-fern-sdk-method-name: delete get: operationId: account-billing-profile-get-billing-profile summary: Get Billing Profile description: Gets the current billing profile for the account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' responses: '200': description: Billing Profile Details response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_billing_response_single' 4XX: description: Billing Profile Details response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing Profile x-api-token-group: - Billing Write - Billing Read x-cfPermissionsRequired: enum: - '#billing:read' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-availability: generally-available x-fern-sdk-group-name: billing.profiles x-fern-sdk-method-name: get x-forge-hidden: true patch: operationId: account-billing-profile-update-billing-email summary: Update Billing Email description: Updates the billing email addresses and preferred locale for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' requestBody: required: true content: application/json: schema: type: object properties: billing_email: type: string example: billing@example.com preferred_locale: type: string example: en-US secondary_billing_email: type: string example: secondary@example.com responses: '200': description: Update Billing Email response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_billing_response_single' 4XX: description: Update Billing Email response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing Profile x-api-token-group: - Billing Write x-cfPermissionsRequired: enum: - '#billing:read' - '#billing:edit' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: billing.profiles x-fern-sdk-method-name: updateEmail post: operationId: account-billing-profile-create-billing-profile summary: Create Billing Profile description: Creates a billing profile for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_billing_profile_request' responses: '200': description: Create Billing Profile response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_billing_response_single' 4XX: description: Create Billing Profile response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing Profile x-api-token-group: - Billing Write x-cfPermissionsRequired: enum: - '#billing:read' - '#billing:edit' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: billing.profiles x-fern-sdk-method-name: create put: operationId: account-billing-profile-update-billing-profile summary: Update Billing Profile description: Updates the billing profile for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_billing_profile_request' responses: '200': description: Update Billing Profile response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_billing_response_single' 4XX: description: Update Billing Profile response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing Profile x-api-token-group: - Billing Write x-cfPermissionsRequired: enum: - '#billing:read' - '#billing:edit' x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: billing.profiles x-fern-sdk-method-name: update /accounts/{account_id}/billing/profile/payment-method: post: operationId: account-billing-create-payment-intent summary: Create Payment Intent for Billing Profile description: Creates a Stripe payment intent for adding or updating a payment method on the account's billing profile. Returns a client secret for frontend payment method collection. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' responses: '200': description: Create Payment Intent response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_payment_intent_response_single' 4XX: description: Create Payment Intent response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing x-api-token-group: - Billing Write x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: billing.profiles x-fern-sdk-method-name: createPaymentIntent /accounts/{account_id}/billing/unpaid-invoice: get: operationId: account-billing-get-unpaid-invoices summary: Get Unpaid Invoices description: Gets unpaid invoice information for an account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/bill-subs-api_identifier' responses: '200': description: Get Unpaid Invoices response content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_unpaid_invoices_response_single' 4XX: description: Get Unpaid Invoices response failure content: application/json: schema: $ref: '#/components/schemas/bill-subs-api_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Account Billing x-cfPlanAvailability: business: true enterprise: true free: true pro: true x-fern-sdk-group-name: accounts.billing x-fern-sdk-method-name: getUnpaidInvoices /accounts/{account_id}/billing/usage: get: operationId: usage-analytics-get-account-billing-usage summary: Get account billing usage description: | Retrieve billing usage analytics for an account. Returns time-series data for all billable product metrics including Stream, Media (Images), Rate Limiting, Load Balancing, Argo, Workers, Workers KV, Image Resizing, and Spectrum. parameters: - $ref: '#/components/parameters/usage-analytics_account_id' - $ref: '#/components/parameters/usage-analytics_metrics' - $ref: '#/components/parameters/usage-analytics_since' - $ref: '#/components/parameters/usage-analytics_until' - $ref: '#/components/parameters/usage-analytics_time_delta' - $ref: '#/components/parameters/usage-analytics_limit' - $ref: '#/components/parameters/usage-analytics_filters' responses: '200': description: Usage analytics response. content: application/json: examples: success: summary: Successful billing usage retrieval value: errors: [] messages: [] result: - argoAcceleratedBytes: 5000000 imageResizingRequests: 15000 loadBalancingQueries: 10000 mediaUniqueTransformations: 45000 rateLimitingRequestsAllowed: 50000 spectrumBytesTransferred: 8000000 streamMinutesViewed: 125000 ts: 1693526400 workersKVReads: 30000 workersRequests: 200000 success: true schema: $ref: '#/components/schemas/usage-analytics_billing_usage_response' '400': $ref: '#/components/responses/usage-analytics_bad_request' '401': $ref: '#/components/responses/usage-analytics_unauthorized' '403': $ref: '#/components/responses/usage-analytics_forbidden' security: - api_token: [] - api_email: [] api_key: [] tags: - Usage Analytics x-api-token-group: - Billing Read x-fern-availability: deprecated x-fern-sdk-group-name: billing.usage x-fern-sdk-method-name: get /accounts/{account_id}/botnet_feed/asn/{asn_id}/day_report: get: operationId: botnet-threat-feed-get-day-report summary: Get daily report description: Gets all the data the botnet tracking database has for a given ASN registered to user account for given date. If no date is given, it will return results for the previous day. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/dos_identifier' - name: asn_id in: path required: true schema: $ref: '#/components/schemas/dos_asn' - name: date in: query schema: $ref: '#/components/schemas/dos_timestamp' responses: '200': description: Get botnet feed report for day content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/dos_api-response-common' - properties: result: type: object properties: cidr: type: string example: 1.1.1.1/32 date: type: string format: date-time example: 2014-01-01T05:20:00.12345Z offense_count: type: integer example: 1000 type: object 4XX: description: Get botnet feed report for day response failure content: application/json: schema: $ref: '#/components/schemas/dos_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Botnet Threat Feed x-api-token-group: - DDoS Botnet Feed Write - DDoS Botnet Feed Read x-fern-availability: generally-available x-fern-sdk-group-name: botnet-feed.asn x-fern-sdk-method-name: day-report x-forge-hidden: true /accounts/{account_id}/botnet_feed/asn/{asn_id}/full_report: get: operationId: botnet-threat-feed-get-full-report summary: Get full report description: Gets all the data the botnet threat feed tracking database has for a given ASN registered to user account. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/dos_identifier' - name: asn_id in: path required: true schema: $ref: '#/components/schemas/dos_asn' responses: '200': description: Get full botnet feed report content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/dos_api-response-common' - properties: result: type: object properties: cidr: type: string example: 1.1.1.1/32 date: type: string format: date-time example: 2014-01-01T05:20:00.12345Z offense_count: type: integer example: 1000 type: object 4XX: description: Get full botnet feed report response failure content: application/json: schema: $ref: '#/components/schemas/dos_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Botnet Threat Feed x-api-token-group: - DDoS Botnet Feed Write - DDoS Botnet Feed Read x-fern-availability: generally-available x-fern-sdk-group-name: botnet-feed.asn x-fern-sdk-method-name: full-report x-forge-hidden: true /accounts/{account_id}/botnet_feed/configs/asn: get: operationId: botnet-threat-feed-list-asn summary: Get list of ASNs description: Gets a list of all ASNs registered for a user for the DDoS Botnet Feed API. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/dos_identifier' responses: '200': description: Get list of ASNs response content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/dos_api-response-common' - properties: result: type: object properties: asn: type: integer example: 13335 type: object 4XX: description: Get list of ASNs response failure content: application/json: schema: $ref: '#/components/schemas/dos_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Botnet Threat Feed x-api-token-group: - DDoS Botnet Feed Write - DDoS Botnet Feed Read x-fern-availability: generally-available x-fern-sdk-group-name: botnet-feed.configs.asn x-fern-sdk-method-name: get x-forge-hidden: true /accounts/{account_id}/botnet_feed/configs/asn/{asn_id}: delete: operationId: botnet-threat-feed-delete-asn summary: Delete an ASN description: Delete an ASN from botnet threat feed for a given user. parameters: - name: account_id in: path required: true schema: $ref: '#/components/schemas/dos_identifier' - name: asn_id in: path required: true schema: $ref: '#/components/schemas/dos_asn' responses: '200': description: Delete ASN response content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/dos_api-response-common' - properties: result: type: object properties: asn: type: integer example: 13335 type: object 4XX: description: Delete ASN response failure content: application/json: schema: $ref: '#/components/schemas/dos_api-response-common-failure' security: - api_email: [] api_key: [] api_token: [] tags: - Botnet Threat Feed x-api-token-group: - DDoS Botnet Feed Write x-fern-availability: generally-available x-fern-sdk-group-name: botnet-feed.configs.asn x-fern-sdk-method-name: delete x-forge-hidden: true /accounts/{account_id}/brand-protection/alerts: get: operationId: getAccountsAccountIdBrandProtectionAlerts summary: Read all alerts on submitted domains description: Return all alerts on submitted domains responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: alerts x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 patch: operationId: patchAccountsAccountIdBrandProtectionAlerts summary: Update alerts on submitted domains by ID description: Return a success message after updating alerts on submitted domains by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: alerts x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/brand-protection/alerts/clear: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 patch: operationId: patchAccountsAccountIdBrandProtectionAlertsClear summary: Update verification statuses of tracked URLs to awaiting by ID description: Return a success message after updating verification statuses of tracked URLs to awaiting by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: alerts.clear x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/brand-protection/alerts/refute: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 patch: operationId: patchAccountsAccountIdBrandProtectionAlertsRefute summary: Update verification statuses of tracked URLs to disproven by ID description: Return a success message after updating verification statuses of tracked URLs to disproven by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: alerts.refute x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/brand-protection/alerts/verify: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 patch: operationId: patchAccountsAccountIdBrandProtectionAlertsVerify summary: Update verification statuses of tracked URLs to confirmed by ID description: Return a success message after updating verification statuses of tracked URLs to confirmed by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: alerts.verify x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/brand-protection/brands: delete: operationId: deleteAccountsAccountIdBrandProtectionBrands summary: Delete brands by ID description: Return a success message after deleting brands by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: brands x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: getAccountsAccountIdBrandProtectionBrands summary: Read all brands description: Return all brands responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: brands x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 post: operationId: postAccountsAccountIdBrandProtectionBrands summary: Create new brands description: Return new brands responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: brands x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/brands/patterns: delete: operationId: deleteAccountsAccountIdBrandProtectionBrandsPatterns summary: Delete patterns for brands by ID description: Return a success message after deleting patterns for brands by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: brands.patterns x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: getAccountsAccountIdBrandProtectionBrandsPatterns summary: Read patterns for brands by ID description: Return patterns for brands based on ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: brands.patterns x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 post: operationId: postAccountsAccountIdBrandProtectionBrandsPatterns summary: Create new patterns for brands by ID description: Return a success message after creating new patterns for brands by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: brands.patterns x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/clear: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 patch: operationId: patchAccountsAccountIdBrandProtectionClear summary: Update verification statuses of submitted URLs to awaiting by ID description: Return a success message after updating verification statuses of submitted URLs to awaiting by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: clear x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/brand-protection/domain-info: get: operationId: getAccountsAccountIdBrandProtectionDomainInfo summary: Read submitted domains by ID description: Return submitted domains based on ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: domain-info x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/logo-matches: get: operationId: getAccountsAccountIdBrandProtectionLogoMatches summary: Read matches for logo queries by ID description: Return matches for logo queries based on ID parameters: - name: logo_id in: query schema: type: array items: type: string explode: true style: form - name: offset in: query schema: type: string - name: limit in: query schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_LogoMatch' '422': $ref: '#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - logo_match x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: logo-matches x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/logo-matches/download: get: operationId: getAccountsAccountIdBrandProtectionLogoMatchesDownload summary: Download matches for logo queries by ID description: Return matches as CSV for logo queries based on ID parameters: - name: logo_id in: query schema: type: array items: type: string explode: true style: form - name: offset in: query schema: type: string - name: limit in: query schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_LogoMatch' '422': $ref: '#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - logo_match x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: logo-matches.download x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/logos: get: operationId: getAccountsAccountIdBrandProtectionLogos summary: Read all saved logo queries description: Return all saved logo queries responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - logo_match x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: logos x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 post: operationId: postAccountsAccountIdBrandProtectionLogos summary: Create new saved logo queries from image files description: Return new saved logo queries created from image files parameters: - name: tag in: query schema: type: string - name: match_type in: query schema: type: string - name: threshold in: query schema: type: number requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/brand-protection-api_ImageFile' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_Logo' '422': $ref: '#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - logo_match x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: logos x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/logos/{logo_id}: delete: operationId: deleteAccountsAccountIdBrandProtectionLogosLogoId summary: Delete saved logo queries by ID description: Return a success message after deleting saved logo queries by ID responses: '204': description: No Content default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - logo_match x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: logos x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: getAccountsAccountIdBrandProtectionLogosLogoId summary: Read saved logo queries by ID description: Return saved logo queries based on ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - logo_match x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: logos x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 - name: logo_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/matches: get: operationId: getAccountsAccountIdBrandProtectionMatches summary: Read matches for string queries by ID description: Return matches for string queries based on ID parameters: - name: id in: query schema: type: string - name: offset in: query schema: type: integer - name: limit in: query schema: type: integer - name: include_domain_id in: query schema: type: boolean - name: include_dismissed in: query schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_QueryMatch' '422': $ref: '#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: matches x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/matches/download: get: operationId: getAccountsAccountIdBrandProtectionMatchesDownload summary: Download matches for string queries by ID description: Return matches as CSV for string queries based on ID parameters: - name: id in: query schema: type: string - name: offset in: query schema: type: integer - name: limit in: query schema: type: integer - name: include_domain_id in: query schema: type: boolean - name: include_dismissed in: query schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_QueryMatch' '422': $ref: '#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: matches.download x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/queries: delete: operationId: deleteAccountsAccountIdBrandProtectionQueries summary: Delete saved string queries by ID description: Return a success message after deleting saved string queries by ID parameters: - name: id in: query schema: type: string - name: tag in: query schema: type: string - name: scan in: query schema: type: boolean responses: '204': description: No Content '422': $ref: '#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: queries x-fern-sdk-method-name: delete x-forge-hidden: true get: operationId: getAccountsAccountIdBrandProtectionQueries summary: Read string queries by ID description: Return string queries based on ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: queries x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 patch: operationId: patchAccountsAccountIdBrandProtectionQueries summary: Update saved string queries by ID description: Update a saved query's tag, scan setting, or string_matches (pattern). When string_matches is provided, the query parameters and hash are updated. At least one of tag, scan, or string_matches is required. requestBody: required: true content: application/json: schema: type: object properties: id: description: The query ID to update (required when updating tag or scan) type: integer scan: description: Whether to scan matches type: boolean string_matches: description: Updated pattern match constraints. When provided, replaces the existing string_matches. type: array items: properties: max_edit_distance: description: Maximum Levenshtein edit distance for fuzzy matching type: number pattern: description: The pattern to match against type: string required: - pattern type: object tag: description: Query tag. Required as identifier when updating string_matches. type: string responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: queries x-fern-sdk-method-name: edit x-forge-hidden: true post: operationId: postAccountsAccountIdBrandProtectionQueries summary: Create new saved string queries description: Return a success message after creating new saved string queries parameters: - name: id in: query schema: type: string - name: tag in: query schema: type: string - name: scan in: query schema: type: boolean requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_Query' responses: '204': description: No Content '422': $ref: '#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: queries x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/queries/{query_id}/matches/{domain_id}/dismiss: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 - name: query_id in: path required: true schema: type: integer minimum: 0 - name: domain_id in: path required: true schema: type: integer minimum: 0 post: operationId: postAccountsAccountIdBrandProtectionQueriesQueryIdMatchesDomainIdDismiss summary: Dismiss a match for a saved string query description: Hide a matched domain from the default view of a saved query's results. Dismissal is scoped to the calling account. responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: queries.matches x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/queries/{query_id}/matches/{domain_id}/undismiss: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 - name: query_id in: path required: true schema: type: integer minimum: 0 - name: domain_id in: path required: true schema: type: integer minimum: 0 post: operationId: postAccountsAccountIdBrandProtectionQueriesQueryIdMatchesDomainIdUndismiss summary: Undismiss a match for a saved string query description: Restore a previously dismissed matched domain to the default view. Dismissal is scoped to the calling account. responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: queries.matches x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/queries/bulk: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 post: operationId: postAccountsAccountIdBrandProtectionQueriesBulk summary: Create new saved string queries in bulk description: Return a success message after creating new saved string queries in bulk requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_QueryBulk' responses: '204': description: No Content '422': $ref: '#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: queries.bulk x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/recent-submissions: get: operationId: getAccountsAccountIdBrandProtectionRecentSubmissions summary: Read recent URL submissions description: Return recent URL submissions responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: recent-submissions x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/refute: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 patch: operationId: patchAccountsAccountIdBrandProtectionRefute summary: Update verification statuses of submitted URLs to disproven by ID description: Return a success message after updating verification statuses of submitted URLs to disproven by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: refute x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/brand-protection/scan-logo: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 post: operationId: postAccountsAccountIdBrandProtectionScanLogo summary: Create new logo queries from image files description: Return new logo queries created from image files responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - logo_match x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: scan-logo x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/scan-page: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 post: operationId: postAccountsAccountIdBrandProtectionScanPage summary: Create new logo queries from URLs description: Return new logo queries created from URLs responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - logo_match x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: scan-page x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/search: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 post: operationId: postAccountsAccountIdBrandProtectionSearch summary: Create new string queries description: Return new string queries responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: search x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/submission-info: get: operationId: getAccountsAccountIdBrandProtectionSubmissionInfo summary: Read URL submissions by ID description: Return URL submissions based on ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: submission-info x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/submit: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 post: operationId: postAccountsAccountIdBrandProtectionSubmit summary: Create new URL submissions description: Return new URL submissions responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_URLSubmit' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: submit x-fern-sdk-method-name: create x-forge-hidden: true /accounts/{account_id}/brand-protection/total-queries: get: operationId: getAccountsAccountIdBrandProtectionTotalQueries summary: Read the total number of saved string queries description: Return the total number of saved string queries responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - domain_search x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: total-queries x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/tracked-domains: get: operationId: getAccountsAccountIdBrandProtectionTrackedDomains summary: Read submitted domains by pattern description: Return submitted domains based on pattern responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: tracked-domains x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/url-info: get: operationId: getAccountsAccountIdBrandProtectionUrlInfo summary: Read submitted URLs by ID description: Return submitted URLs based on ID responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/brand-protection-api_URLInfo' default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write - Intel Read x-fern-availability: generally-available x-fern-sdk-group-name: url-info x-fern-sdk-method-name: get x-forge-hidden: true parameters: - name: account_id in: path required: true schema: type: string minLength: 1 /accounts/{account_id}/brand-protection/verify: parameters: - name: account_id in: path required: true schema: type: string minLength: 1 patch: operationId: patchAccountsAccountIdBrandProtectionVerify summary: Update verification statuses of submitted URLs to confirmed by ID description: Return a success message after updating verification statuses of submitted URLs to confirmed by ID responses: default: $ref: '#/components/responses/brand-protection-api_DEFAULT_ERROR' security: - api_token: [] tags: - brand_protection x-api-token-group: - Intel Write x-fern-availability: generally-available x-fern-sdk-group-name: verify x-fern-sdk-method-name: edit x-forge-hidden: true /accounts/{account_id}/browser-extension/config: delete: operationId: accounts-browser-extension-config-delete summary: Delete browser extension configuration description: | Deletes the browser extension configuration for an account. The shard mapping is preserved and not deleted. responses: '200': description: Browser extension configuration deleted. content: application/json: schema: $ref: '#/components/schemas/brex_DeleteResponse' '400': $ref: '#/components/responses/brex_BadRequest' '401': $ref: '#/components/responses/brex_Unauthorized' '403': $ref: '#/components/responses/brex_Forbidden' '404': $ref: '#/components/responses/brex_NotFound' '500': $ref: '#/components/responses/brex_InternalServerError' security: - api_token: [] tags: - Browser Extension Config x-fern-availability: generally-available x-fern-sdk-group-name: browser-extension.config x-fern-sdk-method-name: delete get: operationId: accounts-browser-extension-config-get summary: Get browser extension configuration description: | Returns the browser extension configuration for an account. responses: '200': description: Browser extension configuration response. content: application/json: schema: $ref: '#/components/schemas/brex_ConfigResponse' '401': $ref: '#/components/responses/brex_Unauthorized' '403': $ref: '#/components/responses/brex_Forbidden' '404': $ref: '#/components/responses/brex_NotFound' '500': $ref: '#/components/responses/brex_InternalServerError' security: - api_token: [] tags: - Browser Extension Config x-fern-availability: generally-available x-fern-sdk-group-name: browser-extension.config x-fern-sdk-method-name: get 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/brex_CreateConfigRequest' responses: '200': description: Browser extension configuration created. content: application/json: schema: $ref: '#/components/schemas/brex_ConfigResponse' '400': $ref: '#/components/responses/brex_BadRequest' '401': $ref: '#/components/responses/brex_Unauthorized' '403': $ref: '#/components/responses/brex_Forbidden' '409': $ref: '#/components/responses/brex_Conflict' '500': $ref: '#/components/responses/brex_InternalServerError' security: - api_token: [] tags: - Browser Extension Config x-fern-availability: generally-available x-fern-sdk-group-name: browser-extension.config x-fern-sdk-method-name: create put: operationId: accounts-browser-extension-config-put summary: Update browser extension configuration description: | Replaces the browser extension configuration for an account. The configuration must already exist. The shard mapping is immutable. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/brex_UpdateConfigRequest' responses: '200': description: Browser extension configuration updated. content: application/json: schema: $ref: '#/components/schemas/brex_ConfigResponse' '400': $ref: '#/components/responses/brex_BadRequest' '401': $ref: '#/components/responses/brex_Unauthorized' '403': $ref: '#/components/responses/brex_Forbidden' '404': $ref: '#/components/responses/brex_NotFound' '500': $ref: '#/components/responses/brex_InternalServerError' security: - api_token: [] tags: - Browser Extension Config x-fern-availability: generally-available x-fern-sdk-group-name: browser-extension.config x-fern-sdk-method-name: update /accounts/{account_id}/browser-rendering/accessibilityTree: post: operationId: brapi-post_AccessibilityTree summary: Get accessibility tree page description: Returns the page's accessibility tree. Use `interestingOnly` to only return semantically meaningful nodes; use `root` to scope the tree to a CSS-selector-anchored subtree. Control page loading with `gotoOptions` and `waitFor*` options. parameters: - name: account_id in: path description: Account ID. required: true schema: description: Account ID. type: string - name: cacheTTL in: query description: Cache TTL default is 5s. Set to 0 to disable. schema: description: Cache TTL default is 5s. Set to 0 to disable. type: number default: 5 maximum: 86400 minimum: 0 requestBody: required: true content: application/json: examples: example1: value: url: https://www.example.com/ schema: type: object properties: actionTimeout: description: The maximum duration allowed for the browser action to complete after the page has loaded (such as taking screenshots, extracting content, or generating PDFs). If this time limit is exceeded, the action stops and returns a timeout error. type: number maximum: 120000 addScriptTag: description: Adds a `