openapi: 3.2.0
info:
  title: Anthropic Environments?beta=true API
servers:
- url: https://api.anthropic.com
tags:
- name: Environments?beta=true
paths:
  /v1/environments?beta=true:
    post:
      summary: Create Environment
      description: Create a new environment with the specified configuration.
      operationId: beta_create_environment_v1_environments_post
      parameters:
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          description: 'Optional header to specify the beta version(s) you want to use.


            To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
          title: Anthropic-Beta
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
        description: 'Optional header to specify the beta version(s) you want to use.


          To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BetaPublicEnvironmentCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaEnvironment'
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
      tags:
      - Environments?beta=true
    get:
      summary: List Environments
      description: List environments with pagination support.
      operationId: beta_list_environments_v1_environments_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Maximum number of environments to return
          default: 20
          title: Limit
        description: Maximum number of environments to return
      - name: page
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response.
          x-stainless-pagination-property:
            purpose: next_cursor_param
          title: Page
        description: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response.
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          description: Include archived environments in the response
          default: false
          title: Include Archived
        description: Include archived environments in the response
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          description: 'Optional header to specify the beta version(s) you want to use.


            To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
          title: Anthropic-Beta
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
        description: 'Optional header to specify the beta version(s) you want to use.


          To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaEnvironmentListResponse'
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
      tags:
      - Environments?beta=true
components:
  schemas:
    BetaGatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: Message
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: Type
          type: string
      required:
      - message
      - type
      title: GatewayTimeoutError
      type: object
    BetaUnrestrictedNetwork:
      properties:
        type:
          type: string
          const: unrestricted
          title: Type
          description: Network policy type
      additionalProperties: false
      type: object
      required:
      - type
      title: UnrestrictedNetwork
      description: Unrestricted network access.
    BetaOverloadedError:
      properties:
        message:
          default: Overloaded
          title: Message
          type: string
        type:
          const: overloaded_error
          default: overloaded_error
          title: Type
          type: string
      required:
      - message
      - type
      title: OverloadedError
      type: object
    BetaBillingError:
      properties:
        message:
          default: Billing error
          title: Message
          type: string
        type:
          const: billing_error
          default: billing_error
          title: Type
          type: string
      required:
      - message
      - type
      title: BillingError
      type: object
    BetaAuthenticationError:
      properties:
        message:
          default: Authentication error
          title: Message
          type: string
        type:
          const: authentication_error
          default: authentication_error
          title: Type
          type: string
      required:
      - message
      - type
      title: AuthenticationError
      type: object
    BetaNotFoundError:
      properties:
        message:
          default: Not found
          title: Message
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: Type
          type: string
      required:
      - message
      - type
      title: NotFoundError
      type: object
    BetaCloudConfigParams:
      properties:
        networking:
          anyOf:
          - oneOf:
            - $ref: '#/components/schemas/BetaUnrestrictedNetwork'
            - $ref: '#/components/schemas/BetaLimitedNetworkParams'
              x-anthropic-beta-required:
              - managed-agents-2026-04-01
            discriminator:
              propertyName: type
              mapping:
                limited: '#/components/schemas/BetaLimitedNetworkParams'
                unrestricted: '#/components/schemas/BetaUnrestrictedNetwork'
          - type: 'null'
          title: Networking
          description: Network configuration policy. Omit on update to preserve the existing value.
          examples:
          - type: limited
            allowed_hosts:
            - api.example.com
            allow_package_managers: true
        packages:
          anyOf:
          - $ref: '#/components/schemas/BetaPackagesParams'
          - type: 'null'
          description: Package manager configuration. Under `limited` networking, requires `networking.allow_package_managers` to be `true`. Omit on update to preserve the existing value.
          x-anthropic-beta-required:
          - managed-agents-2026-04-01
          examples:
          - pip:
            - pandas
            - numpy
        type:
          type: string
          const: cloud
          title: Type
          description: Environment type
          examples:
          - cloud
      additionalProperties: false
      type: object
      required:
      - type
      title: CloudConfigParams
      description: 'Request params for `cloud` environment configuration.


        Fields default to null; on update, omitted fields preserve the

        existing value.'
      example:
        type: cloud
        networking:
          type: limited
          allowed_hosts:
          - api.example.com
          allow_package_managers: true
        packages:
          pip:
          - pandas
          - numpy
    BetaCloudConfig:
      properties:
        networking:
          oneOf:
          - $ref: '#/components/schemas/BetaUnrestrictedNetwork'
          - $ref: '#/components/schemas/BetaLimitedNetwork'
            x-anthropic-beta-required:
            - managed-agents-2026-04-01
          title: Networking
          description: Network configuration policy.
          discriminator:
            propertyName: type
            mapping:
              limited: '#/components/schemas/BetaLimitedNetwork'
              unrestricted: '#/components/schemas/BetaUnrestrictedNetwork'
          examples:
          - type: limited
            allowed_hosts:
            - api.example.com
            allow_package_managers: true
            allow_mcp_servers: false
        packages:
          $ref: '#/components/schemas/BetaPackages'
          description: Package manager configuration.
          x-anthropic-beta-required:
          - managed-agents-2026-04-01
          examples:
          - type: packages
            pip:
            - pandas
            - numpy
            npm: []
            apt: []
            cargo: []
            gem: []
            go: []
        type:
          type: string
          const: cloud
          title: Type
          description: Environment type
          examples:
          - cloud
      type: object
      required:
      - networking
      - packages
      - type
      title: CloudConfig
      description: '`cloud` environment configuration.'
      example:
        type: cloud
        networking:
          type: limited
          allowed_hosts:
          - api.example.com
          allow_package_managers: true
          allow_mcp_servers: false
        packages:
          type: packages
          pip:
          - pandas
          - numpy
          npm: []
          apt: []
          cargo: []
          gem: []
          go: []
    BetaEnvironment:
      properties:
        archived_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Archived At
          description: RFC 3339 timestamp when environment was archived, or null if not archived
          examples:
          - null
        config:
          oneOf:
          - $ref: '#/components/schemas/BetaCloudConfig'
          - $ref: '#/components/schemas/BetaSelfHostedConfig'
            x-anthropic-beta-required:
            - managed-agents-2026-04-01
          title: Config
          description: Environment configuration (either Anthropic Cloud or self-hosted)
          discriminator:
            propertyName: type
            mapping:
              cloud: '#/components/schemas/BetaCloudConfig'
              self_hosted: '#/components/schemas/BetaSelfHostedConfig'
          examples:
          - type: cloud
            networking:
              type: limited
              allowed_hosts:
              - api.example.com
              allow_package_managers: true
              allow_mcp_servers: false
            packages:
              type: packages
              pip:
              - pandas
              - numpy
              npm: []
              apt: []
              cargo: []
              gem: []
              go: []
        created_at:
          type: string
          title: Created At
          description: RFC 3339 timestamp when environment was created
          examples:
          - '2026-03-15T10:00:00Z'
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: User-provided description for the environment; null when unset
          examples:
          - Python environment with data-analysis packages.
        id:
          type: string
          title: Id
          description: Environment identifier (e.g., 'env_...')
          examples:
          - env_011CZkZ9X2dpNyB7HsEFoRfW
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: User-provided metadata key-value pairs
          examples:
          - key: value
        name:
          type: string
          title: Name
          description: Human-readable name for the environment
          examples:
          - python-data-analysis
        scope:
          type: string
          enum:
          - organization
          - account
          title: Scope
          description: The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.
          x-anthropic-beta-required:
          - managed-agents-2026-04-01
        type:
          type: string
          const: environment
          title: Type
          description: The type of object (always 'environment')
          default: environment
          examples:
          - environment
        updated_at:
          type: string
          title: Updated At
          description: RFC 3339 timestamp when environment was last updated
          examples:
          - '2026-03-15T10:00:00Z'
      type: object
      required:
      - archived_at
      - config
      - created_at
      - description
      - id
      - metadata
      - name
      - type
      - updated_at
      title: Environment
      description: Unified Environment resource for both cloud and self-hosted environments.
      example:
        type: environment
        id: env_011CZkZ9X2dpNyB7HsEFoRfW
        name: python-data-analysis
        description: Python environment with data-analysis packages.
        config:
          type: cloud
          networking:
            type: limited
            allowed_hosts:
            - api.example.com
            allow_package_managers: true
            allow_mcp_servers: false
          packages:
            type: packages
            pip:
            - pandas
            - numpy
            npm: []
            apt: []
            cargo: []
            gem: []
            go: []
        metadata: {}
        archived_at: null
        created_at: '2026-03-15T10:00:00Z'
        updated_at: '2026-03-15T10:00:00Z'
    BetaInvalidRequestError:
      properties:
        message:
          default: Invalid request
          title: Message
          type: string
        type:
          const: invalid_request_error
          default: invalid_request_error
          title: Type
          type: string
      required:
      - message
      - type
      title: InvalidRequestError
      type: object
    BetaPackagesParams:
      properties:
        apt:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Apt
          description: Ubuntu/Debian packages to install
        cargo:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Cargo
          description: Rust packages to install
        gem:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Gem
          description: Ruby packages to install
        go:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Go
          description: Go packages to install
        npm:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Npm
          description: Node.js packages to install
        pip:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Pip
          description: Python packages to install
        type:
          type: string
          const: packages
          title: Type
          description: Package configuration type
          default: packages
      additionalProperties: false
      type: object
      title: PackagesParams
      description: 'Specify packages (and optionally their versions) available in this environment.


        When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest.


        Under `limited` networking, requires `networking.allow_package_managers` to be `true`.'
    BetaPermissionError:
      properties:
        message:
          default: Permission denied
          title: Message
          type: string
        type:
          const: permission_error
          default: permission_error
          title: Type
          type: string
      required:
      - message
      - type
      title: PermissionError
      type: object
    BetaSelfHostedConfig:
      properties:
        type:
          type: string
          const: self_hosted
          title: Type
          description: Environment type
      additionalProperties: false
      type: object
      required:
      - type
      title: SelfHostedConfig
      description: Configuration for self-hosted environments.
    BetaLimitedNetwork:
      properties:
        allow_mcp_servers:
          type: boolean
          title: Allow Mcp Servers
          description: Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.
        allow_package_managers:
          type: boolean
          title: Allow Package Managers
          description: Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.
        allowed_hosts:
          items:
            type: string
          type: array
          title: Allowed Hosts
          description: Specifies domains the container can reach.
        type:
          type: string
          const: limited
          title: Type
          description: Network policy type
      type: object
      required:
      - allow_mcp_servers
      - allow_package_managers
      - allowed_hosts
      - type
      title: LimitedNetwork
      description: Limited network access.
    BetaAPIError:
      properties:
        message:
          default: Internal server error
          title: Message
          type: string
        type:
          const: api_error
          default: api_error
          title: Type
          type: string
      required:
      - message
      - type
      title: APIError
      type: object
    BetaErrorResponse:
      properties:
        error:
          discriminator:
            mapping:
              api_error: '#/components/schemas/BetaAPIError'
              authentication_error: '#/components/schemas/BetaAuthenticationError'
              billing_error: '#/components/schemas/BetaBillingError'
              invalid_request_error: '#/components/schemas/BetaInvalidRequestError'
              not_found_error: '#/components/schemas/BetaNotFoundError'
              overloaded_error: '#/components/schemas/BetaOverloadedError'
              permission_error: '#/components/schemas/BetaPermissionError'
              rate_limit_error: '#/components/schemas/BetaRateLimitError'
              timeout_error: '#/components/schemas/BetaGatewayTimeoutError'
            propertyName: type
          oneOf:
          - $ref: '#/components/schemas/BetaInvalidRequestError'
          - $ref: '#/components/schemas/BetaAuthenticationError'
          - $ref: '#/components/schemas/BetaBillingError'
          - $ref: '#/components/schemas/BetaPermissionError'
          - $ref: '#/components/schemas/BetaNotFoundError'
          - $ref: '#/components/schemas/BetaRateLimitError'
          - $ref: '#/components/schemas/BetaGatewayTimeoutError'
          - $ref: '#/components/schemas/BetaAPIError'
          - $ref: '#/components/schemas/BetaOverloadedError'
          title: Error
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Request Id
        type:
          const: error
          default: error
          title: Type
          type: string
      required:
      - error
      - request_id
      - type
      title: ErrorResponse
      type: object
    BetaEnvironmentListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/BetaEnvironment'
          type: array
          title: Data
          description: List of environments.
          x-stainless-pagination-property:
            purpose: items
        next_page:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Page
          description: Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request.
          examples:
          - page_MjAyNS0wNS0xNFQwMDowMDowMFo=
          - null
          x-stainless-pagination-property:
            purpose: next_cursor_field
      type: object
      required:
      - data
      - next_page
      title: EnvironmentListResponse
      description: 'Response when listing environments.


        This response model uses opaque cursor-based pagination. Use the `page`

        query parameter with the value from `next_page` to fetch the next page.'
    BetaPublicEnvironmentCreateRequest:
      properties:
        config:
          anyOf:
          - oneOf:
            - $ref: '#/components/schemas/BetaCloudConfigParams'
            - $ref: '#/components/schemas/BetaSelfHostedConfigParams'
              x-anthropic-beta-required:
              - managed-agents-2026-04-01
            discriminator:
              propertyName: type
              mapping:
                cloud: '#/components/schemas/BetaCloudConfigParams'
                self_hosted: '#/components/schemas/BetaSelfHostedConfigParams'
          - type: 'null'
          title: Config
          description: Environment configuration
          examples:
          - type: cloud
            networking:
              type: limited
              allowed_hosts:
              - api.example.com
              allow_package_managers: true
            packages:
              pip:
              - pandas
              - numpy
        description:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Description
          description: Optional description of the environment
          examples:
          - Python environment with data-analysis packages.
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: User-provided metadata key-value pairs
        name:
          type: string
          maxLength: 256
          minLength: 1
          title: Name
          description: Human-readable name for the environment
          examples:
          - python-data-analysis
        scope:
          anyOf:
          - type: string
            enum:
            - organization
            - account
          - type: 'null'
          title: Scope
          description: The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. Only applicable for self-hosted environments. If not specified, defaults based on organization type.
          x-anthropic-beta-required:
          - managed-agents-2026-04-01
      additionalProperties: false
      type: object
      required:
      - name
      title: PublicEnvironmentCreateRequest
      description: Public API request to create a new environment (without org/account fields).
      example:
        name: python-data-analysis
        description: Python environment with data-analysis packages.
        config:
          type: cloud
          networking:
            type: limited
            allowed_hosts:
            - api.example.com
            allow_package_managers: true
          packages:
            pip:
            - pandas
            - numpy
    BetaLimitedNetworkParams:
      properties:
        allow_mcp_servers:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allow Mcp Servers
          description: Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.
        allow_package_managers:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allow Package Managers
          description: Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false` on creation. Must be `true` when `packages` are specified.
        allowed_hosts:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Hosts
          description: Specifies domains the container can reach.
        type:
          type: string
          const: limited
          title: Type
          description: Network policy type
      additionalProperties: false
      type: object
      required:
      - type
      title: LimitedNetworkParams
      description: 'Limited network request params.


        Fields default to null; on update, omitted fields preserve the

        existing value.'
    AnthropicBeta:
      anyOf:
      - type: string
      - type: string
        enum:
        - message-batches-2024-09-24
        - prompt-caching-2024-07-31
        - computer-use-2024-10-22
        - computer-use-2025-01-24
        - pdfs-2024-09-25
        - token-counting-2024-11-01
        - token-efficient-tools-2025-02-19
        - output-128k-2025-02-19
        - files-api-2025-04-14
        - mcp-client-2025-04-04
        - mcp-client-2025-11-20
        - dev-full-thinking-2025-05-14
        - interleaved-thinking-2025-05-14
        - code-execution-2025-05-22
        - extended-cache-ttl-2025-04-11
        - context-1m-2025-08-07
        - context-management-2025-06-27
        - model-context-window-exceeded-2025-08-26
        - skills-2025-10-02
        - fast-mode-2026-02-01
        - output-300k-2026-03-24
        - user-profiles-2026-03-24
        - user-profiles-2026-08-18
        - advisor-tool-2026-03-01
        - managed-agents-2026-04-01
        - cache-diagnosis-2026-04-07
        - dreaming-2026-04-21
        - thinking-token-count-2026-05-13
        - server-side-fallback-2026-06-01
        - server-side-fallback-2026-07-01
        - fallback-credit-2026-06-01
        - fallback-credit-2026-07-01
        - agent-memory-2026-07-22
        - mid-conversation-tool-changes-2026-07-01
        - compact-2026-01-12
        - computer-use-2025-11-24
        - mcp-tunnels-2026-06-22
        - structured-outputs-2025-11-13
        - task-budgets-2026-03-13
        - thinking-display-updates-2026-08-18
        - ce-user-management-2026-07-13
        x-stainless-nominal: false
    BetaSelfHostedConfigParams:
      properties:
        type:
          type: string
          const: self_hosted
          title: Type
          description: Environment type
      additionalProperties: false
      type: object
      required:
      - type
      title: SelfHostedConfigParams
      description: Request params for `self_hosted` environment configuration.
    BetaRateLimitError:
      properties:
        message:
          default: Rate limited
          title: Message
          type: string
        type:
          const: rate_limit_error
          default: rate_limit_error
          title: Type
          type: string
      required:
      - message
      - type
      title: RateLimitError
      type: object
    BetaPackages:
      properties:
        apt:
          items:
            type: string
          type: array
          title: Apt
          description: Ubuntu/Debian packages to install
        cargo:
          items:
            type: string
          type: array
          title: Cargo
          description: Rust packages to install
        gem:
          items:
            type: string
          type: array
          title: Gem
          description: Ruby packages to install
        go:
          items:
            type: string
          type: array
          title: Go
          description: Go packages to install
        npm:
          items:
            type: string
          type: array
          title: Npm
          description: Node.js packages to install
        pip:
          items:
            type: string
          type: array
          title: Pip
          description: Python packages to install
        type:
          type: string
          const: packages
          title: Type
          description: Package configuration type
          default: packages
      type: object
      required:
      - apt
      - cargo
      - gem
      - go
      - npm
      - pip
      title: Packages
      description: Packages (and their versions) available in this environment.