# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST API Token API
  version: 1.0.0
extends: openapi/dotcms-api-token-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: 7
- target: $.paths['/api/v1/apitoken/{tokenId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an API token
      effect: destructive
      questions:
      - How do I permanently delete an API token, even an expired one?
      - Can revoked tokens be deleted afterwards?
      instructions:
      - text: Delete API token {tokenId}.
        slots:
          tokenId: path.tokenId
      - text: Permanently remove token {tokenId}.
        slots:
          tokenId: path.tokenId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apitoken/{userId}/tokens'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's API tokens
      effect: read
      questions:
      - Which API tokens does a given user have?
      - Can I include revoked tokens when listing a user's tokens?
      instructions:
      - text: List API tokens for user {userId}.
        slots:
          userId: path.userId
      - text: Show all tokens of user {userId}, including revoked ones.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apitoken/expiring'].get
  update:
    x-apievangelist-phrasing:
      intent: List API tokens about to expire
      effect: read
      questions:
      - Which API tokens will expire soon?
      - Do I have any tokens nearing their expiration date?
      instructions:
      - text: List API tokens that are about to expire.
      - text: Show tokens expiring within the configured window.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apitoken/{tokenId}/jwt'].get
  update:
    x-apievangelist-phrasing:
      intent: Generate a new JWT for a token
      effect: write
      questions:
      - How do I get a fresh JWT for an existing API token?
      - Does generating a new JWT replace the old one?
      instructions:
      - text: Generate a new JWT for token {tokenId}.
        slots:
          tokenId: path.tokenId
      - text: Regenerate the JSON web token of API token {tokenId}.
        slots:
          tokenId: path.tokenId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apitoken/remote'].put
  update:
    x-apievangelist-phrasing:
      intent: Get a token for a remote dotCMS instance
      effect: write
      questions:
      - How do I obtain an API token from another dotCMS server?
      - Can I use remote credentials to issue a token for remote operations?
      instructions:
      - text: Get a remote API token using {tokenInfo}.
        slots:
          tokenInfo: requestBody.tokenInfo
      - text: Request a token from the remote instance described by {tokenInfo}.
        slots:
          tokenInfo: requestBody.tokenInfo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apitoken'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue an API token
      effect: write
      questions:
      - How do I create a new API token for a user?
      - Can I set how long an issued token stays valid?
      instructions:
      - text: Issue an API token for user {userId}.
        slots:
          userId: requestBody.userId
      - text: Issue a token for {userId} that expires in {expirationSeconds} seconds.
        slots:
          userId: requestBody.userId
          expirationSeconds: requestBody.expirationSeconds
      - text: Create a token for {userId} restricted to network {network}.
        slots:
          userId: requestBody.userId
          network: requestBody.network
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apitoken/{tokenId}/revoke'].put
  update:
    x-apievangelist-phrasing:
      intent: Revoke an API token
      effect: destructive
      questions:
      - How do I revoke a leaked API token?
      - Can I disable a token without deleting it?
      instructions:
      - text: Revoke API token {tokenId}.
        slots:
          tokenId: path.tokenId
      - text: Disable token {tokenId} immediately.
        slots:
          tokenId: path.tokenId
      method: generated
      generated: '2026-09-26'