# Environments

Environments let you run different versions of a flow in different contexts — so you can iterate on prompts in development without affecting production traffic.

## How it works

Each flow maintains an `ActiveVersions` map:

```json
{
  "development": "67a1b2c3d4e5f6a7b8c9d0e1",
  "staging": "67a1b2c3d4e5f6a7b8c9d0e2",
  "production": "67a1b2c3d4e5f6a7b8c9d0e3"
}
```

When you execute a flow with `"environment": "production"`, PromptShuttle resolves to the version ID pinned to that environment.

## Creating environments

Environments are tenant-level resources. Create them once and use them across all flows.

```bash
POST /api/v1/environments
```

```json
{ "name": "production" }
```

Common setups:

* Simple: `development`, `production`
* Standard: `development`, `staging`, `production`
* Custom: any names you choose (e.g. `canary`, `eu-prod`)

## Activating a version

To pin a version to an environment:

```bash
POST /api/v1/flows/{flowId}/versions/{versionId}/environments
```

```json
{
  "environment": "production",
  "comment": "Improved billing handler prompt"
}
```

Once activated, the version becomes read-only. Fork it to make further changes.

## Promoting versions

You can promote all active versions from one environment to another in bulk — for example, promoting everything in `staging` to `production`.

### Diff first

Before promoting, check what will change:

```bash
GET /api/v1/environments/diff?sourceEnvironment=staging&targetEnvironment=production
```

Returns a list of flows with their current version in each environment, so you can review before promoting.

### Promote

```bash
POST /api/v1/environments/promote
```

```json
{
  "sourceEnvironment": "staging",
  "targetEnvironment": "production",
  "flowIds": ["flow_id_1", "flow_id_2"],
  "comment": "March release"
}
```

If `flowIds` is omitted, all flows with an active version in the source environment are promoted.

## Environment in API requests

### Flow execution

Pass the environment name when running a flow:

```bash
POST /api/v1/flows/my_flow/runs
```

```json
{
  "environment": "production",
  "parameters": { ... }
}
```

If no environment is specified, the first environment in the flow's `ActiveVersions` is used.

### OpenAI endpoint

Requests through the OpenAI-compatible endpoint are logged with the environment `"OpenAI"`. The OpenAI endpoint does not use flow versions — it routes directly to the specified model.

### Direct inference

The inference endpoint accepts an optional `environment` field for logging and analytics segmentation, but it doesn't affect model selection (since there's no flow/template involved).

## Filtering by environment

The invocation log and statistics endpoints support filtering by environment, so you can:

* Track production usage separately from development testing
* Monitor costs per environment
* Compare performance across environments