# 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 Client Registry API
  version: 1.0.0
extends: openapi/the-things-network-clientregistry-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: 10
- target: $.paths['/clients'].get
  update:
    x-apievangelist-phrasing:
      intent: List OAuth clients I can access
      effect: read
      questions:
      - Which OAuth clients are registered that I have access to on The Things Stack?
      - Can I include deleted OAuth clients when I list them?
      instructions:
      - text: List all OAuth clients I can access.
      - text: List OAuth clients where user {user_id} is a direct collaborator.
        slots:
          user_id: query.collaborator.user_ids.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/clients/{client.ids.client_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an OAuth client
      effect: write
      questions:
      - How do I change the redirect URIs or name of an OAuth client?
      - Can I update just some fields of an OAuth client with a field mask?
      instructions:
      - text: Update OAuth client {client_id} with the fields in {field_mask}.
        slots:
          client_id: path.client.ids.client_id
          field_mask: requestBody.field_mask
      - text: Change OAuth client {client_id} to {client}.
        slots:
          client_id: path.client.ids.client_id
          client: requestBody.client
      method: generated
      generated: '2026-09-26'
- target: $.paths['/clients/{client_ids.client_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an OAuth client
      effect: read
      questions:
      - What is configured on a specific OAuth client?
      - Can I fetch one OAuth client with only selected fields?
      instructions:
      - text: Show OAuth client {client_id}.
        slots:
          client_id: path.client_ids.client_id
      - text: Get only the {field_mask} of OAuth client {client_id}.
        slots:
          field_mask: query.field_mask
          client_id: path.client_ids.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/clients/{client_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an OAuth client
      effect: destructive
      questions:
      - How do I delete an OAuth client I no longer need?
      - Does deleting an OAuth client make its ID available again?
      instructions:
      - text: Delete OAuth client {client_id}.
        slots:
          client_id: path.client_id
      - text: Soft-delete OAuth client {client_id}.
        slots:
          client_id: path.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/clients/{client_id}/purge'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently purge an OAuth client
      effect: destructive
      questions:
      - How do I purge an OAuth client so its client ID is released?
      - Is purging an OAuth client reversible?
      instructions:
      - text: Purge OAuth client {client_id} permanently.
        slots:
          client_id: path.client_id
      - text: Release client ID {client_id} for reuse by purging it.
        slots:
          client_id: path.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/clients/{client_id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a deleted OAuth client
      effect: write
      questions:
      - Can I restore an OAuth client that was recently deleted?
      - Is there a time window for recovering a deleted OAuth client?
      instructions:
      - text: Restore deleted OAuth client {client_id}.
        slots:
          client_id: path.client_id
      - text: Undelete OAuth client {client_id}.
        slots:
          client_id: path.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{collaborator.organization_ids.organization_id}/clients'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's OAuth clients
      effect: read
      questions:
      - Which OAuth clients does an organization collaborate on?
      - Can I page through an organization's OAuth clients?
      instructions:
      - text: List OAuth clients for organization {organization_id}.
        slots:
          organization_id: path.collaborator.organization_ids.organization_id
      - text: Show the first {limit} OAuth clients of organization {organization_id}.
        slots:
          limit: query.limit
          organization_id: path.collaborator.organization_ids.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{collaborator.organization_ids.organization_id}/clients'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an OAuth client under an organization
      effect: write
      questions:
      - How do I register a new OAuth client owned by an organization?
      - Does the owning organization get all rights on a new OAuth client?
      instructions:
      - text: Create OAuth client {client} under organization {organization_id}.
        slots:
          client: requestBody.client
          organization_id: path.collaborator.organization_ids.organization_id
      - text: Register OAuth app {client} owned by organization {organization_id}.
        slots:
          client: requestBody.client
          organization_id: path.collaborator.organization_ids.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{collaborator.user_ids.user_id}/clients'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's OAuth clients
      effect: read
      questions:
      - What OAuth clients is a given user a collaborator on?
      - Can I list only one user's OAuth clients, including deleted ones?
      instructions:
      - text: List OAuth clients for user {user_id}.
        slots:
          user_id: path.collaborator.user_ids.user_id
      - text: 'List user {user_id}''s OAuth clients including deleted ones: {deleted}.'
        slots:
          user_id: path.collaborator.user_ids.user_id
          deleted: query.deleted
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{collaborator.user_ids.user_id}/clients'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an OAuth client under a user
      effect: write
      questions:
      - How do I register an OAuth client under my own user account?
      - Will my user be the first collaborator on an OAuth client I create?
      instructions:
      - text: Create OAuth client {client} under user {user_id}.
        slots:
          client: requestBody.client
          user_id: path.collaborator.user_ids.user_id
      - text: Register OAuth app {client} owned by my user {user_id}.
        slots:
          client: requestBody.client
          user_id: path.collaborator.user_ids.user_id
      method: generated
      generated: '2026-09-26'