> ## 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.

```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();
```

**Parameters**

```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;
}
```

**Response**

```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;
}
```

### Create an Environment

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

```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();
```

**Parameters**

```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;
  };
}
```

**Response**

```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;
    };
  };
}
```

### Retrieve an Environment

Retrieves a visible environment by ID.

```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();
```

**Parameters**

```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
}
```

**Response**

```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;
    };
  };
}
```

### Delete an Environment

Permanently deletes an environment.

```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();
```

**Parameters**

```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
}
```

### Update an Environment

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

```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();
```

**Parameters**

```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;
    };
  };
}
```

**Response**

```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;
    };
  };
}
```


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