# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for One Link API
  version: 1.0.0
extends: openapi/integration-os-link-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: 5
- target: $.paths['/v1/link/connections'].get
  update:
    x-apievangelist-phrasing:
      intent: List connections made through Link
      effect: read
      questions:
      - Which connections have my end users created through the Link flow?
      - Can I page through Link connections a set number at a time?
      instructions:
      - text: List the connections created through Link.
      - text: Show page {page} of Link connections, {limit} per page.
        slots:
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/link/init'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a Link session to connect an account
      effect: write
      questions:
      - How do I start the Link flow so an end user can connect their account?
      - Can I attach an identity and tags to a Link session when I start it?
      instructions:
      - text: Start a Link session for identity {identity}.
        slots:
          identity: requestBody.identity
      - text: Initialize a Link connection labelled {label} for {identity} with tags {tags}.
        slots:
          label: requestBody.label
          identity: requestBody.identity
          tags: requestBody.tags
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/link/organizations/{org_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization's Link
      effect: read
      questions:
      - What are the settings of a specific Link in my organization?
      - Can I look up one organization Link by its ID?
      instructions:
      - text: Get Link {id} in organization {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Show the details of organization {org_id}'s Link {id}.
        slots:
          org_id: path.org_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/link/organizations/{org_id}/{id}/rotate'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate an organization's Link
      effect: write
      questions:
      - How do I rotate a Link if I think it has been shared too widely?
      - Can I issue a fresh Link to replace the current one for my organization?
      instructions:
      - text: Rotate Link {id} in organization {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Replace organization {org_id}'s Link {id} with a newly rotated one.
        slots:
          org_id: path.org_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/link/resolve'].get
  update:
    x-apievangelist-phrasing:
      intent: Resolve the Link for the current caller
      effect: read
      questions:
      - Which Link applies to the credential I'm calling with?
      - Can I resolve the active Link without knowing its ID?
      instructions:
      - text: Resolve the Link for my current credential.
      - text: Look up which Link my key resolves to.
      method: generated
      generated: '2026-10-01'