# 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 Portal Links API
  version: 1.0.0
extends: openapi/convoy-portal-links-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: 6
- target: $.paths['/v1/projects/{projectID}/portal-links'].get
  update:
    x-apievangelist-phrasing:
      intent: List customer portal links
      effect: read
      questions:
      - Which customer portal links have I created in my project?
      - Can I filter portal links by owner ID?
      instructions:
      - text: List portal links in project {projectID}.
        slots:
          projectID: path.projectID
      - text: Show the portal links for owner {ownerId}.
        slots:
          ownerId: query.ownerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/portal-links'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a customer portal link
      effect: write
      questions:
      - How do I give a customer a portal where they can see their own webhooks?
      - Can a portal link let customers manage their own endpoints?
      instructions:
      - text: Create a portal link named {name} for owner {owner_id} in project {projectID}.
        slots:
          name: requestBody.name
          owner_id: requestBody.owner_id
          projectID: path.projectID
      - text: Create a portal link {name} with endpoint management set to {can_manage_endpoint}.
        slots:
          name: requestBody.name
          can_manage_endpoint: requestBody.can_manage_endpoint
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/portal-links/{portalLinkID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a portal link
      effect: read
      questions:
      - Where can I see the URL and settings of one portal link?
      - Can I look up a portal link by its ID?
      instructions:
      - text: Get portal link {portalLinkID} in project {projectID}.
        slots:
          portalLinkID: path.portalLinkID
          projectID: path.projectID
      - text: Show me portal link {portalLinkID}.
        slots:
          portalLinkID: path.portalLinkID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/portal-links/{portalLinkID}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a portal link
      effect: write
      questions:
      - How do I rename an existing portal link or point it at a different owner?
      - Can I turn endpoint management on or off for a portal link I already shared?
      instructions:
      - text: Rename portal link {portalLinkID} in project {projectID} to {name}.
        slots:
          portalLinkID: path.portalLinkID
          projectID: path.projectID
          name: requestBody.name
      - text: Change existing portal link {portalLinkID} to owner {owner_id}.
        slots:
          portalLinkID: path.portalLinkID
          owner_id: requestBody.owner_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/portal-links/{portalLinkID}/refresh_token'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a portal link auth token
      effect: read
      questions:
      - How do I get a fresh auth token for a customer portal link?
      - Can I refresh the token a portal link uses to sign in?
      instructions:
      - text: Get an auth token for portal link {portalLinkID} in project {projectID}.
        slots:
          portalLinkID: path.portalLinkID
          projectID: path.projectID
      - text: Refresh the auth token of portal link {portalLinkID}.
        slots:
          portalLinkID: path.portalLinkID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{projectID}/portal-links/{portalLinkID}/revoke'].put
  update:
    x-apievangelist-phrasing:
      intent: Revoke a portal link
      effect: destructive
      questions:
      - How do I cut off a customer's access to their webhook portal?
      - Can I revoke a portal link that was shared by mistake?
      instructions:
      - text: Revoke portal link {portalLinkID} in project {projectID}.
        slots:
          portalLinkID: path.portalLinkID
          projectID: path.projectID
      - text: Disable access through portal link {portalLinkID}.
        slots:
          portalLinkID: path.portalLinkID
      method: generated
      generated: '2026-10-01'