e-volv
Contents

Prompts

A prompt has a name, numbered versions and labels. A label, such as production or staging, points at one version, and an agent asks for the prompt by name and label. Moving a label is how a prompt change ships: no deploy, live within a minute.

Templates

{{name}} placeholders and nothing more: no conditionals, no loops, no expressions, so any SDK can fill one with a string replace. A variable with no value is left as written, so a missing one is visible in the output rather than silently empty.

Fetching a prompt

shell
curl -s "https://api.e-volv.io/api/public/v1/prompts/summarise?label=production" \
  -H "Authorization: Bearer evk_..."
json
{
  "name": "summarise",
  "label": "production",
  "version": 7,
  "template": "Summarise {{ticket}} for {{audience}}.",
  "variables": ["ticket", "audience"],
  "modelSettings": { "model": "gpt-5-mini", "temperature": 0.2 }
}

label defaults to production. The key needs the prompts:read scope; an Observer key with logs:read also works.

Caching

Every response carries an ETag for the version it served and may be cached for sixty seconds. Send the tag back in If-None-Match and an unchanged prompt answers 304 with no body, so fetching on every call costs almost nothing.

shell
curl -s -o /dev/null -w "%{http_code}" \
  "https://api.e-volv.io/api/public/v1/prompts/summarise?label=production" \
  -H "Authorization: Bearer evk_..." \
  -H 'If-None-Match: "<the ETag from the last response>"'
# 304 while the label still points at the same version

Rolling a version out by segment

A prompt can be tied to an e-volv Launch flag. Pass subject (a user or account id) on the fetch; when the flag evaluates true for that subject, the candidate label is served instead of the one asked for. The rollout is then targeted like any other flag.

If the flag cannot be evaluated, the label you asked for is served. A flag being away is never a reason to serve no prompt.

Versions and runs

Spans that carry evolv.prompt.name and evolv.prompt.version are joined to the version, so each version shows the cost and score of the runs that used it. Set the two attributes on your agent span when you fetch the prompt.