# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Svix Sink API
  version: 1.0.0
extends: openapi/svix-sink-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: 16
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/last-acked-event'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the last event a sink acknowledged
      effect: read
      questions:
      - How far has my stream sink gotten — what's the last event it acked?
      - Can I see the most recent acknowledged event for a sink?
      instructions:
      - text: Get the last acked event for sink {sink_id} on stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Show where sink {sink_id} in stream {stream_id} last acknowledged.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/next-event'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a sink's oldest unacknowledged event
      effect: read
      questions:
      - What's the next event my sink hasn't acked yet?
      - Which is the oldest pending event waiting on a stream sink?
      instructions:
      - text: Get the next unacked event for sink {sink_id} on stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Show the oldest event stream {stream_id} sink {sink_id} still has to acknowledge.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink'].get
  update:
    x-apievangelist-phrasing:
      intent: List a stream's sinks
      effect: read
      questions:
      - Which sinks are attached to my stream?
      - Can I page through all the destinations a stream delivers to?
      instructions:
      - text: List all sinks on stream {stream_id}.
        slots:
          stream_id: path.stream_id
      - text: Show the first {limit} sinks for stream {stream_id}.
        slots:
          limit: query.limit
          stream_id: path.stream_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a sink on a stream
      effect: write
      questions:
      - How do I add a new sink to a Svix stream?
      - Can a new sink receive only certain event types and batch them?
      instructions:
      - text: Create a new sink on stream {stream_id}.
        slots:
          stream_id: path.stream_id
      - text: Add a sink to stream {stream_id} for event types {eventTypes} with batch size {batchSize}.
        slots:
          stream_id: path.stream_id
          eventTypes: requestBody.eventTypes
          batchSize: requestBody.batchSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a sink's configuration
      effect: read
      questions:
      - What is the configuration of a specific sink on my stream?
      - Can I look up a sink by its uid instead of its id?
      instructions:
      - text: Get sink {sink_id} on stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Show the settings for stream {stream_id}'s sink {sink_id}.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or fully replace a sink
      effect: write
      questions:
      - How do I upsert a sink so it's created if it doesn't exist yet?
      - Can I replace a sink's whole configuration in one call?
      instructions:
      - text: Upsert sink {sink_id} on stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Replace sink {sink_id} on {stream_id} with status {status} and max wait {maxWaitSecs} seconds.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
          status: requestBody.status
          maxWaitSecs: requestBody.maxWaitSecs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a sink
      effect: destructive
      questions:
      - How do I remove a sink from a stream?
      - What happens to a stream when I delete one of its sinks?
      instructions:
      - text: Delete sink {sink_id} from stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Remove stream {stream_id}'s sink {sink_id} permanently.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a sink
      effect: write
      questions:
      - How do I pause a sink by changing just its status?
      - Can I tweak a sink's batch size without resending its full config?
      instructions:
      - text: Set sink {sink_id} on stream {stream_id} to status {status}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
          status: requestBody.status
      - text: Patch only the batch size of sink {sink_id} in {stream_id} to {batchSize}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
          batchSize: requestBody.batchSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/transformation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a sink's transformation code
      effect: read
      questions:
      - What transformation code is running on my sink?
      - Can I read back the script that reshapes events before a sink delivers them?
      instructions:
      - text: Get the transformation code for sink {sink_id} on stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Show stream {stream_id} sink {sink_id}'s transformation.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/transformation'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set or clear a sink's transformation code
      effect: write
      questions:
      - How do I attach transformation code to a stream sink?
      - Can I remove a sink's transformation so events pass through unchanged?
      instructions:
      - text: Set the transformation on sink {sink_id} in stream {stream_id} to {code}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
          code: requestBody.code
      - text: Unset the transformation code on stream {stream_id} sink {sink_id}.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/secret'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an HTTP sink's signing secret
      effect: read
      questions:
      - Where do I find the signing secret to verify deliveries from an HTTP sink?
      - Does every sink type have a signing secret?
      instructions:
      - text: Get the signing secret for HTTP sink {sink_id} on stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Show stream {stream_id} sink {sink_id}'s secret so I can verify its deliveries.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/secret/rotate'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate an HTTP sink's signing secret
      effect: write
      questions:
      - How do I rotate the signing secret on an HTTP stream sink?
      - Can the old sink secret stay valid for a grace period after rotation?
      instructions:
      - text: Rotate the signing secret for sink {sink_id} on stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Rotate stream {stream_id} sink {sink_id}'s secret with a {gracePeriodSeconds}-second grace period.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
          gracePeriodSeconds: requestBody.gracePeriodSeconds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/headers'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the HTTP headers a sink sends
      effect: read
      questions:
      - Which custom HTTP headers does my sink send with deliveries?
      - Can I view headers configured on an OpenTelemetry tracing sink?
      instructions:
      - text: Get the headers for sink {sink_id} on stream {stream_id}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Show the custom headers stream {stream_id} sink {sink_id} is sending.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/headers'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update the HTTP headers a sink sends
      effect: write
      questions:
      - How do I add an auth header to every delivery from an HTTP sink?
      - Can I change headers on a sink that isn't http or otelTracing?
      instructions:
      - text: Update sink {sink_id} on stream {stream_id} to send headers {headers}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
          headers: requestBody.headers
      - text: Patch stream {stream_id} sink {sink_id}'s headers with {headers}.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
          headers: requestBody.headers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/force-retry'].post
  update:
    x-apievangelist-phrasing:
      intent: Force a retrying sink to dispatch now
      effect: write
      questions:
      - My sink is backing off after failures — can I make it retry right away?
      - How do I skip the wait on a sink that's currently retrying?
      instructions:
      - text: Force sink {sink_id} on stream {stream_id} to retry immediately.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
      - text: Kick stream {stream_id} sink {sink_id} out of its retry backoff now.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/{stream_id}/sink/{sink_id}/skip'].post
  update:
    x-apievangelist-phrasing:
      intent: Skip a sink ahead past a given event
      effect: destructive
      questions:
      - How do I make a sink skip events it's stuck on?
      - Can I move a sink's position to just after a specific iterator?
      instructions:
      - text: Skip sink {sink_id} on stream {stream_id} to after iterator {iterator}.
        slots:
          sink_id: path.sink_id
          stream_id: path.stream_id
          iterator: requestBody.iterator
      - text: Move stream {stream_id} sink {sink_id}'s consumer position past {iterator}, dropping earlier events.
        slots:
          stream_id: path.stream_id
          sink_id: path.sink_id
          iterator: requestBody.iterator
      method: generated
      generated: '2026-09-26'