API Evangelist conversational phrasing for Anthropic Environments 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 Environments API
  version: 1.0.0
extends: openapi/anthropic-environments-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['/v1/environments/{environment_id}/archive?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive an environment so no new sessions use it
      effect: write
      questions:
      - How do I stop an environment from being used for new agent sessions?
      - What happens to an environment once I archive it with the beta flag?
      instructions:
      - text: Archive environment {environment_id} via the beta flag so it can't start new sessions.
        slots:
          environment_id: path.environment_id
      - text: Retire beta environment {environment_id} from new session use.
        slots:
          environment_id: path.environment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/work/poll?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Poll an environment's queue for new work
      effect: read
      questions:
      - How does a self-hosted sandbox worker pick up the next piece of work for an environment?
      - Can a worker long-poll for work and reclaim items that were left unfinished?
      instructions:
      - text: Poll environment {environment_id} for the next work item, waiting up to {block_ms} ms.
        slots:
          environment_id: path.environment_id
          block_ms: query.block_ms
      - text: As worker {worker_id}, pull work from environment {environment_id} and reclaim items older than {reclaim_older_than_ms} ms.
        slots:
          worker_id: header.Anthropic-Worker-ID
          environment_id: path.environment_id
          reclaim_older_than_ms: query.reclaim_older_than_ms
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/work/stats?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Get work queue statistics for an environment
      effect: read
      questions:
      - How backed up is the work queue for my sandbox environment?
      - Where can I see queue statistics for a self-hosted environment?
      instructions:
      - text: Show queue statistics for environment {environment_id}.
        slots:
          environment_id: path.environment_id
      - text: Report how much work is waiting in environment {environment_id}'s queue.
        slots:
          environment_id: path.environment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/work/{work_id}/ack?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge a work item a worker picked up
      effect: write
      questions:
      - How does a worker confirm it has claimed a work item from the environment queue?
      - Do I need to acknowledge work after polling it in a self-hosted sandbox?
      instructions:
      - text: Acknowledge work item {work_id} in environment {environment_id}.
        slots:
          work_id: path.work_id
          environment_id: path.environment_id
      - text: Confirm receipt of environment {environment_id} work {work_id}.
        slots:
          environment_id: path.environment_id
          work_id: path.work_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/work/{work_id}/heartbeat?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a heartbeat to keep a work item leased
      effect: write
      questions:
      - How does a worker keep its lease on a long-running work item alive?
      - Can a heartbeat ask for a longer time-to-live on the work item?
      instructions:
      - text: Record a heartbeat for work {work_id} in environment {environment_id}.
        slots:
          work_id: path.work_id
          environment_id: path.environment_id
      - text: Extend the lease on environment {environment_id} work {work_id} to {desired_ttl_seconds} seconds.
        slots:
          environment_id: path.environment_id
          work_id: path.work_id
          desired_ttl_seconds: query.desired_ttl_seconds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/work/{work_id}/stop?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop a work item in an environment
      effect: destructive
      questions:
      - How do I halt a work item that's running in a self-hosted environment?
      - Can I force-stop a work item instead of letting it wind down?
      instructions:
      - text: Stop work item {work_id} in environment {environment_id}.
        slots:
          work_id: path.work_id
          environment_id: path.environment_id
      - text: Force-stop environment {environment_id} work {work_id} with force set to {force}.
        slots:
          environment_id: path.environment_id
          work_id: path.work_id
          force: requestBody.force
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/work/{work_id}?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one work item from an environment
      effect: read
      questions:
      - What is the current state of a specific work item in my environment?
      - Can I look up a single queued work item by its ID?
      instructions:
      - text: Get work item {work_id} from environment {environment_id}.
        slots:
          work_id: path.work_id
          environment_id: path.environment_id
      - text: Show the details of environment {environment_id} work {work_id}.
        slots:
          environment_id: path.environment_id
          work_id: path.work_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/work/{work_id}?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a work item's metadata
      effect: write
      questions:
      - Can I attach or change metadata on a work item in an environment queue?
      - Where do I update the metadata a worker keeps on a work item?
      instructions:
      - text: Set metadata {metadata} on work item {work_id} in environment {environment_id}.
        slots:
          metadata: requestBody.metadata
          work_id: path.work_id
          environment_id: path.environment_id
      - text: Update environment {environment_id} work {work_id} metadata to {metadata}.
        slots:
          environment_id: path.environment_id
          work_id: path.work_id
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/work?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: List work items in an environment
      effect: read
      questions:
      - Which work items are queued or running in my sandbox environment?
      - Can I page through all work items for an environment?
      instructions:
      - text: List the work items in environment {environment_id}.
        slots:
          environment_id: path.environment_id
      - text: Show {limit} work items per page for environment {environment_id}.
        slots:
          limit: query.limit
          environment_id: path.environment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an environment via the beta flag
      effect: read
      questions:
      - How do I read an environment's configuration with the beta environments endpoint?
      - What settings does the beta API return for a single environment?
      instructions:
      - text: Get beta environment {environment_id}.
        slots:
          environment_id: path.environment_id
      - text: Fetch environment {environment_id} with the beta query flag.
        slots:
          environment_id: path.environment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an environment's configuration
      effect: write
      questions:
      - Can I rename an environment or change its description?
      - Is it possible to change an existing environment's config or scope?
      instructions:
      - text: Rename environment {environment_id} to {name}.
        slots:
          environment_id: path.environment_id
          name: requestBody.name
      - text: Replace the config of environment {environment_id} with {config}.
        slots:
          environment_id: path.environment_id
          config: requestBody.config
      - text: Change environment {environment_id} scope to {scope}.
        slots:
          environment_id: path.environment_id
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}?beta=true'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an environment via the beta flag
      effect: destructive
      questions:
      - How do I permanently delete an environment using the beta endpoint?
      - Does deleting an environment with the beta flag return a confirmation?
      instructions:
      - text: Delete beta environment {environment_id}.
        slots:
          environment_id: path.environment_id
      - text: Permanently remove environment {environment_id} through the beta flag.
        slots:
          environment_id: path.environment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments?beta=true'].get
  update:
    x-apievangelist-phrasing:
      intent: List environments, optionally including archived
      effect: read
      questions:
      - Which sandbox environments do I have, including archived ones?
      - Can the beta environment listing be paginated?
      instructions:
      - text: List my environments with archived included set to {include_archived}.
        slots:
          include_archived: query.include_archived
      - text: Show {limit} environments per page from the beta listing.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments?beta=true'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an environment with config and scope
      effect: write
      questions:
      - How do I set up a new environment for agent sessions with the beta flag?
      - Can I give a new environment a description, scope and metadata when I create it?
      instructions:
      - text: Create a beta environment named {name}.
        slots:
          name: requestBody.name
      - text: Create environment {name} with config {config} and scope {scope}.
        slots:
          name: requestBody.name
          config: requestBody.config
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments'].get
  update:
    x-apievangelist-phrasing:
      intent: List environments on the plain endpoint
      effect: read
      questions:
      - What's the paginated environment list on /v1/environments without the beta query flag?
      - Can I list environments through the plain endpoint using a specific beta header?
      instructions:
      - text: Using the plain endpoint with beta header {anthropic_beta}, list my environments.
        slots:
          anthropic_beta: header.anthropic-beta
      - text: List environments without the beta query flag, sending API version {anthropic_version}.
        slots:
          anthropic_version: header.anthropic-version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a container config on the plain endpoint
      effect: write
      questions:
      - How do I create a container configuration for sessions without the beta query flag?
      - Which fields are required to create an environment on the plain endpoint?
      instructions:
      - text: On the plain endpoint, create container config {name} using {config}.
        slots:
          name: requestBody.name
          config: requestBody.config
      - text: Without the beta flag, set up a session container called {name} with settings {config}.
        slots:
          name: requestBody.name
          config: requestBody.config
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an environment on the plain endpoint
      effect: read
      questions:
      - What's the non-beta-flag call to read one environment by ID?
      - Can I retrieve an environment from /v1/environments without the beta query parameter?
      instructions:
      - text: Look up environment {environment_id} on the plain endpoint.
        slots:
          environment_id: path.environment_id
      - text: Without the beta parameter, retrieve environment {environment_id}.
        slots:
          environment_id: path.environment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an environment on the plain endpoint
      effect: destructive
      questions:
      - What's the non-beta-flag way to delete an environment?
      - Can I delete environments from the plain /v1/environments path?
      instructions:
      - text: Delete environment {environment_id} using the plain endpoint.
        slots:
          environment_id: path.environment_id
      - text: Without the beta parameter, erase environment {environment_id}.
        slots:
          environment_id: path.environment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/environments/{environment_id}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive an environment on the plain endpoint
      effect: write
      questions:
      - Can I archive an environment without adding the beta query flag?
      - Where is the plain archive path for environments?
      instructions:
      - text: Archive environment {environment_id} on the plain endpoint.
        slots:
          environment_id: path.environment_id
      - text: Without the beta parameter, mark environment {environment_id} archived.
        slots:
          environment_id: path.environment_id
      method: generated
      generated: '2026-09-26'