API Evangelist conversational phrasing for One Organizations API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for One Organizations API
  version: 1.0.0
extends: openapi/integration-os-organizations-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: 16
- target: $.paths['/v1/management/organizations/setup'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization with a service key
      effect: write
      questions:
      - How do I set up a new organization and get its service-account key in one step?
      - Can I name the API key that gets minted when I create an organization?
      instructions:
      - text: Set up a new organization called {name}.
        slots:
          name: requestBody.name
      - text: Create organization {name} and mint its service-account key named {key_name}.
        slots:
          name: requestBody.name
          key_name: requestBody.keyName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization's settings
      effect: read
      questions:
      - What members and projects does my organization have?
      - Where can I see an organization's current name and description?
      instructions:
      - text: Show the settings for organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Fetch org {org_id} with its members and projects.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe an organization
      effect: write
      questions:
      - How do I rename my organization?
      - Can I change an organization's description after setup?
      instructions:
      - text: Rename organization {org_id} to {name}.
        slots:
          org_id: path.org_id
          name: requestBody.name
      - text: Set org {org_id}'s description to {description}.
        slots:
          org_id: path.org_id
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an organization
      effect: destructive
      questions:
      - How do I delete an organization I no longer need?
      - Why does deleting my organization fail when it still has projects?
      instructions:
      - text: Delete organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Soft-delete org {org_id} now that its projects are gone.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/authkit'].put
  update:
    x-apievangelist-phrasing:
      intent: Configure organization-level embeddable auth
      effect: write
      questions:
      - How do I set up embeddable OAuth for a connector across my whole organization?
      - Can my organization use the default OAuth credentials instead of its own client?
      instructions:
      - text: Turn on embeddable auth for connector definition {connection_definition_id} in org {org_id}, {environment} environment, active {active}.
        slots:
          connection_definition_id: requestBody.connectionDefinitionId
          org_id: path.org_id
          environment: requestBody.environment
          active: requestBody.active
      - text: Set org {org_id}'s embeddable auth OAuth client id to {client_id} with scopes {scopes}.
        slots:
          org_id: path.org_id
          client_id: requestBody.clientId
          scopes: requestBody.scopes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/invitations'].get
  update:
    x-apievangelist-phrasing:
      intent: List pending organization invitations
      effect: read
      questions:
      - Who has been invited to my organization but not joined yet?
      - Can I see all outstanding org invites?
      instructions:
      - text: List pending invitations for organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Show who is still invited to org {org_id}.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/invitations'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite someone to an organization
      effect: write
      questions:
      - How do I invite a teammate to my organization by email?
      - Can I set a role and expiry on an organization invite?
      instructions:
      - text: Invite {email} to organization {org_id}.
        slots:
          email: requestBody.email
          org_id: path.org_id
      - text: Invite {email} to org {org_id} with role {role_key}, expiring {expires_at}.
        slots:
          email: requestBody.email
          org_id: path.org_id
          role_key: requestBody.roleKey
          expires_at: requestBody.expiresAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/invitations/{invitation_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an organization invitation
      effect: destructive
      questions:
      - How do I cancel an invitation to my organization before it is accepted?
      - Can I withdraw a project invite from the organization level?
      instructions:
      - text: Revoke invitation {invitation_id} in organization {org_id}.
        slots:
          invitation_id: path.invitation_id
          org_id: path.org_id
      - text: Cancel pending invite {invitation_id} under org {org_id}.
        slots:
          invitation_id: path.invitation_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/invitations/{invitation_id}/resend'].post
  update:
    x-apievangelist-phrasing:
      intent: Resend an organization invitation
      effect: write
      questions:
      - Can I resend an organization invite email that someone missed?
      - Does resending an invite issue a new token?
      instructions:
      - text: Resend invitation {invitation_id} for organization {org_id}.
        slots:
          invitation_id: path.invitation_id
          org_id: path.org_id
      - text: Rotate the token on org {org_id}'s invite {invitation_id} and email it again.
        slots:
          invitation_id: path.invitation_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's API keys
      effect: read
      questions:
      - Which API keys are scoped to my organization?
      - Does the organization key list include the service-account key?
      instructions:
      - text: List API keys for organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Show every org-scoped key in org {org_id} for this environment.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization API key
      effect: write
      questions:
      - How do I mint an extra API key for my organization?
      - Can I give a new org-scoped key a name?
      instructions:
      - text: Create a new API key for organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Mint an org-scoped key named {name} in org {org_id}.
        slots:
          name: requestBody.name
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/keys/{key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an organization API key
      effect: destructive
      questions:
      - How do I revoke an organization API key I created?
      - Can I delete the organization's service-account key this way?
      instructions:
      - text: Delete API key {key_id} from organization {org_id}.
        slots:
          key_id: path.key_id
          org_id: path.org_id
      - text: Revoke org {org_id}'s key {key_id}.
        slots:
          key_id: path.key_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/keys/{key_id}/configure'].put
  update:
    x-apievangelist-phrasing:
      intent: Set passthrough rules on an org key
      effect: write
      questions:
      - Can I restrict which passthrough methods an organization key may call?
      - How do I replace the access rules on an org-scoped API key?
      instructions:
      - text: Limit organization key {key_id} in org {org_id} to methods {methods}.
        slots:
          key_id: path.key_id
          org_id: path.org_id
          methods: requestBody.methods
      - text: Replace the passthrough rules on org {org_id}'s key {key_id} with {rules}.
        slots:
          key_id: path.key_id
          org_id: path.org_id
          rules: requestBody.rules
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List organization members
      effect: read
      questions:
      - Who belongs to my organization?
      - Can I page through every user in an org?
      instructions:
      - text: List members of organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Show all users in org {org_id}.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/members'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a member's organization role
      effect: write
      questions:
      - How do I promote a user to a different role in my organization?
      - Can I change someone's org-level role without removing them?
      instructions:
      - text: Give user {user_id} the role {role_key} in organization {org_id}.
        slots:
          user_id: requestBody.userId
          role_key: requestBody.roleKey
          org_id: path.org_id
      - text: Change {user_id}'s org {org_id} role to {role_key}.
        slots:
          user_id: requestBody.userId
          role_key: requestBody.roleKey
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/management/organizations/{org_id}/members/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a member from an organization
      effect: destructive
      questions:
      - How do I remove someone from my organization?
      - Does removing an org member delete their user account?
      instructions:
      - text: Remove user {user_id} from organization {org_id}.
        slots:
          user_id: path.user_id
          org_id: path.org_id
      - text: Take {user_id} out of org {org_id} but keep their account.
        slots:
          user_id: path.user_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'