# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Confluent Cloud ACL (v3) API
  version: 1.0.0
extends: openapi/confluent-acl-v3-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 4
- target: $.paths['/kafka/v3/clusters/{cluster_id}/acls:batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many Kafka ACLs in one request
      effect: write
      questions:
      - Can I create several ACLs in a single call instead of one at a time?
      - How do I bulk-grant permissions on a Kafka cluster?
      instructions:
      - text: Create these ACLs {data} on cluster {cluster_id} in one batch.
        slots:
          data: requestBody.data
          cluster_id: path.cluster_id
      - text: Batch-add the ACL entries {data} to Kafka cluster {cluster_id}.
        slots:
          data: requestBody.data
          cluster_id: path.cluster_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/kafka/v3/clusters/{cluster_id}/acls'].get
  update:
    x-apievangelist-phrasing:
      intent: List Kafka ACLs matching a filter
      effect: read
      questions:
      - Which ACLs grant access to a given topic?
      - What permissions does a particular service account principal have on my cluster?
      - Why do service accounts show as numeric User IDs in ACL results?
      instructions:
      - text: List ACLs on cluster {cluster_id} for principal {principal}.
        slots:
          cluster_id: path.cluster_id
          principal: query.principal
      - text: Show ACLs on cluster {cluster_id} for {resource_type} {resource_name}.
        slots:
          cluster_id: path.cluster_id
          resource_type: query.resource_type
          resource_name: query.resource_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/kafka/v3/clusters/{cluster_id}/acls'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a single Kafka ACL
      effect: write
      questions:
      - How do I give a service account read access to one topic?
      - Can I create an ACL that applies to a topic prefix?
      instructions:
      - text: Create an ACL on cluster {cluster_id} allowing {principal} to {operation} on {resource_type} {resource_name}.
        slots:
          cluster_id: path.cluster_id
          principal: requestBody.principal
          operation: requestBody.operation
          resource_type: requestBody.resource_type
          resource_name: requestBody.resource_name
      - text: 'Add a {permission} ACL: {principal} may {operation} on {resource_type} {resource_name} ({pattern_type}) from {host} in {cluster_id}.'
        slots:
          permission: requestBody.permission
          principal: requestBody.principal
          resource_type: requestBody.resource_type
          resource_name: requestBody.resource_name
          pattern_type: requestBody.pattern_type
          host: requestBody.host
          operation: requestBody.operation
          cluster_id: path.cluster_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/kafka/v3/clusters/{cluster_id}/acls'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete Kafka ACLs matching a filter
      effect: destructive
      questions:
      - How do I revoke ACLs that match certain criteria?
      - Can one call delete every ACL for a resource type and operation?
      instructions:
      - text: Delete {permission} ACLs for {operation} on {resource_type} with pattern {pattern_type} in cluster {cluster_id}.
        slots:
          permission: query.permission
          operation: query.operation
          resource_type: query.resource_type
          pattern_type: query.pattern_type
          cluster_id: path.cluster_id
      - text: Revoke ACLs for principal {principal} matching {resource_type}, {pattern_type}, {operation}, {permission} on cluster {cluster_id}.
        slots:
          principal: query.principal
          resource_type: query.resource_type
          pattern_type: query.pattern_type
          operation: query.operation
          permission: query.permission
          cluster_id: path.cluster_id
      method: generated
      generated: '2026-09-26'