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

# Create Environment

> Create a new environment for your tenant

## Create Environment

```text theme={"dark"}
POST /v1/environments
```

Creates a new environment.

### Request Body

| Field          | Type    | Required | Description                                                                                      |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ |
| `name`         | string  | Yes      | Machine-friendly name. Must match `^[a-z0-9_-]+$` (lowercase alphanumeric, hyphens, underscores) |
| `display_name` | string  | No       | Human-friendly display name                                                                      |
| `description`  | string  | No       | Description of the environment                                                                   |
| `color`        | string  | No       | Hex color code for the UI (defaults to `#6366f1`)                                                |
| `is_default`   | boolean | No       | Whether this is the default environment (defaults to `false`)                                    |

### Response

Returns the created environment object.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/environments \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "staging",
      "display_name": "Staging",
      "description": "Pre-production testing",
      "color": "#f59e0b"
    }'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://api.knoxcall.com/v1/environments",
      headers={
          "Authorization": "Bearer tk_live_abc123...",
          "Content-Type": "application/json"
      },
      json={
          "name": "staging",
          "display_name": "Staging",
          "description": "Pre-production testing",
          "color": "#f59e0b"
      }
  )
  environment = resp.json()
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/environments", {
    method: "POST",
    headers: {
      Authorization: "Bearer tk_live_abc123...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "staging",
      display_name: "Staging",
      description: "Pre-production testing",
      color: "#f59e0b"
    })
  });
  const environment = await resp.json();
  ```
</CodeGroup>

### Errors

| Status | Type               | Description                                                           |
| ------ | ------------------ | --------------------------------------------------------------------- |
| 400    | `validation_error` | Invalid name format or missing required field                         |
| 403    | `plan_limit`       | Environments not available on your plan, or environment limit reached |
| 409    | `conflict`         | An environment with this name already exists                          |