<!-- disableFinding(G3DOC_JINJA) -->
<!-- disableFinding(HEADING_FUNCTION) -->
<!-- disableFinding(LINE_OVER_80) -->
<!-- disableFinding(SPACES) -->


# Gemini Environments API

Note: This API is in Beta. Endpoints are under `/v1beta/`.

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

## Environments

### CreateEnvironment

`POST https://generativelanguage.googleapis.com/v1beta/environments`

Creates an environment.


#### Request Body
- **network** (`EnvironmentNetworkEgressAllowlist or enum (string)`) Network configuration for the environment.
  Possible values:
  - `disabled`: Turns all network off.

- **sources** (`array (Source)`) Sources to be mounted into the environment.
  - **content** (`string`)   The inline content if `type` is `INLINE`.

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

  - **source** (`string`)   The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

  - **target** (`string`)   Where the source should appear in the environment.

  - **type** (`enum (string)`)
    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
- **created** (`string`) Output only. The time at which the environment was created in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

- **file_count** (`string`) Output only. The number of files in the environment, output only.

- **id** (`string`) Required. Output only. The ID of the environment.

- **last_accessed** (`string`) 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)`) Network configuration for the environment.
  Possible values:
  - `disabled`: Turns all network off.

- **size_bytes** (`string`) Output only. The total size of the environment files in bytes, output only.

- **sources** (`array (Source)`) Sources to be mounted into the environment.
  - **content** (`string`)   The inline content if `type` is `INLINE`.

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

  - **source** (`string`)   The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

  - **target** (`string`)   Where the source should appear in the environment.

  - **type** (`enum (string)`)
    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)`) 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`) Output only. The time at which the environment was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).


#### Examples
**Create Environment**

**REST**

```sh
curl -X POST https://generativelanguage.googleapis.com/v1beta/environments \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{
      "type": "inline",
      "target": "main.py",
      "content": "print(\"Hello, World!\")"
    }]
  }'
```
**Python**

```python
from google import genai

client = genai.Client()
environment = client.environments.create(
    sources=[{
        "type": "inline",
        "target": "main.py",
        "content": "print('Hello, World!')",
    }]
)
print(environment.id)

```
**JavaScript**

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const environment = await ai.environments.create({
    sources: [{
        type: 'inline',
        target: 'main.py',
        content: "print('Hello, World!')",
    }],
});
if (!environment.id) {
    throw new Error('Environment creation failed: ID is undefined');
}
console.log(environment.id);

```
**Java**

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.CreateEnvironmentRequest;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import java.util.List;

Client client = new Client();
CreateEnvironmentRequest request = CreateEnvironmentRequest.builder()
    .sources(List.of(Source.builder()
        .type(SourceType.INLINE)
        .target("main.py")
        .content("print('Hello, World!')")
        .build()))
    .build();
Environment environment = client.environments.createEnvironment(request).environment().orElseThrow();
System.out.println(environment.id().orElse(""));

```
Response:
```json
{
  "created": "2026-08-19T00:00:00Z",
  "id": "env_abc123",
  "last_accessed": "2026-08-19T00:00:00Z",
  "sources": [
    {
      "type": "inline",
      "content": "print('Hello, World!')",
      "target": "main.py"
    }
  ],
  "status": "active",
  "updated": "2026-08-19T00:00:00Z"
}
```
---
### ListEnvironments

`GET https://generativelanguage.googleapis.com/v1beta/environments`

Lists environments.

#### Parameters
- **page_size** (`integer`) Optional. Maximum number of environments to return.\nIf unspecified, defaults to 50. Maximum is 1000.

- **page_token** (`string`) Optional. Pagination token.


#### Response
- **environments** (`array (<a href="#Resource:Environment">Environment</a>)`) Environments belonging to the provided project.

- **next_page_token** (`string`) Pagination token.


#### Examples
**List Environments**

**REST**

```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/environments \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
**Python**

```python
from google import genai

client = genai.Client()
response = client.environments.list()
for environment in response.environments or []:
    print(environment.id)
```
**JavaScript**

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});
const response = await ai.environments.list();
for (const env of (response.environments ?? [])) {
    console.log(env.id);
}
```
**Java**

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.operations.ListEnvironmentsResponse;
import java.util.List;

Client client = new Client();
ListEnvironmentsResponse response = client.environments.listEnvironmentsDirect();
for (Environment env : response.listEnvironmentsResponse().flatMap(res -> res.environments()).orElse(List.of())) {
    System.out.println(env.id().orElse(""));
}
```
Response:
```json
{
  "environments": [
    {
      "created": "2026-08-19T00:00:00Z",
      "id": "env_abc123",
      "last_accessed": "2026-08-19T00:00:00Z",
      "status": "active",
      "updated": "2026-08-19T00:00:00Z"
    }
  ]
}
```
---
### GetEnvironmentFiles

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

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
- **page_size** (`integer`) Optional. Maximum number of entries to return per page (for directory listing).

- **page_token** (`string`) Optional. Pagination token for directory listing.

- **recursive** (`boolean`) Optional. If true and the path is a directory, recursively lists all files.


#### Response
- **files** (`array (EnvironmentFile)`) 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`).
  - **created** (`string`)   Output only. The creation time of the file/directory.

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

  - **modified** (`string`)   Output only. The modification time of the file/directory.

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

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

  - **size_bytes** (`string`)   Output only. The size of the file/directory in bytes. NOLINT

  - **type** (`enum (string)`)   Output only. The type of the entry.
    Possible values:
    - `file`: A regular file.
    - `directory`: A directory.


- **next_page_token** (`string`) Pagination token for directory listing. NOLINT


#### Examples
**List Files in Environment**

**REST**

```sh
curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/src' \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
**Python**

```python
from google import genai

client = genai.Client()


response = client.environments.files.list(
    environment=created.id,
    path="src",
)
for file in response.files or []:
    print(file.name, file.type, file.size_bytes)

```
**JavaScript**

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const response = await ai.environments.files.list({
    environment: created.id,
    path: 'src',
});
for (const file of (response.files ?? [])) {
    console.log(file.name, file.type, file.size_bytes);
}

```
**Java**

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.CreateEnvironmentRequest;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.environments.EnvironmentFile;
import com.google.genai.gaos.models.environments.GetEnvironmentFilesResponse;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.GetEnvironmentFilesRequest;
import java.util.List;

Client client = new Client();


com.google.genai.gaos.models.operations.GetEnvironmentFilesResponse response = client.environments.files().list(
    GetEnvironmentFilesRequest.builder()
        .environment(envId)
        .path("src")
        .build());
GetEnvironmentFilesResponse filesResponse = response.getEnvironmentFilesResponse().orElseThrow();
for (EnvironmentFile file : filesResponse.files().orElse(List.of())) {
    System.out.println(file.name().orElse("") + " " + file.type().map(Object::toString).orElse("") + " " + file.sizeBytes().orElse(""));
}

```
Response:
```json
{
  "files": [
    {
      "name": "src",
      "type": "directory",
      "created": "2026-08-19T00:00:00Z",
      "modified": "2026-08-19T00:00:00Z",
      "path": "src"
    },
    {
      "name": "main.py",
      "type": "file",
      "created": "2026-08-19T00:00:00Z",
      "mime_type": "text/x-python",
      "modified": "2026-08-19T00:00:00Z",
      "path": "main.py",
      "size_bytes": "22"
    }
  ]
}
```
**Get File Metadata**

**REST**

```sh
curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/main.py' \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
**Python**

```python
from google import genai

client = genai.Client()


response = client.environments.files.get(
    environment=created.id,
    path="main.py",
)
for file in response.files or []:
    print(file.name, file.size_bytes)

```
**JavaScript**

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const response = await ai.environments.files.list({
    environment: created.id,
    path: 'main.py',
});
for (const file of (response.files ?? [])) {
    console.log(file.name, file.size_bytes);
}

```
**Java**

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.CreateEnvironmentRequest;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.environments.EnvironmentFile;
import com.google.genai.gaos.models.environments.GetEnvironmentFilesResponse;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.GetEnvironmentFilesRequest;
import java.util.List;

Client client = new Client();


com.google.genai.gaos.models.operations.GetEnvironmentFilesResponse response = client.environments.files().list(
    GetEnvironmentFilesRequest.builder()
        .environment(envId)
        .path("main.py")
        .build());
GetEnvironmentFilesResponse filesResponse = response.getEnvironmentFilesResponse().orElseThrow();
for (EnvironmentFile file : filesResponse.files().orElse(List.of())) {
    System.out.println(file.name().orElse("") + " " + file.sizeBytes().orElse(""));
}

```
Response:
```json
{
  "files": [
    {
      "name": "main.py",
      "type": "file",
      "created": "2026-08-19T00:00:00Z",
      "mime_type": "text/x-python",
      "modified": "2026-08-19T00:00:00Z",
      "path": "main.py",
      "size_bytes": "22"
    }
  ]
}
```
**Download File Content**

**REST**

```sh
curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/src/main.py?alt=media' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --output main.py
```
**Python**

```python
from google import genai

client = genai.Client()


content = client.environments.files.download(
    environment=created.id,
    path="src/main.py",
)
print(content.decode("utf-8"))

```
Response:
```json
{
  "files": [
    {
      "name": "main.py",
      "type": "file",
      "mime_type": "text/x-python",
      "path": "main.py",
      "size_bytes": "22"
    }
  ]
}
```
---
### GetEnvironment

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

Gets an environment.


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

- **file_count** (`string`) Output only. The number of files in the environment, output only.

- **id** (`string`) Required. Output only. The ID of the environment.

- **last_accessed** (`string`) 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)`) Network configuration for the environment.
  Possible values:
  - `disabled`: Turns all network off.

- **size_bytes** (`string`) Output only. The total size of the environment files in bytes, output only.

- **sources** (`array (Source)`) Sources to be mounted into the environment.
  - **content** (`string`)   The inline content if `type` is `INLINE`.

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

  - **source** (`string`)   The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

  - **target** (`string`)   Where the source should appear in the environment.

  - **type** (`enum (string)`)
    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)`) 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`) Output only. The time at which the environment was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).


#### Examples
**Get Environment**

**REST**

```sh
curl -X GET https://generativelanguage.googleapis.com/v1beta/environments/env_abc123 \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
**Python**

```python
from google import genai

client = genai.Client()


environment = client.environments.get(id=created.id)
print(environment.id)

```
**JavaScript**

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


const environment = await ai.environments.get(created.id);
console.log(environment.id);

```
**Java**

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.CreateEnvironmentRequest;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import java.util.List;

Client client = new Client();


Environment environment = client.environments.getEnvironment(envId).environment().orElseThrow();
System.out.println(environment.id().orElse(""));

```
Response:
```json
{
  "created": "2026-08-19T00:00:00Z",
  "id": "env_abc123",
  "last_accessed": "2026-08-19T00:00:00Z",
  "sources": [
    {
      "type": "inline",
      "content": "print('Hello, World!')",
      "target": "main.py"
    }
  ],
  "status": "active",
  "updated": "2026-08-19T00:00:00Z"
}
```
---
### DeleteEnvironment

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

Deletes an environment.


#### Response

#### Examples
**Delete Environment**

**REST**

```sh
curl -X DELETE https://generativelanguage.googleapis.com/v1beta/environments/env_abc123 \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
**Python**

```python
from google import genai

client = genai.Client()


client.environments.delete(id=created.id)
print("Environment deleted successfully.")
```
**JavaScript**

```javascript
import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});


await ai.environments.delete(created.id);
console.log('Environment deleted successfully.');
```
**Java**

```java
import com.google.genai.Client;
import com.google.genai.gaos.models.environments.CreateEnvironmentRequest;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import java.util.List;

Client client = new Client();


client.environments.deleteEnvironment(envId);
System.out.println("Environment deleted successfully.");
```
---

## Resources
### Environment { #Resource:Environment }
An execution environment for an agent.

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

- **file_count** (`string`) Output only. The number of files in the environment, output only.

- **id** (`string`) *(Required)* Required. Output only. The ID of the environment.

- **last_accessed** (`string`) 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)`) Network configuration for the environment.
  Possible values:
  - `disabled`: Turns all network off.

- **size_bytes** (`string`) Output only. The total size of the environment files in bytes, output only.

- **sources** (`array (Source)`) Sources to be mounted into the environment.
  - **content** (`string`)   The inline content if `type` is `INLINE`.

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

  - **source** (`string`)   The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

  - **target** (`string`)   Where the source should appear in the environment.

  - **type** (`enum (string)`)
    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)`) 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`) Output only. The time at which the environment was last updated in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).


**JSON Representation:**
```json
{
  "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"
}
```