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:

{
  "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.

POST /api/v1/environments

{ "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:

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

{
  "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:

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

POST /api/v1/environments/promote

{
  "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:

POST /api/v1/flows/my_flow/runs

{
  "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