---
title: "Create an environment"
method: POST
path: "/v3/environments"
tags: ["Environments"]
---

# Create an environment

`POST /v3/environments`

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

## Request body

- CreateEnvironmentRequest
  - `slug` string, required
  - `display_name` string, required
  - `description` string
  - `project_id` string
  - `sharing` Sharing — Sharing controls which projects in the workspace may use this entity and what they may do with it.
    - `all_projects` SharingAllProjects
    - `selected` SharingSelectedProjects
      - `project_ids` string[] — Projects allowed to use the entity. An empty list shares it with no project.
    - `allow_version_pin` boolean — Consuming projects may pin a specific version instead of tracking latest. Enforcement lives with the consuming reference.
    - `allow_fork` boolean — Projects may duplicate this entity into a detached project-owned copy.
    - `auto_grant_new_projects` boolean — New projects created after this sharing config is applied should receive access automatically. Enforcement lives with project creation and entity-specific adoption code.

## Response `200`

OK

- CreateEnvironmentResponse
  - `environment` Environment, required
    - `id` string, required — Unique environment ID in env_<ulid> form.
    - `slug` string, required — Immutable workspace-unique environment slug.
    - `display_name` string, required — Workspace-unique display name.
    - `description` string, required
    - `created_at` string, date-time, required
    - `created_by_id` string, required
    - `updated_at` string, date-time, required
    - `updated_by_id` string, required
    - `project_id` string — Project that owns this environment.
    - `sharing` Sharing — Sharing controls which projects in the workspace may use this entity and what they may do with it.
      - `all_projects` SharingAllProjects
      - `selected` SharingSelectedProjects
        - `project_ids` string[] — Projects allowed to use the entity. An empty list shares it with no project.
      - `allow_version_pin` boolean — Consuming projects may pin a specific version instead of tracking latest. Enforcement lives with the consuming reference.
      - `allow_fork` boolean — Projects may duplicate this entity into a detached project-owned copy.
      - `auto_grant_new_projects` boolean — New projects created after this sharing config is applied should receive access automatically. Enforcement lives with project creation and entity-specific adoption code.

## Changes

> 350 revisions in range; 136 not diffed.

- **2026-09-28** `3c7d859558ee` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v3/environments/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/3c7d859558ee?raw)