# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Frontend Client API
  version: 1.0.0
extends: openapi/clerk-com-client-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['/v1/client'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the current browser client
      effect: read
      questions:
      - Which client and sessions does the current browser have?
      - Can I read the client from the authorization header instead of cookies?
      instructions:
      - text: Get the current client.
      - text: Show the sessions on this browser's client.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a new client via PUT
      effect: write
      questions:
      - Can I create a fresh client with a PUT request?
      - Is there an idempotent PUT variant for creating a new client object?
      instructions:
      - text: Create a new client using the PUT endpoint.
      - text: Replace this browser's client with a new one via PUT.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new client via POST
      effect: write
      questions:
      - How do I create a new client and have it set in the response cookies?
      - Can a new client be returned in the authorization header with a POST?
      instructions:
      - text: Create a new client using the POST endpoint.
      - text: Start a fresh client via POST and set its cookie.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client'].delete
  update:
    x-apievangelist-phrasing:
      intent: Sign out all sessions on this client
      effect: destructive
      questions:
      - How do I sign out of every session in the current browser at once?
      - Can I end all sessions of the current client in one call?
      instructions:
      - text: End all sessions on the current client.
      - text: Sign out every account in this browser.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sync'].get
  update:
    x-apievangelist-phrasing:
      intent: Start syncing a satellite domain's client
      effect: read
      questions:
      - How does a satellite domain start syncing the session from the primary domain?
      - What begins the multi-domain session sync process?
      instructions:
      - text: Start client sync for satellite domain {link_domain}.
        slots:
          link_domain: query.link_domain
      - text: Sync this satellite with the primary and return to {redirect_url}.
        slots:
          redirect_url: query.redirect_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/link'].get
  update:
    x-apievangelist-phrasing:
      intent: Finish linking clients across domains
      effect: write
      questions:
      - How is the satellite and primary domain sync completed?
      - What token links the clients of two domains together?
      instructions:
      - text: Link clients across domains with token {__clerk_token}.
        slots:
          __clerk_token: query.__clerk_token
      - text: Complete the satellite-to-primary client link.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/handshake'].get
  update:
    x-apievangelist-phrasing:
      intent: Refresh a session token through a handshake
      effect: read
      questions:
      - How does my server get a fresh session token when it can't tell if the user is signed in?
      - Can the handshake return a token for a specific active organization?
      instructions:
      - text: Run a handshake to refresh the session token and redirect to {redirect_url}.
        slots:
          redirect_url: query.redirect_url
      - text: Handshake for a new session token scoped to organization {organization_id}.
        slots:
          organization_id: query.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/agents/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: Create a session from an agent task ticket
      effect: write
      questions:
      - How does an AI agent get signed in without going through the sign-in page?
      - Do agent task tickets bypass MFA, and can they be reused?
      instructions:
      - text: Create a session from agent task ticket {ticket}.
        slots:
          ticket: query.ticket
      - text: Sign the agent in directly using task ticket {ticket}.
        slots:
          ticket: query.ticket
      method: generated
      generated: '2026-09-26'