# 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 Endpoints API
  version: 1.0.0
extends: openapi/convoy-endpoints-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/v1/projects/{projectID}/endpoints'].get
  update:
    x-apievangelist-phrasing:
      intent: List webhook endpoints in a project
      effect: read
      questions:
      - Which webhook endpoints are registered in my Convoy project?
      - Can I filter my endpoints by owner ID to see a fanout group?
      - Is there a way to search endpoints by name and page through the results?
      instructions:
      - text: List all endpoints in project {projectID}.
        slots:
          projectID: path.projectID
      - text: Find endpoints named {q} in project {projectID}.
        slots:
          q: query.q
          projectID: path.projectID
      - text: List the endpoints belonging to owner {ownerId}, {perPage} per page.
        slots:
          ownerId: query.ownerId
          perPage: query.perPage
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/endpoints'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new webhook endpoint
      effect: write
      questions:
      - How do I add a new HTTPS URL that should receive my webhooks?
      - Can I set a rate limit and HTTP timeout when registering an endpoint?
      - What happens if I don't supply a webhook secret for a new endpoint?
      instructions:
      - text: Create an endpoint named {name} pointing at {url} in project {projectID}.
        slots:
          name: requestBody.name
          url: requestBody.url
          projectID: path.projectID
      - text: Register a new endpoint for {url} with support email {support_email} and owner {owner_id}.
        slots:
          url: requestBody.url
          support_email: requestBody.support_email
          owner_id: requestBody.owner_id
      - text: Add a new endpoint at {url} limited to {rate_limit} requests with a {http_timeout} second timeout.
        slots:
          url: requestBody.url
          rate_limit: requestBody.rate_limit
          http_timeout: requestBody.http_timeout
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/endpoints/oauth2/test'].post
  update:
    x-apievangelist-phrasing:
      intent: Test an endpoint's OAuth2 token exchange
      effect: read
      questions:
      - Can I check that my OAuth2 client credentials work before attaching them to an endpoint?
      - Is there a way to verify Convoy can exchange a token with my OAuth2 server?
      instructions:
      - text: Test the OAuth2 connection {oauth2} for project {projectID}.
        slots:
          oauth2: requestBody.oauth2
          projectID: path.projectID
      - text: Try a token exchange with these OAuth2 settings {oauth2} and tell me if it succeeds.
        slots:
          oauth2: requestBody.oauth2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/endpoints/{endpointID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a webhook endpoint's details
      effect: read
      questions:
      - How do I look up the configuration of one specific endpoint?
      - What URL, status and rate limit is a given endpoint currently set to?
      instructions:
      - text: Get endpoint {endpointID} in project {projectID}.
        slots:
          endpointID: path.endpointID
          projectID: path.projectID
      - text: Show me the current settings of endpoint {endpointID}.
        slots:
          endpointID: path.endpointID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/endpoints/{endpointID}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing webhook endpoint
      effect: write
      questions:
      - Can I change the URL an existing endpoint delivers webhooks to?
      - How do I update the support email or Slack alert URL on an endpoint I already created?
      instructions:
      - text: Change the URL of endpoint {endpointID} in project {projectID} to {url}.
        slots:
          endpointID: path.endpointID
          projectID: path.projectID
          url: requestBody.url
      - text: Update existing endpoint {endpointID} to send failure alerts to {slack_webhook_url}.
        slots:
          endpointID: path.endpointID
          slack_webhook_url: requestBody.slack_webhook_url
      - text: Set the HTTP timeout on existing endpoint {endpointID} to {http_timeout} seconds.
        slots:
          endpointID: path.endpointID
          http_timeout: requestBody.http_timeout
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/endpoints/{endpointID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a webhook endpoint
      effect: destructive
      questions:
      - How do I permanently remove an endpoint that no longer needs webhooks?
      - Can I delete an endpoint rather than just pausing it?
      instructions:
      - text: Delete endpoint {endpointID} from project {projectID}.
        slots:
          endpointID: path.endpointID
          projectID: path.projectID
      - text: Remove endpoint {endpointID} permanently.
        slots:
          endpointID: path.endpointID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/endpoints/{endpointID}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Reactivate an inactive endpoint
      effect: write
      questions:
      - An endpoint was marked inactive after failures, how do I turn it back on?
      - Can I reactivate a disabled endpoint so it starts receiving webhooks again?
      instructions:
      - text: Activate inactive endpoint {endpointID} in project {projectID}.
        slots:
          endpointID: path.endpointID
          projectID: path.projectID
      - text: Bring endpoint {endpointID} back from inactive status.
        slots:
          endpointID: path.endpointID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/endpoints/{endpointID}/expire_secret'].put
  update:
    x-apievangelist-phrasing:
      intent: Roll an endpoint's signing secret
      effect: destructive
      questions:
      - How do I rotate the webhook signing secret for an endpoint?
      - Can I keep the old endpoint secret valid for a while after rolling a new one?
      instructions:
      - text: Roll the secret for endpoint {endpointID} in project {projectID}.
        slots:
          endpointID: path.endpointID
          projectID: path.projectID
      - text: Expire the old secret on endpoint {endpointID} after {expiration} and set the new secret to {secret}.
        slots:
          endpointID: path.endpointID
          expiration: requestBody.expiration
          secret: requestBody.secret
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/endpoints/{endpointID}/pause'].put
  update:
    x-apievangelist-phrasing:
      intent: Pause or unpause an endpoint
      effect: write
      questions:
      - Can I temporarily stop webhooks going to an endpoint during maintenance?
      - Is there a toggle to switch an endpoint between active and paused?
      instructions:
      - text: Pause endpoint {endpointID} in project {projectID}.
        slots:
          endpointID: path.endpointID
          projectID: path.projectID
      - text: Toggle the paused state of endpoint {endpointID} so deliveries resume.
        slots:
          endpointID: path.endpointID
      method: generated
      generated: '2026-10-01'