Engineering Workspace

Prompts

Versioned prompt management for the Engineering workspace. Create prompts, keep history, label environments, roll back versions, and evaluate candidates in Lab.

Python SDK

client.prompts covers the full lifecycle, fetch by key/label, create versions, label, archive, and carry prompt lineage into your sessions:

python
from stimulir import StimulirClient

client = StimulirClient()
prompt = client.prompts.get("customer.chat.agent", label="prod")

client.prompts.create_version(
    "customer.chat.agent",
    content=open("prompts/customer_chat_agent.md").read(),
    label="prod",
    change_notes="Tightened scoring rubric",
)

Full reference on the Python SDK page.

CLI

stimulir prompts wraps the endpoints below. Same auth as the rest of the CLI, your active workspace is implicit.

bash
# List prompts (add --json for raw output)
stimulir prompts list

# Fetch the active/latest version, a label, or a fixed version
stimulir prompts get <key> [--label prod|--version N]

# Show the full version history for a prompt
stimulir prompts versions <key>

# Save a prompt (or a new version), content from --file or stdin
stimulir prompts create --key <key> --file ./prompt.md --label prod --notes "rev a"

# Update metadata without mutating prompt content
stimulir prompts update <key> <version> --notes "eval passed"

# Move a label onto a specific version (promote or roll back)
stimulir prompts label <key> <version> <label>

# Archive an inactive prompt version
stimulir prompts archive <key> <version>

# Evaluate a prompt version against staged data in Lab
stimulir lab eval create-run --prompt <key>:<version> --data-asset-id <asset-id> --execute

Endpoints

GET/api/v1/workspace/prompts
GET/api/v1/workspace/prompts/{key}
GET/api/v1/workspace/prompts/{key}/versions
POST/api/v1/workspace/prompts
PUT/api/v1/workspace/prompts/{key}/{version}/label
PATCH/api/v1/workspace/prompts/{key}/{version}
DELETE/api/v1/workspace/prompts/{key}/{version}

Platform endpoints authenticate with your session token and the X-Business-Profile-Id header.

List prompts

GET/api/v1/workspace/prompts

Returns the prompts in the active workspace, each identified by a stable key.

List versions

GET/api/v1/workspace/prompts/{key}
GET/api/v1/workspace/prompts/{key}/versions

Fetch a prompt by key plus label/version, or return the full version history. Every save creates a new immutable version, so you can audit what changed and roll a label back to an earlier one.

Create a prompt

POST/api/v1/workspace/prompts

Creates a new prompt (or a new version of an existing key) in the workspace.

Label a version

PUT/api/v1/workspace/prompts/{key}/{version}/label
PATCH/api/v1/workspace/prompts/{key}/{version}
DELETE/api/v1/workspace/prompts/{key}/{version}

Move a label, for example the one your application reads at runtime, onto a specific version. Metadata can be updated in place, but prompt content stays immutable; create a new version to edit the body. Archiving marks a version inactive without deleting its lineage.

Evaluate prompt versions

POST/api/v1/lab/evals/runs

Prompt versions can be evaluated in Lab alongside staged datasets, trace snapshots, model endpoints, and adapter candidates. Pass a prompt ref by key plus either version or label; the eval run stores the prompt lineage before execution starts.

bash
# Evaluate the staging label
stimulir lab eval create-run --prompt <key>:staging --data-asset-id <asset-id> --execute

# Evaluate a fixed version
stimulir lab eval create-run --prompt <key>:3 --data-asset-id <asset-id>