> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments SDK Reference

> SDK reference for the Environments API, available in Node.js and Python.

## Environments

### List Environments

Returns environments visible to the caller. When project\_id is set, the result contains project-owned environments plus workspace environments shared with that project. When project\_id is omitted, the result contains workspace-owned environments.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.environments.list()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.environments.list();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "project_id": Optional[str],
        "search": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      projectId?: string;
      search?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "data": [{
            "id": str,
            "slug": str,
            "display_name": str,
            "description": str,
            "created_at": str,
            "created_by_id": str,
            "updated_at": str,
            "updated_by_id": str,
            "project_id": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
        }],
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        slug: string;
        displayName: string;
        description: string;
        createdAt: Date;
        createdById: string;
        updatedAt: Date;
        updatedById: string;
        projectId?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
      }[];
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create an Environment

Creates either a project-owned environment or a workspace-owned environment with sharing. Exactly one scope must be provided.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.environments.create(slug="<value>", display_name="Production", project_id="<project_id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.environments.create({
      slug: "<value>",
      displayName: "Production",
      projectId: "<project_id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "slug": str,  # required
        "display_name": str,  # required
        "description": Optional[str],
        "project_id": Optional[str],
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      slug: string;  // required
      displayName: string;  // required
      description?: string;
      projectId?: string;
      sharing?: {
        allProjects?: Record<string, unknown>;
        selected?: {
          projectIds?: string[];
        };
        allowVersionPin?: boolean;
        allowFork?: boolean;
        autoGrantNewProjects?: boolean;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "environment": {
            "id": str,
            "slug": str,
            "display_name": str,
            "description": str,
            "created_at": str,
            "created_by_id": str,
            "updated_at": str,
            "updated_by_id": str,
            "project_id": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      environment: {
        id: string;
        slug: string;
        displayName: string;
        description: string;
        createdAt: Date;
        createdById: string;
        updatedAt: Date;
        updatedById: string;
        projectId?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve an Environment

Retrieves a visible environment by ID.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.environments.get(environment_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.environments.get({
      environmentId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "environment_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      environmentId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "environment": {
            "id": str,
            "slug": str,
            "display_name": str,
            "description": str,
            "created_at": str,
            "created_by_id": str,
            "updated_at": str,
            "updated_by_id": str,
            "project_id": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      environment: {
        id: string;
        slug: string;
        displayName: string;
        description: string;
        createdAt: Date;
        createdById: string;
        updatedAt: Date;
        updatedById: string;
        projectId?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete an Environment

Permanently deletes an environment.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.environments.delete(environment_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.environments.delete({
      environmentId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "environment_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      environmentId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Update an Environment

Updates environment metadata. Scope is immutable; sharing may only be updated on workspace-owned environments.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.environments.update(environment_id="<id>", display_name="Staging")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.environments.update({
      environmentId: "<id>",
      updateEnvironmentRequest: {
        displayName: "Staging",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "environment_id": str,  # required
        "display_name": Optional[str],
        "description": Optional[str],
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      environmentId: string;  // required
      updateEnvironmentRequest: {  // required
        displayName?: string;
        description?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "environment": {
            "id": str,
            "slug": str,
            "display_name": str,
            "description": str,
            "created_at": str,
            "created_by_id": str,
            "updated_at": str,
            "updated_by_id": str,
            "project_id": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      environment: {
        id: string;
        slug: string;
        displayName: string;
        description: string;
        createdAt: Date;
        createdById: string;
        updatedAt: Date;
        updatedById: string;
        projectId?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.