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

# Publishing overview

> Ship changes with environments. Edit a draft, publish it live, clone one to work in isolation, merge it back, and split traffic between versions.

An environment is a copy of your agent with its own draft and its own live
version. Publishing promotes the draft; until you do, nothing you change
reaches users.

These endpoints let you work in an environment of your own, merge it back when
it is ready, and route a share of real traffic to it to compare two versions
against each other.

## Endpoints

### Environment

| Endpoint | Description |
| - | - |
| GET [List environments](https://www.voiceflow.com/docs/api-reference/environment/list-environments.md) | List all environments by project ID. |
| PUT [Merge environments](https://www.voiceflow.com/docs/api-reference/environment/merge-environments.md) | Merge one environment into another. |
| PUT [Update traffic split](https://www.voiceflow.com/docs/api-reference/environment/update-traffic-split.md) | Update the percentage of traffic routed to each environment. |
| GET [Get environment](https://www.voiceflow.com/docs/api-reference/environment/get-environment.md) | Get an environment by alias or ID. |
| PATCH [Update environment](https://www.voiceflow.com/docs/api-reference/environment/update-environment.md) | Update a environment by alias or ID. |
| DELETE [Delete environment](https://www.voiceflow.com/docs/api-reference/environment/delete-environment.md) | Delete an environment by alias or ID. |
| GET [Export environment](https://www.voiceflow.com/docs/api-reference/environment/export-environment.md) | Export all data from environment. |
| PUT [Compile environment](https://www.voiceflow.com/docs/api-reference/environment/compile-environment.md) | Compile an environment. |
| POST [Clone environment](https://www.voiceflow.com/docs/api-reference/environment/clone-environment.md) | Clone an environment. |
| POST [Publish environment](https://www.voiceflow.com/docs/api-reference/environment/publish-environment.md) | Publish live version of an environment. |

## Draft and published

Every environment holds two versions of the agent. The **draft** is what you
edit and what `version: "draft"` runs when you
[send a conversation](https://www.voiceflow.com/docs/api-reference/sections/running-agents.md). The **published** version is
what real traffic reaches. Publishing promotes the draft to published; nothing
you change before that is visible to users.

New projects start with a single environment called `main`. Passing an alias
the project does not have returns `400 invalid environment tag`, so list them
first if you are not sure:

```bash theme={null}
curl "https://realtime-api.voiceflow.com/v1/stable/environment?projectID=$VF_PROJECT_ID" \
  -H "Authorization: Bearer $VF_PAT"
```

## Working with more than one

* **Clone** copies an existing environment into a new one. This is how you get
  a second environment to build against without touching `main`.
* **Merge** folds one environment's changes back into another.
* **Publish** promotes an environment's draft to its published version.
* **Update traffic split** routes a share of live conversations to a different
  environment, which is how you run one version against another on real
  traffic.
* **Export** returns the environment as JSON, for backup or for inspecting a
  build outside Voiceflow.
* **Compile** builds the environment without publishing it, so you can surface
  errors before users would.

## Secrets

Secret values are environment-scoped, so the same secret name can hold a test
value in one environment and a production value in another. They are not
managed through the environment endpoints today.

## Where to go next

After publishing, [watch what happens](https://www.voiceflow.com/docs/api-reference/sections/observe.md) in the
transcripts, and [measure it](https://www.voiceflow.com/docs/api-reference/sections/insights.md).


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