# 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 User Bookmark Registry API
  version: 1.0.0
extends: openapi/the-things-network-userbookmarkregistry-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: 9
- target: $.paths['/users/{user_ids.user_id}/bookmarks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's bookmarks
      effect: read
      questions:
      - Which applications, gateways and devices has a user bookmarked?
      - Can I list only bookmarks of certain entity types?
      instructions:
      - text: List bookmarks for user {user_id}.
        slots:
          user_id: path.user_ids.user_id
      - text: Show user {user_id}'s bookmarks of type {entity_types}.
        slots:
          user_id: path.user_ids.user_id
          entity_types: query.entity_types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/bookmarks'].post
  update:
    x-apievangelist-phrasing:
      intent: Bookmark an entity for a user
      effect: write
      questions:
      - How do I bookmark an application or gateway so it shows up in my favorites?
      - Can I add a bookmark to any kind of entity for a user?
      instructions:
      - text: Bookmark entity {entity_ids} for user {user_id}.
        slots:
          entity_ids: requestBody.entity_ids
          user_id: path.user_ids.user_id
      - text: Add a new bookmark to user {user_id}'s list for {entity_ids}.
        slots:
          user_id: path.user_ids.user_id
          entity_ids: requestBody.entity_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/bookmarks/applications/{entity_ids.application_ids.application_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an application bookmark
      effect: destructive
      questions:
      - How do I unbookmark an application?
      - Can I remove one application from a user's bookmarks?
      instructions:
      - text: Remove the bookmark for application {application_id} from user {user_id}.
        slots:
          application_id: path.entity_ids.application_ids.application_id
          user_id: path.user_ids.user_id
      - text: Unbookmark application {application_id} for {user_id}.
        slots:
          application_id: path.entity_ids.application_ids.application_id
          user_id: path.user_ids.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/bookmarks/applications/{entity_ids.device_ids.application_ids.application_id}/devices/{entity_ids.device_ids.device_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an end device bookmark
      effect: destructive
      questions:
      - How do I unbookmark a single end device?
      - Can I remove a device bookmark by application and device ID?
      instructions:
      - text: Remove the bookmark for device {device_id} in application {application_id} from user {user_id}.
        slots:
          device_id: path.entity_ids.device_ids.device_id
          application_id: path.entity_ids.device_ids.application_ids.application_id
          user_id: path.user_ids.user_id
      - text: Unbookmark end device {device_id} of {application_id} for {user_id}.
        slots:
          device_id: path.entity_ids.device_ids.device_id
          application_id: path.entity_ids.device_ids.application_ids.application_id
          user_id: path.user_ids.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/bookmarks/batch'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove several bookmarks at once
      effect: destructive
      questions:
      - Can I clear multiple bookmarks in one atomic operation?
      - What happens to bookmarks that don't exist during a batch delete?
      instructions:
      - text: Delete a batch of bookmarks for user {user_id}.
        slots:
          user_id: path.user_ids.user_id
      - text: Clear several of user {user_id}'s bookmarks in one atomic call.
        slots:
          user_id: path.user_ids.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/bookmarks/clients/{entity_ids.client_ids.client_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an OAuth client bookmark
      effect: destructive
      questions:
      - How do I unbookmark an OAuth client?
      - Can I drop a client from a user's bookmarks?
      instructions:
      - text: Remove the bookmark for OAuth client {client_id} from user {user_id}.
        slots:
          client_id: path.entity_ids.client_ids.client_id
          user_id: path.user_ids.user_id
      - text: Unbookmark client {client_id} for {user_id}.
        slots:
          client_id: path.entity_ids.client_ids.client_id
          user_id: path.user_ids.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/bookmarks/gateways/{entity_ids.gateway_ids.gateway_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a gateway bookmark
      effect: destructive
      questions:
      - How do I unbookmark a gateway?
      - Can I remove one gateway from my bookmarks?
      instructions:
      - text: Remove the bookmark for gateway {gateway_id} from user {user_id}.
        slots:
          gateway_id: path.entity_ids.gateway_ids.gateway_id
          user_id: path.user_ids.user_id
      - text: Unbookmark gateway {gateway_id} for {user_id}.
        slots:
          gateway_id: path.entity_ids.gateway_ids.gateway_id
          user_id: path.user_ids.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/bookmarks/organizations/{entity_ids.organization_ids.organization_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an organization bookmark
      effect: destructive
      questions:
      - How do I unbookmark an organization?
      - Can I take an organization off a user's bookmarks?
      instructions:
      - text: Remove the bookmark for organization {organization_id} from user {user_id}.
        slots:
          organization_id: path.entity_ids.organization_ids.organization_id
          user_id: path.user_ids.user_id
      - text: Unbookmark organization {organization_id} for {user_id}.
        slots:
          organization_id: path.entity_ids.organization_ids.organization_id
          user_id: path.user_ids.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/bookmarks/users/{entity_ids.user_ids.user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user bookmark
      effect: destructive
      questions:
      - How do I remove another user from my bookmarks?
      - Can I unbookmark a user account I saved earlier?
      instructions:
      - text: Drop the saved person {bookmarked_user} from the bookmarks {user_id} keeps.
        slots:
          bookmarked_user: path.entity_ids.user_ids.user_id
          user_id: path.user_ids.user_id
      - text: Unbookmark user account {bookmarked_user} for {user_id}.
        slots:
          bookmarked_user: path.entity_ids.user_ids.user_id
          user_id: path.user_ids.user_id
      method: generated
      generated: '2026-09-26'