API Evangelist conversational phrasing for Anthropic Sessions API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Anthropic Sessions API
  version: 1.0.0
extends: openapi/anthropic-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: 25
- target: $.paths['/v1/sessions/{session_id}/archive?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive an agent session
      effect: write
      questions:
      - How do I archive an agent session I no longer need so it drops out of my default list?
      - Can I archive a Claude session through the beta sessions endpoint instead of deleting it?
      instructions:
      - text: Archive session {session_id} using the beta flag.
        slots:
          session_id: path.session_id
      - text: Move beta session {session_id} into the archive but keep its history.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/events/stream?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream a session's events live
      effect: read
      questions:
      - How can I watch a running agent session's events as they happen?
      - Can the session event stream include partial deltas while the agent is still typing?
      instructions:
      - text: Open a live event stream for session {session_id}.
        slots:
          session_id: path.session_id
      - text: Stream events from session {session_id} including {event_deltas} deltas.
        slots:
          session_id: path.session_id
          event_deltas: query.event_deltas[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/events?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: List past events in a session
      effect: read
      questions:
      - Where can I page through the full event history of an agent session?
      - Can I filter a session's recorded events by type or by when they were created?
      - Is it possible to get a session's events oldest first instead of newest first?
      instructions:
      - text: List the recorded events of session {session_id}.
        slots:
          session_id: path.session_id
      - text: Show only {types} events from session {session_id} created after {since}.
        slots:
          types: query.types[]
          session_id: path.session_id
          since: query.created_at[gt]
      - text: Page through session {session_id} history {limit} events at a time in {order} order.
        slots:
          session_id: path.session_id
          limit: query.limit
          order: query.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/events?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Send events into an agent session
      effect: write
      questions:
      - How do I post a user message into an agent session with the beta sessions API?
      - Can I push several events to a session in a single request?
      instructions:
      - text: Send events {events} to beta session {session_id}.
        slots:
          events: requestBody.events
          session_id: path.session_id
      - text: Post a batch of user events {events} into session {session_id} via the beta flag.
        slots:
          events: requestBody.events
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/resources/{resource_id}?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a resource attached to a session
      effect: read
      questions:
      - How do I look up one resource that's mounted on an agent session?
      - What details can I see for a specific session resource?
      instructions:
      - text: Get resource {resource_id} on session {session_id}.
        slots:
          resource_id: path.resource_id
          session_id: path.session_id
      - text: Show me the details of session {session_id} resource {resource_id}.
        slots:
          session_id: path.session_id
          resource_id: path.resource_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/resources/{resource_id}?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh a session resource's access token
      effect: write
      questions:
      - Need to rotate the authorization token on a resource already attached to a session?
      - Can I give a session resource a new access token without removing it?
      instructions:
      - text: Update resource {resource_id} on session {session_id} with token {authorization_token}.
        slots:
          resource_id: path.resource_id
          session_id: path.session_id
          authorization_token: requestBody.authorization_token
      - text: Swap in a fresh authorization token {authorization_token} for session {session_id} resource {resource_id}.
        slots:
          authorization_token: requestBody.authorization_token
          session_id: path.session_id
          resource_id: path.resource_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/resources/{resource_id}?beta=true'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a resource from a session
      effect: destructive
      questions:
      - What is the way to detach a resource from an agent session?
      - Can I delete one mounted resource without deleting the whole session?
      instructions:
      - text: Delete resource {resource_id} from session {session_id}.
        slots:
          resource_id: path.resource_id
          session_id: path.session_id
      - text: Detach session {session_id} resource {resource_id} permanently.
        slots:
          session_id: path.session_id
          resource_id: path.resource_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/resources?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: List resources attached to a session
      effect: read
      questions:
      - Which resources are currently mounted on my agent session?
      - Can I page through a session's resources a few at a time?
      instructions:
      - text: List all resources on session {session_id}.
        slots:
          session_id: path.session_id
      - text: Show the first {limit} resources attached to session {session_id}.
        slots:
          limit: query.limit
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/resources?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a new resource to a session
      effect: write
      questions:
      - How do I mount an additional resource onto a session that's already running?
      - Can I add a resource to an agent session after I've created it?
      instructions:
      - text: Add a new resource to session {session_id}.
        slots:
          session_id: path.session_id
      - text: Attach another resource onto existing session {session_id}.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/threads/{thread_id}/archive?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a thread within a session
      effect: write
      questions:
      - How do I archive a single thread inside an agent session?
      - Can I put away one conversation thread while keeping the rest of the session active?
      instructions:
      - text: Archive thread {thread_id} in session {session_id}.
        slots:
          thread_id: path.thread_id
          session_id: path.session_id
      - text: Mark session {session_id} thread {thread_id} as archived.
        slots:
          session_id: path.session_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/threads/{thread_id}/events?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: List events recorded in a session thread
      effect: read
      questions:
      - Where do I read back the event history for one thread of a session?
      - Can I page through a single thread's events rather than the whole session's?
      instructions:
      - text: List the events in thread {thread_id} of session {session_id}.
        slots:
          thread_id: path.thread_id
          session_id: path.session_id
      - text: Page through {limit} past events at a time from session {session_id} thread {thread_id}.
        slots:
          limit: query.limit
          session_id: path.session_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/threads/{thread_id}/stream?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream live events from a session thread
      effect: read
      questions:
      - How can I follow just one thread of an agent session in real time?
      - Can a thread's live stream include incremental deltas?
      instructions:
      - text: Stream thread {thread_id} of session {session_id} live.
        slots:
          thread_id: path.thread_id
          session_id: path.session_id
      - text: Follow session {session_id} thread {thread_id} as it runs with {event_deltas} deltas turned on.
        slots:
          session_id: path.session_id
          thread_id: path.thread_id
          event_deltas: query.event_deltas[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/threads/{thread_id}?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one thread of a session
      effect: read
      questions:
      - Can I fetch the details of a specific thread in a session?
      - What does a single session thread record look like?
      instructions:
      - text: Get thread {thread_id} from session {session_id}.
        slots:
          thread_id: path.thread_id
          session_id: path.session_id
      - text: Look up the thread record {thread_id} under session {session_id}.
        slots:
          thread_id: path.thread_id
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/threads?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: List the threads in a session
      effect: read
      questions:
      - Which threads exist inside my agent session?
      - Can I page through a session's threads in chunks?
      instructions:
      - text: List every thread in session {session_id}.
        slots:
          session_id: path.session_id
      - text: Show {limit} threads per page for session {session_id}.
        slots:
          limit: query.limit
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an agent session via the beta flag
      effect: read
      questions:
      - How do I check the status and settings of one agent session using the beta endpoint?
      - What does the beta sessions API return for a single session?
      instructions:
      - text: Get beta session {session_id}.
        slots:
          session_id: path.session_id
      - text: Fetch session {session_id} with the beta query flag set.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a session's title, vaults or budget
      effect: write
      questions:
      - How do I rename an agent session or change its metadata?
      - Can I change which vaults or budget a session uses after it starts?
      - Is it possible to switch the agent attached to an existing session?
      instructions:
      - text: Rename session {session_id} to {title}.
        slots:
          session_id: path.session_id
          title: requestBody.title
      - text: Set the budget of session {session_id} to {budget}.
        slots:
          session_id: path.session_id
          budget: requestBody.budget
      - text: Give session {session_id} access to vaults {vault_ids}.
        slots:
          session_id: path.session_id
          vault_ids: requestBody.vault_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}?beta=true'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an agent session via the beta flag
      effect: destructive
      questions:
      - How do I permanently delete an agent session with the beta sessions API?
      - Can I remove a session entirely rather than archiving it, using the beta endpoint?
      instructions:
      - text: Delete beta session {session_id} permanently.
        slots:
          session_id: path.session_id
      - text: Remove session {session_id} for good through the beta flag.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter agent sessions
      effect: read
      questions:
      - Which agent sessions are running for a given agent or deployment?
      - Can I include archived sessions or filter sessions by status and creation date?
      - How do I find sessions that used a particular memory store?
      instructions:
      - text: List sessions for agent {agent_id} with status {statuses}.
        slots:
          agent_id: query.agent_id
          statuses: query.statuses[]
      - text: Show sessions started by deployment {deployment_id}, archived ones included {include_archived}.
        slots:
          deployment_id: query.deployment_id
          include_archived: query.include_archived
      - text: Find sessions created since {since} that used memory store {memory_store_id}.
        slots:
          since: query.created_at[gte]
          memory_store_id: query.memory_store_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new agent session with resources
      effect: write
      questions:
      - How do I start a new agent session in an environment with the beta API?
      - Can I seed a new session with initial events and a spending budget?
      - Is it possible to attach resources and vaults when a session is created?
      instructions:
      - text: Start a beta session for agent {agent} in environment {environment_id}.
        slots:
          agent: requestBody.agent
          environment_id: requestBody.environment_id
      - text: Create session {title} running agent {agent} in environment {environment_id} with budget {budget}.
        slots:
          title: requestBody.title
          agent: requestBody.agent
          environment_id: requestBody.environment_id
          budget: requestBody.budget
      - text: Launch agent {agent} in environment {environment_id} and kick it off with events {initial_events}.
        slots:
          agent: requestBody.agent
          environment_id: requestBody.environment_id
          initial_events: requestBody.initial_events
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List sessions on the plain sessions endpoint
      effect: read
      questions:
      - How do I list sessions by agent and status on the /v1/sessions endpoint without the beta query flag?
      - Can the non-beta-flag session listing filter by a single status?
      instructions:
      - text: Using the plain sessions endpoint, list sessions for agent {agent_id}.
        slots:
          agent_id: query.agent_id
      - text: On the endpoint without the beta query flag, list sessions whose status is {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a session on the plain sessions endpoint
      effect: write
      questions:
      - How do I create a stateful agent execution instance without the beta query flag?
      - Can I pass vault IDs when creating a session on the plain /v1/sessions endpoint?
      instructions:
      - text: On the plain endpoint, create a stateful execution for agent {agent} in environment {environment_id}.
        slots:
          agent: requestBody.agent
          environment_id: requestBody.environment_id
      - text: Without the beta flag, spin up agent {agent} in {environment_id} using vaults {vault_ids}.
        slots:
          agent: requestBody.agent
          environment_id: requestBody.environment_id
          vault_ids: requestBody.vault_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a session on the plain sessions endpoint
      effect: read
      questions:
      - How do I read one session from /v1/sessions without adding the beta query flag?
      - What's the non-beta-flag way to look up a session by its ID?
      instructions:
      - text: Look up session {session_id} on the plain endpoint.
        slots:
          session_id: path.session_id
      - text: Retrieve session {session_id} without the beta query parameter.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a session's tools or MCP servers
      effect: write
      questions:
      - How do I change the tools or MCP servers a session uses?
      - Can I reconfigure a session's config on the plain endpoint without the beta flag?
      instructions:
      - text: Update the tools and MCP servers configured on session {session_id}.
        slots:
          session_id: path.session_id
      - text: Reconfigure session {session_id} through the plain endpoint.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a session on the plain sessions endpoint
      effect: destructive
      questions:
      - How do I delete a session on /v1/sessions without the beta query flag?
      - Is deleting a session on the plain endpoint permanent?
      instructions:
      - text: Delete session {session_id} using the plain endpoint.
        slots:
          session_id: path.session_id
      - text: Without the beta parameter, permanently erase session {session_id}.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/sessions/{session_id}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a session on the plain endpoint
      effect: write
      questions:
      - How do I archive a session on the endpoint that doesn't take the beta query flag?
      - Can I archive a session through the plain /archive path?
      instructions:
      - text: Archive session {session_id} on the plain endpoint.
        slots:
          session_id: path.session_id
      - text: Without the beta parameter, set session {session_id} to archived.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'