# 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 Subjects (v1) API
  version: 1.0.0
extends: openapi/confluent-subjects-v1-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: 10
- target: $.paths['/subjects/{subject}/versions/{version}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a schema version under a subject
      effect: read
      questions:
      - How do I fetch a specific version of a schema registered under a subject?
      - Can I retrieve a soft-deleted schema version too?
      instructions:
      - text: Get version {version} of the schema under subject {subject}.
        slots:
          version: path.version
          subject: path.subject
      - text: Fetch schema version {version} of subject {subject}, including deleted versions.
        slots:
          version: path.version
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions/{version}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a schema version from a subject
      effect: destructive
      questions:
      - Can I remove one version of a schema without deleting the whole subject?
      - What is the difference between a soft and a permanent delete of a schema version?
      instructions:
      - text: Delete version {version} of subject {subject}.
        slots:
          version: path.version
          subject: path.subject
      - text: Permanently delete schema version {version} from subject {subject}, permanent={permanent}.
        slots:
          version: path.version
          subject: path.subject
          permanent: query.permanent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions/{version}/referencedby'].get
  update:
    x-apievangelist-phrasing:
      intent: List schemas that reference a schema version
      effect: read
      questions:
      - Which other schemas reference this schema version?
      - Is anything still depending on a schema version before I delete it?
      instructions:
      - text: List the schema IDs that reference version {version} of subject {subject}.
        slots:
          version: path.version
          subject: path.subject
      - text: Show which schemas point to subject {subject} version {version}.
        slots:
          subject: path.subject
          version: path.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions/{version}/schema'].get
  update:
    x-apievangelist-phrasing:
      intent: Get only the raw schema string for a version
      effect: read
      questions:
      - How do I get just the unescaped schema text for a subject version, without metadata?
      - Can I pull the raw schema definition for one version to paste into my code?
      instructions:
      - text: Get the raw schema string for subject {subject} version {version}.
        slots:
          subject: path.subject
          version: path.version
      - text: Return only the schema text of version {version} under {subject}.
        slots:
          version: path.version
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions registered under a subject
      effect: read
      questions:
      - What versions exist for a subject in Schema Registry?
      - Can I list only the soft-deleted versions of a subject?
      instructions:
      - text: List the versions of subject {subject}.
        slots:
          subject: path.subject
      - text: Show only deleted versions under subject {subject}, deletedOnly={deletedOnly}.
        slots:
          subject: path.subject
          deletedOnly: query.deletedOnly
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new schema under a subject
      effect: write
      questions:
      - How do I register a new Avro or Protobuf schema under a subject?
      - Does registering a schema return its global schema ID?
      instructions:
      - text: Register this schema {schema} under subject {subject}.
        slots:
          schema: requestBody.schema
          subject: path.subject
      - text: Register a {schemaType} schema {schema} as a new version of {subject}.
        slots:
          schemaType: requestBody.schemaType
          schema: requestBody.schema
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}'].post
  update:
    x-apievangelist-phrasing:
      intent: Check if a schema is already registered
      effect: read
      questions:
      - Has this exact schema already been registered under my subject?
      - Can I find the version and ID of a schema I have in hand without registering it again?
      instructions:
      - text: Check whether schema {schema} is already registered under subject {subject}.
        slots:
          schema: requestBody.schema
          subject: path.subject
      - text: Look up the ID and version of schema {schema} in subject {subject}.
        slots:
          schema: requestBody.schema
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a subject and all its versions
      effect: destructive
      questions:
      - How do I delete a whole subject from Schema Registry when recycling a topic?
      - Does deleting a subject also remove its compatibility setting?
      instructions:
      - text: Delete subject {subject}.
        slots:
          subject: path.subject
      - text: Permanently delete subject {subject} and every version, permanent={permanent}.
        slots:
          subject: path.subject
          permanent: query.permanent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects'].get
  update:
    x-apievangelist-phrasing:
      intent: List subjects in Schema Registry
      effect: read
      questions:
      - What subjects are registered in my Schema Registry?
      - Can I list only subjects that start with a given prefix?
      instructions:
      - text: List all registered subjects.
      - text: List subjects starting with {subjectPrefix}.
        slots:
          subjectPrefix: query.subjectPrefix
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/metadata'].get
  update:
    x-apievangelist-phrasing:
      intent: Get latest schema version matching metadata
      effect: read
      questions:
      - Which is the newest schema version under a subject tagged with a given metadata key and value?
      - Can I find a schema version by its metadata instead of its version number?
      instructions:
      - text: Get the latest version of subject {subject} with metadata {key}={value}.
        slots:
          subject: path.subject
          key: query.key
          value: query.value
      - text: Find the newest schema in {subject} whose metadata {key} is {value}.
        slots:
          subject: path.subject
          key: query.key
          value: query.value
      method: generated
      generated: '2026-09-26'