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

# Create environment

`POST /environment`

## Request

- Base URL: `https://api.braintrust.dev`
- URL: `https://api.braintrust.dev/environment`
- Auth: one of:
  - HTTP bearer
  - none

Create a new environment

## Request body

- CreateEnvironment
  - `name` string, required: Name of the environment
  - `slug` string, required: A url-friendly, unique identifier for the environment within an organization
  - `description` string, nullable: Textual description of the environment
  - `org_name` string, nullable: For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the environment belongs in.

## Response `200`

Created environment

- Environment
  - `id` string, uuid, required: Unique identifier for the environment
  - `org_id` string, uuid, required: Unique identifier for the organization that the environment belongs under
  - `name` string, required: Name of the environment
  - `slug` string, required: A url-friendly, unique identifier for the environment within an organization
  - `description` string, nullable: Textual description of the environment
  - `created` string, date-time, nullable: Date of environment creation
  - `deleted_at` string, date-time, nullable: Date of environment deletion, or null if the environment is still active

## Other responses

- `400`: The request was unacceptable, often due to missing a required parameter
- `401`: No valid API key provided
- `403`: The API key doesn’t have permissions to perform the request
- `429`: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500`: Something went wrong on Braintrust's end. (These are rare.)

## Changes

- **2026-10-30** `8f5039399f77`: 2 breaking
  - the request property `description` became not nullable
  - the request property `org_name` became not nullable
- **2026-03-04** `79e3efbd784c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/environment/post.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) - [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braintrustdata/apis/braintrust-api/revisions/19184ec94018?raw)