# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Convoy API Reference Subscriptions API
  version: 1.0.0
extends: openapi/convoy-subscriptions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/v1/projects/{projectID}/sources/test_function'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a source's transform function on a payload
      effect: read
      questions:
      - Can I dry-run the function attached to an incoming source before I save that source?
      - What does an ingest source's function produce from a sample webhook body?
      instructions:
      - text: Test source function {function} of type {type} against sample payload {payload} in project {projectID}.
        slots:
          function: requestBody.function
          type: requestBody.type
          payload: requestBody.payload
          projectID: path.projectID
      - text: Dry-run my incoming source's function {function} in project {projectID} before saving the source.
        slots:
          function: requestBody.function
          projectID: path.projectID
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v1/projects/{projectID}/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List subscriptions
      effect: read
      questions:
      - Which subscriptions route events to my endpoints?
      - Can I list subscriptions for a particular endpoint or search by name?
      instructions:
      - text: List subscriptions in project {projectID}.
        slots:
          projectID: path.projectID
      - text: Show the subscriptions attached to endpoint {endpointId}.
        slots:
          endpointId: query.endpointId
      - text: Find subscriptions named {name}.
        slots:
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe an endpoint to events
      effect: write
      questions:
      - How do I connect an endpoint so it starts receiving events?
      - Can I link a source to an endpoint with its own filter and rate limit?
      instructions:
      - text: Create subscription {name} for endpoint {endpoint_id} in project {projectID}.
        slots:
          name: requestBody.name
          endpoint_id: requestBody.endpoint_id
          projectID: path.projectID
      - text: Subscribe endpoint {endpoint_id} to source {source_id}.
        slots:
          endpoint_id: requestBody.endpoint_id
          source_id: requestBody.source_id
      - text: Create a subscription for endpoint {endpoint_id} with filter config {filter_config}.
        slots:
          endpoint_id: requestBody.endpoint_id
          filter_config: requestBody.filter_config
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/subscriptions/test_filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a filter schema against a sample request
      effect: read
      questions:
      - Before saving a subscription, would my filter schema match this request?
      - Can I check a draft filter schema against sample headers and body?
      instructions:
      - text: Validate filter schema {schema} against request {request} in project {projectID}.
        slots:
          schema: requestBody.schema
          request: requestBody.request
          projectID: path.projectID
      - text: Check whether my draft filter {schema} matches this sample request {request}.
        slots:
          schema: requestBody.schema
          request: requestBody.request
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/subscriptions/test_function'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a payload transform function
      effect: read
      questions:
      - Can I try my JavaScript transform function on a sample payload first?
      - What will my payload look like after a subscription function mutates it?
      instructions:
      - text: Run transform function {function} against payload {payload} in project {projectID}.
        slots:
          function: requestBody.function
          payload: requestBody.payload
          projectID: path.projectID
      - text: Test-run this transform {function} on a sample payload and show the output.
        slots:
          function: requestBody.function
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/subscriptions/{subscriptionID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a subscription
      effect: read
      questions:
      - What endpoint, source and filter does one subscription use?
      - Can I look up a single subscription by its ID?
      instructions:
      - text: Get subscription {subscriptionID} in project {projectID}.
        slots:
          subscriptionID: path.subscriptionID
          projectID: path.projectID
      - text: Show me the settings of subscription {subscriptionID}.
        slots:
          subscriptionID: path.subscriptionID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/subscriptions/{subscriptionID}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a subscription
      effect: write
      questions:
      - How do I change the retry policy on an existing subscription?
      - Can I point a subscription I already have at a different endpoint?
      instructions:
      - text: Set retry config {retry_config} on subscription {subscriptionID} in project {projectID}.
        slots:
          retry_config: requestBody.retry_config
          subscriptionID: path.subscriptionID
          projectID: path.projectID
      - text: Move existing subscription {subscriptionID} to endpoint {endpoint_id}.
        slots:
          subscriptionID: path.subscriptionID
          endpoint_id: requestBody.endpoint_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/subscriptions/{subscriptionID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a subscription
      effect: destructive
      questions:
      - How do I stop an endpoint from receiving events by removing its subscription?
      - Can I delete a subscription without deleting the endpoint?
      instructions:
      - text: Delete subscription {subscriptionID} from project {projectID}.
        slots:
          subscriptionID: path.subscriptionID
          projectID: path.projectID
      - text: Remove subscription {subscriptionID}.
        slots:
          subscriptionID: path.subscriptionID
      method: generated
      generated: '2026-10-01'