Gemini Environments API

Environments provide isolated execution contexts for running agent code, tools, and services securely.

View as markdown View the OpenAPI Spec

CreateEnvironment

post https://generativelanguage.googleapis.com/v1beta/environments

Creates an environment.

Request body

The request body contains data with the following structure:

network EnvironmentNetworkEgressAllowlist or enum (string)  (optional)

Network configuration for the environment.

Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.

Possible Types

object

Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.

allowlist array (AllowlistEntry)  (optional)

List of allowed outbound domains. Only requests to listed domains are permitted. Use [{'domain': '*'}] to allow all domains while still injecting headers on specific ones.

A single domain allowlist rule with optional header injection.

Fields

domain string  (optional)

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

transform array (object) or object  (optional)

Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.

string

Turns all network off.

Possible values

  • disabled

    Turns all network off.

sources array (Source)  (optional)

Sources to be mounted into the environment.

A source to be mounted into the environment.

Fields

content string  (optional)

The inline content if `type` is `INLINE`.

encoding string  (optional)

Optional encoding for inline content (e.g. `base64`).

source string  (optional)

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

target string  (optional)

Where the source should appear in the environment.

type enum (string)  (optional)

No description provided.

Possible values:

  • gcs

    A Cloud Storage bucket.

  • inline

    Inline content.

  • repository

    A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

Response

If successful, the response body contains data with the following structure:

created string  (optional)

Output only. The time at which the environment was created in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

file_count string  (optional)

Output only. The number of files in the environment, output only.

id string  (optional)

Required. Output only. The ID of the environment.

last_accessed string  (optional)

Output only. The time at which the environment was last accessed in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

network EnvironmentNetworkEgressAllowlist or enum (string)  (optional)

Network configuration for the environment.

Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.

Possible Types

object

Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.

allowlist array (AllowlistEntry)  (optional)

List of allowed outbound domains. Only requests to listed domains are permitted. Use [{'domain': '*'}] to allow all domains while still injecting headers on specific ones.

A single domain allowlist rule with optional header injection.

Fields

domain string  (optional)

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

transform array (object) or object  (optional)

Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.

string

Turns all network off.

Possible values

  • disabled

    Turns all network off.

size_bytes string  (optional)

Output only. The total size of the environment files in bytes, output only.

sources array (Source)  (optional)

Sources to be mounted into the environment.

A source to be mounted into the environment.

Fields

content string  (optional)

The inline content if `type` is `INLINE`.

encoding string  (optional)

Optional encoding for inline content (e.g. `base64`).

source string  (optional)

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

target string  (optional)

Where the source should appear in the environment.

type enum (string)  (optional)

No description provided.

Possible values:

  • gcs

    A Cloud Storage bucket.

  • inline

    Inline content.

  • repository

    A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

status enum (string)  (optional)

Output only. The status of the environment container.

Possible values:

  • active

    Output only. The status of the environment container.

  • expired

    Output only. The status of the environment container.

updated string  (optional)

Output only. The time at which the environment was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

Example Response

{
  "created": "string",
  "file_count": "string",
  "id": "string",
  "last_accessed": "string",
  "network": {
    "allowlist": [
      {
        "domain": "github.com",
        "transform": [
          {
            "Authorization": "Bearer your-token"
          }
        ]
      },
      {
        "domain": "*.googleapis.com"
      }
    ]
  },
  "size_bytes": "string",
  "sources": [
    {
      "content": "string",
      "encoding": "string",
      "source": "string",
      "target": "string",
      "type": "gcs"
    }
  ],
  "status": "active",
  "updated": "string"
}

ListEnvironments

get https://generativelanguage.googleapis.com/v1beta/environments

Lists environments.

Path / Query Parameters

page_size integer  (optional)

Optional. Maximum number of environments to return.\nIf unspecified, defaults to 50. Maximum is 1000.

page_token string  (optional)

Optional. Pagination token.

Response

If successful, the response body contains data with the following structure:

environments array (Environment)  (optional)

Environments belonging to the provided project.

next_page_token string  (optional)

Pagination token.

Example

Example Response

{
  "environments": [
    {
      "created": "string",
      "file_count": "string",
      "id": "string",
      "last_accessed": "string",
      "network": {
        "allowlist": [
          {
            "domain": "github.com",
            "transform": [
              {
                "Authorization": "Bearer your-token"
              }
            ]
          },
          {
            "domain": "*.googleapis.com"
          }
        ]
      },
      "size_bytes": "string",
      "sources": [
        {
          "content": "string",
          "encoding": "string",
          "source": "string",
          "target": "string",
          "type": "gcs"
        }
      ],
      "status": "active",
      "updated": "string"
    }
  ],
  "next_page_token": "string"
}

GetEnvironmentFiles

get https://generativelanguage.googleapis.com/v1beta/environments/{environment}/files/{path}

Retrieves a file or directory from an environment's snapshot.

Path / Query Parameters

page_size integer  (optional)

Optional. Maximum number of entries to return per page (for directory listing).

page_token string  (optional)

Optional. Pagination token for directory listing.

recursive boolean  (optional)

Optional. If true and the path is a directory, recursively lists all files.

Response

If successful, the response body contains data with the following structure:

files array (EnvironmentFile)  (optional)

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`).

Metadata for a file or directory within an environment.

Fields

created string  (optional)

Output only. The creation time of the file/directory.

mime_type string  (optional)

Output only. The MIME type of the file (e.g., "text/python", "image/png"). Empty for directories. NOLINT

modified string  (optional)

Output only. The modification time of the file/directory.

name string  (optional)

Output only. The name of the file or directory (e.g., "main.py" or "src").

path string  (optional)

Output only. The full relative path within the environment (e.g., "workspace/src/main.py").

size_bytes string  (optional)

Output only. The size of the file/directory in bytes. NOLINT

type enum (string)  (optional)

Output only. The type of the entry.

Possible values:

  • file

    A regular file.

  • directory

    A directory.

next_page_token string  (optional)

Pagination token for directory listing. NOLINT

Example

Example Response

{
  "files": [
    {
      "created": "string",
      "mime_type": "string",
      "modified": "string",
      "name": "string",
      "path": "string",
      "size_bytes": "string",
      "type": "file"
    }
  ],
  "next_page_token": "string"
}

GetEnvironment

get https://generativelanguage.googleapis.com/v1beta/environments/{id}

Gets an environment.

Response

If successful, the response body contains data with the following structure:

created string  (optional)

Output only. The time at which the environment was created in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

file_count string  (optional)

Output only. The number of files in the environment, output only.

id string  (optional)

Required. Output only. The ID of the environment.

last_accessed string  (optional)

Output only. The time at which the environment was last accessed in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

network EnvironmentNetworkEgressAllowlist or enum (string)  (optional)

Network configuration for the environment.

Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.

Possible Types

object

Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.

allowlist array (AllowlistEntry)  (optional)

List of allowed outbound domains. Only requests to listed domains are permitted. Use [{'domain': '*'}] to allow all domains while still injecting headers on specific ones.

A single domain allowlist rule with optional header injection.

Fields

domain string  (optional)

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

transform array (object) or object  (optional)

Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.

string

Turns all network off.

Possible values

  • disabled

    Turns all network off.

size_bytes string  (optional)

Output only. The total size of the environment files in bytes, output only.

sources array (Source)  (optional)

Sources to be mounted into the environment.

A source to be mounted into the environment.

Fields

content string  (optional)

The inline content if `type` is `INLINE`.

encoding string  (optional)

Optional encoding for inline content (e.g. `base64`).

source string  (optional)

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

target string  (optional)

Where the source should appear in the environment.

type enum (string)  (optional)

No description provided.

Possible values:

  • gcs

    A Cloud Storage bucket.

  • inline

    Inline content.

  • repository

    A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

status enum (string)  (optional)

Output only. The status of the environment container.

Possible values:

  • active

    Output only. The status of the environment container.

  • expired

    Output only. The status of the environment container.

updated string  (optional)

Output only. The time at which the environment was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

Example Response

{
  "created": "string",
  "file_count": "string",
  "id": "string",
  "last_accessed": "string",
  "network": {
    "allowlist": [
      {
        "domain": "github.com",
        "transform": [
          {
            "Authorization": "Bearer your-token"
          }
        ]
      },
      {
        "domain": "*.googleapis.com"
      }
    ]
  },
  "size_bytes": "string",
  "sources": [
    {
      "content": "string",
      "encoding": "string",
      "source": "string",
      "target": "string",
      "type": "gcs"
    }
  ],
  "status": "active",
  "updated": "string"
}

DeleteEnvironment

delete https://generativelanguage.googleapis.com/v1beta/environments/{id}

Deletes an environment.

Response

If successful, the response is empty.

Example

Resources

Environment

An execution environment for an agent.

Fields

created string  (optional)

Output only. The time at which the environment was created in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

file_count string  (optional)

Output only. The number of files in the environment, output only.

id string  (optional)

Required. Output only. The ID of the environment.

last_accessed string  (optional)

Output only. The time at which the environment was last accessed in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

network EnvironmentNetworkEgressAllowlist or enum (string)  (optional)

Network configuration for the environment.

Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.

Possible Types

object

Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.

allowlist array (AllowlistEntry)  (optional)

List of allowed outbound domains. Only requests to listed domains are permitted. Use [{'domain': '*'}] to allow all domains while still injecting headers on specific ones.

A single domain allowlist rule with optional header injection.

Fields

domain string  (optional)

Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

transform array (object) or object  (optional)

Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.

string

Turns all network off.

Possible values

  • disabled

    Turns all network off.

size_bytes string  (optional)

Output only. The total size of the environment files in bytes, output only.

sources array (Source)  (optional)

Sources to be mounted into the environment.

A source to be mounted into the environment.

Fields

content string  (optional)

The inline content if `type` is `INLINE`.

encoding string  (optional)

Optional encoding for inline content (e.g. `base64`).

source string  (optional)

The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

target string  (optional)

Where the source should appear in the environment.

type enum (string)  (optional)

No description provided.

Possible values:

  • gcs

    A Cloud Storage bucket.

  • inline

    Inline content.

  • repository

    A generic repository. The protocol prefix in the source URL identifies the provider (e.g., github://, gcs://).

status enum (string)  (optional)

Output only. The status of the environment container.

Possible values:

  • active

    Output only. The status of the environment container.

  • expired

    Output only. The status of the environment container.

updated string  (optional)

Output only. The time at which the environment was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).