# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Com Sessions API
  version: 1.0.0
extends: openapi/clerk-com-sessions-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: 19
- target: $.paths['/sessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List sessions for a user or client
      effect: read
      questions:
      - Which sessions does a given user currently have in Clerk?
      - Can I filter the backend session list to only active or revoked sessions?
      - How do I page through sessions belonging to one client device?
      instructions:
      - text: List the sessions for user {user_id}.
        slots:
          user_id: query.user_id
      - text: Show sessions with status {status} for client {client_id}.
        slots:
          status: query.status
          client_id: query.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a test session for a user
      effect: write
      questions:
      - How do I create an active session for a user in a test instance?
      - Can I start a backend session for a user with an active organization already set?
      instructions:
      - text: Create a testing session for user {user_id}.
        slots:
          user_id: requestBody.user_id
      - text: Start a test session for user {user_id} with organization {active_organization_id} active.
        slots:
          user_id: requestBody.user_id
          active_organization_id: requestBody.active_organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a session by ID from the backend
      effect: read
      questions:
      - How do I look up the details of a session from my backend using its ID?
      - What status and user does a given session ID belong to on the server side?
      instructions:
      - text: Retrieve session {session_id} with the backend API.
        slots:
          session_id: path.session_id
      - text: Show the server-side details of session {session_id}.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh a session with an expired token
      effect: write
      questions:
      - How do I get a new session token when the old one has expired, using the refresh token?
      - What happens when refreshing a session fails validation, does it fall back to handshake?
      instructions:
      - text: Refresh session {session_id} using expired token {expired_token} and refresh token {refresh_token} from origin {request_origin}.
        slots:
          session_id: path.session_id
          expired_token: requestBody.expired_token
          refresh_token: requestBody.refresh_token
          request_origin: requestBody.request_origin
      - text: Refresh session {session_id} with expired token {expired_token}, refresh token {refresh_token}, origin {request_origin}, format {format}.
        slots:
          session_id: path.session_id
          expired_token: requestBody.expired_token
          refresh_token: requestBody.refresh_token
          request_origin: requestBody.request_origin
          format: requestBody.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's session
      effect: destructive
      questions:
      - How do I force a user to sign in again by revoking their session from the backend?
      - Does a revoked session still show up with its client in multi-session mode?
      instructions:
      - text: Revoke session {session_id}.
        slots:
          session_id: path.session_id
      - text: Sign the user out by revoking backend session {session_id}.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/tokens'].post
  update:
    x-apievangelist-phrasing:
      intent: Mint a session JWT from the backend
      effect: write
      questions:
      - How do I generate a session JWT for a session from my server?
      - Can I set a custom lifetime in seconds on a backend-issued session token?
      instructions:
      - text: Create a session token for session {session_id} from the backend.
        slots:
          session_id: path.session_id
      - text: Issue a session JWT for {session_id} that expires in {expires_in_seconds} seconds.
        slots:
          session_id: path.session_id
          expires_in_seconds: requestBody.expires_in_seconds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/tokens/{template_name}'].post
  update:
    x-apievangelist-phrasing:
      intent: Mint a backend session JWT from a template
      effect: write
      questions:
      - How do I create a JWT for a session using one of my instance's JWT templates on the server?
      - Can a template-based token from the backend have its own expiry in seconds?
      instructions:
      - text: Create a JWT for session {session_id} using template {template_name} from the backend.
        slots:
          session_id: path.session_id
          template_name: path.template_name
      - text: Issue a {template_name} template token for session {session_id} valid for {expires_in_seconds} seconds.
        slots:
          template_name: path.template_name
          session_id: path.session_id
          expires_in_seconds: requestBody.expires_in_seconds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all sessions from the current client
      effect: destructive
      questions:
      - How do I clear every session on the current browser client but keep the __client cookie?
      - Can I sign out all sessions on this device without dropping the client cookie?
      instructions:
      - text: Remove all sessions from the current client and keep its cookie.
      - text: Clear every session on this browser client.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a session on the current client
      effect: read
      questions:
      - How do I read one session belonging to the signed-in browser client?
      - What does the frontend API return for a single session ID on this client?
      instructions:
      - text: Get session {session_id} from the current client.
        slots:
          session_id: path.session_id
      - text: Show client session {session_id} via the frontend API.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/touch'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the active session on the client
      effect: write
      questions:
      - How do I switch which session is active on a multi-session client?
      - Can I change the active organization when I touch a session?
      instructions:
      - text: Make session {session_id} the active session on this client.
        slots:
          session_id: path.session_id
      - text: Touch session {session_id} and switch its active organization to {active_organization_id}.
        slots:
          session_id: path.session_id
          active_organization_id: requestBody.active_organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/end'].post
  update:
    x-apievangelist-phrasing:
      intent: End a session on the current client
      effect: destructive
      questions:
      - How do I sign a user out of one session from the browser by marking it ended?
      - Can I end a single session without removing the other sessions on the client?
      instructions:
      - text: End session {session_id} on this client.
        slots:
          session_id: path.session_id
      - text: Mark client session {session_id} as ended.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/remove'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a session from the current client
      effect: destructive
      questions:
      - How do I delete a session entirely from the browser client instead of just ending it?
      - Is there a way to remove one session from a multi-session client?
      instructions:
      - text: Remove session {session_id} from the current client.
        slots:
          session_id: path.session_id
      - text: Delete client session {session_id}.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/tokens'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a session JWT from the frontend client
      effect: write
      questions:
      - How do I fetch a fresh session JWT for the signed-in user from the browser?
      - Can the frontend token request pin a specific organization into the JWT?
      instructions:
      - text: Create a frontend session token for session {session_id}.
        slots:
          session_id: path.session_id
      - text: Get a client session JWT for {session_id} scoped to organization {organization_id}.
        slots:
          session_id: path.session_id
          organization_id: requestBody.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/tokens/{template_name}'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a templated JWT from the frontend client
      effect: write
      questions:
      - How do I get a JWT shaped by a JWT template for the signed-in user in the browser?
      - Which endpoint gives the frontend a custom template token for a third-party service?
      instructions:
      - text: Get a {template_name} template JWT for client session {session_id}.
        slots:
          template_name: path.template_name
          session_id: path.session_id
      - text: From the browser, mint a token for session {session_id} with JWT template {template_name}.
        slots:
          session_id: path.session_id
          template_name: path.template_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Start step-up reverification on a session
      effect: write
      questions:
      - How do I ask a signed-in user to re-verify before a sensitive action?
      - What happens if I request second-factor reverification but the user has no second factor?
      instructions:
      - text: Start reverification at level {level} for session {session_id}.
        slots:
          level: requestBody.level
          session_id: path.session_id
      - text: Require session {session_id} to reverify with level {level}.
        slots:
          session_id: path.session_id
          level: requestBody.level
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/verify/prepare_first_factor'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a first-factor reverification code
      effect: write
      questions:
      - How do I email or text a one-time code to a user during session reverification?
      - Which first-factor strategies can I prepare when reverifying a session?
      instructions:
      - text: Prepare first-factor reverification for session {session_id} using strategy {strategy}.
        slots:
          session_id: path.session_id
          strategy: requestBody.strategy
      - text: Send a reverification code to email address {email_address_id} for session {session_id}.
        slots:
          email_address_id: requestBody.email_address_id
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/verify/attempt_first_factor'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a first-factor reverification attempt
      effect: write
      questions:
      - How do I check the code or password a user entered to reverify their session?
      - Can a user reverify their session with a passkey instead of a code?
      instructions:
      - text: Attempt first-factor reverification on session {session_id} with strategy {strategy} and code {code}.
        slots:
          session_id: path.session_id
          strategy: requestBody.strategy
          code: requestBody.code
      - text: Reverify session {session_id} using the {strategy} strategy.
        slots:
          session_id: path.session_id
          strategy: requestBody.strategy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/verify/prepare_second_factor'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a second-factor reverification code
      effect: write
      questions:
      - How do I trigger the second factor, such as an SMS code, while reverifying a session?
      - Which phone number receives the code when preparing second-factor reverification?
      instructions:
      - text: Prepare second-factor reverification for session {session_id}.
        slots:
          session_id: path.session_id
      - text: Send a second-factor code to phone {phone_number_id} for session {session_id}.
        slots:
          phone_number_id: requestBody.phone_number_id
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sessions/{session_id}/verify/attempt_second_factor'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a second-factor reverification code
      effect: write
      questions:
      - How do I finish reverification by checking the user's second-factor code?
      - Does the second-factor reverification attempt need the prepare step first?
      instructions:
      - text: Attempt second-factor reverification on session {session_id} with code {code}.
        slots:
          session_id: path.session_id
          code: requestBody.code
      - text: Complete the second factor for session {session_id} using strategy {strategy}.
        slots:
          session_id: path.session_id
          strategy: requestBody.strategy
      method: generated
      generated: '2026-09-26'