# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.promptshuttle.com/flows/environments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.