# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Things Stack — Identity Server Organization Registry API
  version: 1.0.0
extends: openapi/the-things-network-organizationregistry-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['/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List organizations I can access
      effect: read
      questions:
      - Which organizations do I belong to?
      - Can I include deleted organizations in the list?
      instructions:
      - text: List all organizations I have access to.
      - text: List organizations with deleted set to {deleted}.
        slots:
          deleted: query.deleted
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization.ids.organization_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an organization
      effect: write
      questions:
      - How do I rename my organization or change its description?
      - Can I update only selected fields of an organization?
      instructions:
      - text: Update organization {organization_id} with {organization}.
        slots:
          organization_id: path.organization.ids.organization_id
          organization: requestBody.organization
      - text: Change fields {field_mask} on organization {organization_id}.
        slots:
          field_mask: requestBody.field_mask
          organization_id: path.organization.ids.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_ids.organization_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization
      effect: read
      questions:
      - What details are stored for my organization?
      - Can I choose which organization fields to return?
      instructions:
      - text: Show organization {organization_id}.
        slots:
          organization_id: path.organization_ids.organization_id
      - text: Get fields {field_mask} of organization {organization_id}.
        slots:
          field_mask: query.field_mask
          organization_id: path.organization_ids.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an organization (restorable)
      effect: destructive
      questions:
      - What happens when I delete an organization; can I get it back?
      - Does deleting an organization free its ID?
      instructions:
      - text: Delete organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Soft-delete organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/purge'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently purge an organization
      effect: destructive
      questions:
      - How do I permanently remove an organization so its ID can be reused?
      - Is purging an organization irreversible?
      instructions:
      - text: Purge organization {organization_id} permanently.
        slots:
          organization_id: path.organization_id
      - text: Release the ID of organization {organization_id} by purging it.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a recently deleted organization
      effect: write
      questions:
      - Can I bring back an organization I just deleted?
      - How long after deletion can an organization be restored?
      instructions:
      - text: Restore deleted organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Undo the deletion of organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{collaborator.user_ids.user_id}/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's organizations
      effect: read
      questions:
      - Which organizations is a specific user a direct member of?
      - Can I list organizations for a user ID?
      instructions:
      - text: List organizations of user {user_id}.
        slots:
          user_id: path.collaborator.user_ids.user_id
      - text: Show {limit} organizations per page for user {user_id}.
        slots:
          limit: query.limit
          user_id: path.collaborator.user_ids.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{collaborator.user_ids.user_id}/organizations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization
      effect: write
      questions:
      - How do I create a new organization on The Things Stack?
      - Does the creating user become an organization collaborator with full rights?
      instructions:
      - text: Create organization {organization} owned by user {user_id}.
        slots:
          organization: requestBody.organization
          user_id: path.collaborator.user_ids.user_id
      - text: Set up a new organization for user {user_id}.
        slots:
          user_id: path.collaborator.user_ids.user_id
      method: generated
      generated: '2026-09-26'