Google Gemini Gemini Environments API

openapi: 3.2.0
info:
  title: Gemini Environments API
  version: v1beta
  description: Generated from Google's published Discovery document for Gemini API (generativelanguage v1beta, revision 20261111). 6 operation(s).
  contact:
    name: Google
    url: https://developers.google.com/
  termsOfService: https://developers.google.com/terms
servers:
- url: https://generativelanguage.googleapis.com
tags:
- name: Environments
paths:
  /v1beta/environments:list:
    get:
      operationId: generativelanguage.environments.list
      summary: List environments
      description: Lists environments.
      parameters:
      - name: mode
        in: query
        required: false
        description: Optional. Filter environments by compute lifecycle mode.
        schema:
          enum:
          - ENVIRONMENT_MODE_UNSPECIFIED
          - ON_DEMAND
          - SELF_HOSTED
          type: string
      - name: pageSize
        in: query
        required: false
        description: Optional. Maximum number of environments to return. If unspecified, defaults to 50. Maximum is 1000.
        schema:
          type: integer
          format: int32
      - name: pageToken
        in: query
        required: false
        description: Optional. Pagination token.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEnvironmentsResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - apiKey: []
      tags:
      - Environments
  /v1beta/environments/{id}:delete:
    delete:
      operationId: generativelanguage.environments.delete
      summary: Delete environments
      description: Deletes an environment.
      parameters:
      - name: id
        in: path
        required: true
        description: Required. Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Empty'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - apiKey: []
      tags:
      - Environments
  /v1beta/environments:create:
    post:
      operationId: generativelanguage.environments.create
      summary: Create environments
      description: Creates an environment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnvironmentRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - apiKey: []
      tags:
      - Environments
  /v1beta/environments/{id}:get:
    get:
      operationId: generativelanguage.environments.get
      summary: Get environments
      description: Gets an environment.
      parameters:
      - name: id
        in: path
        required: true
        description: Required. Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - apiKey: []
      tags:
      - Environments
  /v1beta/environments/{environmentsId}/files/{filesId}:
    put:
      operationId: generativelanguage.environments.files.media.upload
      summary: Upload media
      description: Uploads (creates or updates) a file in an environment's workspace.
      parameters:
      - name: environmentsId
        in: path
        required: true
        description: Resource name segment (environmentsId).
        schema:
          type: string
      - name: filesId
        in: path
        required: true
        description: Resource name segment (filesId).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadEnvironmentFileRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadEnvironmentFileResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - apiKey: []
      x-google-media-upload:
        maxSize: '2147483648'
        protocols:
          simple:
            multipart: true
            path: /upload/v1beta/{+parent}/files/{+path}
          resumable:
            multipart: true
            path: /resumable/upload/v1beta/{+parent}/files/{+path}
        accept:
        - '*/*'
      tags:
      - Environments
  /v1beta/environments/{environmentsId}/files:
    get:
      operationId: generativelanguage.environments.files.media.download
      summary: Download media
      description: Retrieves file metadata or directory contents from an environment's snapshot. To download file contents directly, pass ?alt=media or use the files.download helper.
      parameters:
      - name: environmentsId
        in: path
        required: true
        description: Resource name segment (environmentsId).
        schema:
          type: string
      - name: page_size
        in: query
        required: false
        description: Optional. Maximum number of entries to return per page (for directory listing). If unspecified, defaults to 100. Maximum is 1000. NOLINT
        schema:
          type: integer
          format: int32
      - name: page_token
        in: query
        required: false
        description: Optional. Pagination token for directory listing. NOLINT
        schema:
          type: string
      - name: path
        in: query
        required: false
        description: 'Optional. The path of the file or directory within the environment. If empty, defaults to the root of the workspace. Example: "workspace/src/main.py"'
        schema:
          type: string
      - name: recursive
        in: query
        required: false
        description: Optional. If true and the path is a directory, recursively lists all files and subdirectories. Defaults to false (immediate children only).
        schema:
          type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEnvironmentFilesResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - apiKey: []
      tags:
      - Environments
components:
  schemas:
    EnvironmentNetworkEgressAllowlist:
      properties:
        allowlist:
          type: array
          items:
            $ref: '#/components/schemas/EgressRule'
          description: List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.
      description: Network egress configuration for the environment.
      type: object
    Source:
      description: A source to be mounted into the environment.
      type: object
      properties:
        target:
          type: string
          description: Where the source should appear in the environment.
        type:
          enum:
          - TYPE_UNSPECIFIED
          - GCS
          - INLINE
          - REPOSITORY
          type: string
        content:
          type: string
          description: The inline content if `type` is `INLINE`.
        source:
          description: The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.
          type: string
        encoding:
          description: Optional encoding for inline content (e.g. `base64`).
          type: string
    EgressRule:
      properties:
        mode:
          description: 'Network egress mode. Set via the `"allowlist": "disabled"` short form; must be the only rule in the allowlist and cannot be combined with `domain`, `transform` or `credential`.'
          type: string
          enum:
          - NETWORK_MODE_UNSPECIFIED
          - DISABLED
        transform:
          description: 'Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").'
          type: object
          additionalProperties:
            type: string
        credential:
          type: string
          description: Optional. Reference to a server-managed Credential resource by ID.
        domain:
          type: string
          description: Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.
      type: object
      description: A single domain allowlist rule with optional header injection.
    GetEnvironmentFilesResponse:
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/EnvironmentFile'
          description: If the requested path is a directory, this contains its contents. If the requested path is a file, this contains a single entry with the file's metadata. If alt=media was specified, this is empty (content is served via `blob`).
        next_page_token:
          type: string
          description: Pagination token for directory listing. NOLINT
      description: Response for `GetEnvironmentFiles`.
      type: object
    UploadEnvironmentFileResponse:
      type: object
      description: Response for `UploadEnvironmentFile`.
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/EnvironmentFile'
          description: List of files created or extracted in the environment.
    CreateEnvironmentRequest:
      type: object
      description: Request for `CreateEnvironment`.
      properties:
        customConfig:
          additionalProperties:
            description: Properties of the object.
          type: object
          description: Optional. Arbitrary customer-defined JSON configuration passed through to the self-hosted environment poller. Only supported when `mode` is `SELF_HOSTED`.
        networkAllowlist:
          $ref: '#/components/schemas/EnvironmentNetworkEgressAllowlist'
          description: Allow only specific domains.
        sources:
          description: Sources to be mounted into the environment.
          type: array
          items:
            $ref: '#/components/schemas/Source'
        fromEnvironment:
          type: string
          description: 'Optional. The source environment to copy/fork from. Format: `environments/{environment_id}` or `{environment_id}`. When specified, `sources` and `env` must be empty.'
        networkMode:
          description: Network egress mode.
          enum:
          - NETWORK_MODE_UNSPECIFIED
          - DISABLED
          type: string
        mode:
          description: The compute lifecycle mode for this environment.
          enum:
          - ENVIRONMENT_MODE_UNSPECIFIED
          - ON_DEMAND
          - SELF_HOSTED
          type: string
        systemInstruction:
          description: Optional. System instruction applied to interactions running in this environment. Only supported for `SELF_HOSTED` environments, where it is recommended.
          type: string
    ListEnvironmentsResponse:
      description: Response for `ListEnvironments`.
      type: object
      properties:
        environments:
          description: Environments belonging to the provided project.
          items:
            $ref: '#/components/schemas/Environment'
          type: array
        nextPageToken:
          type: string
          description: Pagination token.
    Environment:
      type: object
      description: An execution environment for an agent.
      properties:
        networkMode:
          description: Network egress mode.
          enum:
          - NETWORK_MODE_UNSPECIFIED
          - DISABLED
          type: string
        lastAccessed:
          readOnly: true
          description: Output only. The time at which the environment was last accessed in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
          type: string
        id:
          readOnly: true
          type: string
          description: Required. Output only. The ID of the environment.
        created:
          type: string
          readOnly: true
          description: Output only. The time at which the environment was created in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
        environmentKey:
          readOnly: true
          description: Output only. Secret token generated upon environment creation for self_hosted environments. Used by the self-hosted sandbox daemon to authenticate polling and streaming requests. Only returned in the CreateEnvironment response; omitted from subsequent GetEnvironment and ListEnvironments calls.
          type: string
        fileCount:
          readOnly: true
          description: Output only. The number of files in the environment, output only.
          format: int64
          type: string
        mode:
          readOnly: true
          description: Output only. The compute lifecycle mode for this environment.
          enum:
          - ENVIRONMENT_MODE_UNSPECIFIED
          - ON_DEMAND
          - SELF_HOSTED
          type: string
        sizeBytes:
          readOnly: true
          type: string
          description: Output only. The total size of the environment files in bytes, output only.
          format: int64
        customConfig:
          readOnly: true
          description: Output only. Arbitrary customer-defined JSON configuration passed through to the self-hosted environment poller. Only populated for `self_hosted` environments when configured.
          additionalProperties:
            description: Properties of the object.
          type: object
        networkAllowlist:
          $ref: '#/components/schemas/EnvironmentNetworkEgressAllowlist'
          description: Allow only specific domains.
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources to be mounted into the environment.
        updated:
          readOnly: true
          type: string
          description: Output only. The time at which the environment was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
        status:
          type: string
          enum:
          - STATUS_UNSPECIFIED
          - ACTIVE
          - EXPIRED
          description: Output only. The status of the environment container.
          readOnly: true
    UploadEnvironmentFileRequest:
      description: Request for `UploadEnvironmentFile`.
      type: object
      properties:
        extract:
          description: Optional. If true, treats the uploaded file as a tar/tar.gz archive and unpacks it into `path`.
          type: boolean
        overwrite:
          type: boolean
          description: Optional. Whether to overwrite the destination file if it already exists.
    EnvironmentFile:
      type: object
      description: Metadata for a file or directory within an environment.
      properties:
        type:
          description: Output only. The type of the entry.
          type: string
          enum:
          - TYPE_UNSPECIFIED
          - FILE
          - DIRECTORY
          readOnly: true
        name:
          description: Output only. The name of the file or directory (e.g., "main.py" or "src").
          type: string
          readOnly: true
        mime_type:
          type: string
          readOnly: true
          description: Output only. The MIME type of the file (e.g., "text/python", "image/png"). Empty for directories. NOLINT
        path:
          description: Output only. The full relative path within the environment (e.g., "workspace/src/main.py").
          type: string
          readOnly: true
        modified:
          type: string
          description: Output only. The modification time of the file/directory.
          readOnly: true
          format: google-datetime
        created:
          readOnly: true
          format: google-datetime
          type: string
          description: Output only. The creation time of the file/directory.
        size_bytes:
          description: Output only. The size of the file/directory in bytes. NOLINT
          format: int64
          type: string
          readOnly: true
    Empty:
      type: object
      description: 'A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. For instance: service Foo { rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); }'
      properties: {}
    GoogleRpcError:
      type: object
      description: The error envelope every Google API returns.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            status:
              type: string
            details:
              type: array
              items:
                type: object
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: API key; accepted by methods that do not need user data.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/devstorage.read_only: View your data in Google Cloud Storage
externalDocs:
  url: https://developers.generativeai.google/api
x-provenance:
  method: harvested
  publisher: Google
  source: https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta
  note: converted by discovery-to-openapi.py from Google's Discovery document (revision 20261111)