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

# Environments

> Isolate dev, staging, and production workloads inside an organization.

An environment is a boundary inside an organization that holds tenants and API keys. Use separate environments to keep dev, staging, and production data — and their keys — apart. Environment administration is a dashboard operation, so every endpoint here requires a **user session**.

<Note>
  All endpoints on this page are **\[User]** — they require a signed-in user session and are not available to API keys.
</Note>

<Warning>
  An **API key is bound to a single environment** and can never reach another. Create at least one key per environment you run against. See [Authentication](/developers/authentication#key-prefixes).
</Warning>

## Endpoints

| Method   | Path                    | Description                          | Auth    |
| -------- | ----------------------- | ------------------------------------ | ------- |
| `GET`    | `/environments?org_id=` | List environments in an organization | \[User] |
| `POST`   | `/environments`         | Create an environment                | \[User] |
| `GET`    | `/environments/:id`     | Get an environment                   | \[User] |
| `PATCH`  | `/environments/:id`     | Update an environment                | \[User] |
| `DELETE` | `/environments/:id`     | Delete an environment                | \[User] |

***

### List environments

`GET /environments`

Lists the environments in an organization, each with a count of the tenants it contains.

<ParamField query="org_id" type="string" required>
  The organization whose environments to list.
</ParamField>

```bash theme={null}
curl "https://api.autosage.ai/api/v1/environments?org_id=ORG_ID" \
  -H "Cookie: YOUR_SESSION_COOKIE"
```

***

### Create an environment

`POST /environments`

Creates a new environment in an organization.

<ParamField body="org_id" type="string" required>
  The organization to create the environment in.
</ParamField>

<ParamField body="name" type="string" required>
  Display name for the environment.
</ParamField>

<ParamField body="type" type="string" required>
  Environment type — one of `dev`, `staging`, `production`, `custom`, or `personal`. The type determines the prefix of keys created in it (`sk_live_` for `production`/`personal`, `sk_test_` otherwise).
</ParamField>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/environments" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "ORG_ID",
    "name": "Production",
    "type": "production"
  }'
```

<Note>
  Only administrative roles (`owner`, `billing_admin`) may create environments.
</Note>

***

### Get an environment

`GET /environments/:id`

Returns a single environment, including counts of the tenants and API keys it contains.

<ParamField path="id" type="string" required>
  The environment ID.
</ParamField>

***

### Update an environment

`PATCH /environments/:id`

Updates any supplied mutable field.

<ParamField path="id" type="string" required>
  The environment ID.
</ParamField>

<ParamField body="name" type="string">
  New display name.
</ParamField>

<ParamField body="type" type="string">
  New environment type — `dev`, `staging`, `production`, `custom`, or `personal`. Future keys created in the environment use the prefix associated with this type.
</ParamField>

<ParamField body="status" type="string">
  `active` or `inactive`.
</ParamField>

<Note>
  Only administrative roles may update an environment.
</Note>

***

### Delete an environment

`DELETE /environments/:id`

Permanently deletes an environment and the tenants, keys, and content within it.

<ParamField path="id" type="string" required>
  The environment ID.
</ParamField>

<Warning>
  Only the `owner` may delete an environment. This is irreversible.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Tenancy" icon="sitemap" href="/developers/concepts/tenancy">
    See how environments, tenants, and keys fit together.
  </Card>

  <Card title="Tenants" icon="box" href="/developers/api/tenants">
    Provision tenants inside an environment.
  </Card>

  <Card title="API keys" icon="key" href="/developers/api/api-keys">
    Create keys scoped to this environment.
  </Card>
</CardGroup>