# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Snyk Orgs API
  version: 1.0.0
extends: openapi/snyk-orgs-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: 8
- target: $.paths['/groups/{group_id}/orgs'].get
  update:
    x-apievangelist-phrasing:
      intent: List the organizations in a group
      effect: read
      questions:
      - Which organizations belong to my Snyk group?
      - Can I find an organization in a group by its name or slug?
      instructions:
      - text: List all organizations in group {group_id}.
        slots:
          group_id: path.group_id
      - text: Find organizations in group {group_id} named {name}.
        slots:
          group_id: path.group_id
          name: query.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs'].get
  update:
    x-apievangelist-phrasing:
      intent: List organizations I can access
      effect: read
      questions:
      - Which organizations do I have access to?
      - Can I list only my personal organizations?
      instructions:
      - text: List every organization I can access.
      - text: List my accessible organizations with slug {slug}.
        slots:
          slug: query.slug
      - text: Show my accessible orgs where personal is {is_personal}.
        slots:
          is_personal: query.is_personal
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization's details
      effect: read
      questions:
      - What are the full details of one of my organizations?
      - Can I expand related data when fetching a single organization?
      instructions:
      - text: Get the details of organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Show organization {org_id} with {expand} expanded.
        slots:
          org_id: path.org_id
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an organization's details
      effect: write
      questions:
      - How do I rename an organization?
      - Can I edit an organization's details through the API?
      instructions:
      - text: Update the details of organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Rename organization {org_id} to our new team name.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/memberships'].get
  update:
    x-apievangelist-phrasing:
      intent: List memberships in an organization
      effect: read
      questions:
      - Who belongs to my organization and with what role?
      - Can I search an org's members by username or email?
      instructions:
      - text: List all memberships of organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Find org {org_id} members with email {email}.
        slots:
          org_id: path.org_id
          email: query.email
      - text: List org {org_id} members holding role {role_name}.
        slots:
          org_id: path.org_id
          role_name: query.role_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/memberships'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a user to an organization with a role
      effect: write
      questions:
      - Can I add an existing user straight into an organization with a role, without an invite?
      - What do I send to create an org membership?
      instructions:
      - text: Add this user to organization {org_id} as a collaborator.
        slots:
          org_id: path.org_id
      - text: Create an org membership in {org_id} for a user and role.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/memberships/{membership_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user's organization membership
      effect: destructive
      questions:
      - Can I remove someone from my organization?
      - What revokes a user's access to one org?
      instructions:
      - text: Remove membership {membership_id} from organization {org_id}.
        slots:
          membership_id: path.membership_id
          org_id: path.org_id
      - text: Delete org {org_id} membership {membership_id}.
        slots:
          org_id: path.org_id
          membership_id: path.membership_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{org_id}/memberships/{membership_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a user's role in an organization
      effect: write
      questions:
      - Can I change the role on an existing org membership?
      - How do I make an org collaborator an admin?
      instructions:
      - text: Update the role on membership {membership_id} in organization {org_id}.
        slots:
          membership_id: path.membership_id
          org_id: path.org_id
      - text: Promote org {org_id} member {membership_id} to admin.
        slots:
          org_id: path.org_id
          membership_id: path.membership_id
      method: generated
      generated: '2026-09-26'