# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Twilio Compositions API
  version: 1.0.0
extends: openapi/twilio-compositions-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['/Compositions'].get
  update:
    x-apievangelist-phrasing:
      intent: List compositions (legacy unversioned endpoint)
      effect: read
      questions:
      - Using the older unversioned compositions path, which video compositions are still processing?
      - Can the legacy compositions list be narrowed to one video room?
      instructions:
      - text: Via the legacy unversioned endpoint, list compositions with status {status}.
        slots:
          status: query.Status
      - text: Via the legacy unversioned endpoint, list compositions made from room {room}.
        slots:
          room: query.RoomSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Compositions'].post
  update:
    x-apievangelist-phrasing:
      intent: Compose room recordings (legacy unversioned endpoint)
      effect: write
      questions:
      - On the older unversioned endpoint, how do I merge a room's recordings into one media file?
      - Can the legacy create endpoint set a layout and resolution like 1280x720?
      instructions:
      - text: Via the legacy unversioned endpoint, compose the recordings of room {room}.
        slots:
          room: requestBody.RoomSid
      - text: Via the legacy unversioned endpoint, compose room {room} at {resolution} in {format}.
        slots:
          room: requestBody.RoomSid
          resolution: requestBody.Resolution
          format: requestBody.Format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Compositions/{CompositionSid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a composition (legacy unversioned endpoint)
      effect: read
      questions:
      - Through the older unversioned path, what is the status of one composition?
      - Can I fetch a single composition from the legacy endpoint?
      instructions:
      - text: Via the legacy unversioned endpoint, get composition {composition}.
        slots:
          composition: path.CompositionSid
      - text: Using the older unversioned path, show composition {composition}.
        slots:
          composition: path.CompositionSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Compositions/{CompositionSid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a composition (legacy unversioned endpoint)
      effect: destructive
      questions:
      - Through the older unversioned path, how do I delete a composition?
      - Can the legacy endpoint remove a composition I no longer need?
      instructions:
      - text: Via the legacy unversioned endpoint, delete composition {composition}.
        slots:
          composition: path.CompositionSid
      - text: Using the older unversioned path, remove composition {composition}.
        slots:
          composition: path.CompositionSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/CompositionSettings/Default'].get
  update:
    x-apievangelist-phrasing:
      intent: Read default composition storage settings
      effect: read
      questions:
      - Where are my compositions being stored by default, and is encryption on?
      - Which S3 bucket and AWS credentials do my composition settings point to?
      instructions:
      - text: Show my default composition settings.
      - text: Check whether external S3 storage and encryption are enabled for compositions.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/CompositionSettings/Default'].post
  update:
    x-apievangelist-phrasing:
      intent: Configure where compositions are stored
      effect: write
      questions:
      - How do I send finished compositions to my own S3 bucket?
      - Can I turn on encryption for stored compositions with my own key?
      instructions:
      - text: Save composition settings {name} storing to {s3_url} with AWS credentials {aws_credentials}.
        slots:
          name: requestBody.FriendlyName
          s3_url: requestBody.AwsS3Url
          aws_credentials: requestBody.AwsCredentialsSid
      - text: Set composition settings {name} to encrypt with key {encryption_key}.
        slots:
          name: requestBody.FriendlyName
          encryption_key: requestBody.EncryptionKeySid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Compositions/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a recording composition
      effect: read
      questions:
      - What is the status and duration of a specific recording composition?
      - Is a given v1 composition finished and ready to download?
      instructions:
      - text: Get v1 composition {composition}.
        slots:
          composition: path.Sid
      - text: Show the details of recording composition {composition} from the v1 API.
        slots:
          composition: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Compositions/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a recording composition
      effect: destructive
      questions:
      - How do I permanently delete a v1 recording composition?
      - Can I free storage by removing a composition I have already downloaded?
      instructions:
      - text: Delete v1 composition {composition}.
        slots:
          composition: path.Sid
      - text: Permanently remove recording composition {composition} using the v1 API.
        slots:
          composition: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Compositions'].get
  update:
    x-apievangelist-phrasing:
      intent: List recording compositions
      effect: read
      questions:
      - Which compositions were created in a given date range?
      - What recording compositions exist for one room, filtered by status?
      instructions:
      - text: List v1 compositions created after {after} and before {before}.
        slots:
          after: query.DateCreatedAfter
          before: query.DateCreatedBefore
      - text: List v1 compositions for room {room} with status {status}.
        slots:
          room: query.RoomSid
          status: query.Status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Compositions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a recording composition
      effect: write
      questions:
      - With the v1 API, how do I turn a video room's recordings into a single file?
      - Is it possible to exclude certain audio tracks from a v1 composition?
      instructions:
      - text: Create a v1 composition of room {room}.
        slots:
          room: requestBody.RoomSid
      - text: Create a v1 composition of room {room} in {format}, notifying {callback_url} when done.
        slots:
          room: requestBody.RoomSid
          format: requestBody.Format
          callback_url: requestBody.StatusCallback
      - text: Compose room {room} with the v1 API, leaving out audio sources {excluded}.
        slots:
          room: requestBody.RoomSid
          excluded: requestBody.AudioSourcesExcluded
      method: generated
      generated: '2026-09-26'