Skip to main content

Prompt Fragments

A fragment is a named block of template text that profiles pull in with {{template "fragment_id" .}}. Use it for text repeated across profiles — safety rules, tone, a shared preamble — so one edit reaches every profile that includes it.

Fragments live in the same project as profiles and use the same authentication: a secret key on its own, no X-On-Behalf-Of.

Create a Fragment​

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/create \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "fragment": {
      "fragmentId": "safety",
      "name": "Safety rules",
      "content": "Never give medical advice. Refer the user to a clinician when asked."
    }
  }'

Response:

{
  "fragment": {
    "fragmentId": "safety",
    "name": "Safety rules",
    "content": "Never give medical advice. Refer the user to a clinician when asked."
  }
}

fragmentId must be unique within the project — it is the name you write in {{template "safety" .}}.

Then include it from a profile's system prompt, via POST /api/v1/agent-profiles/update:

{
  "profileId": "nutrition_coach",
  "profile": {
    "generationConfig": {
      "systemPrompt": "{{template \"safety\" .}}\n\nYou are a nutrition coach for {{.userName}}."
    }
  },
  "updateMask": "generationConfig.systemPrompt"
}

content may itself contain {{.variable}} placeholders and nested {{template "id" .}} includes.

Read and List​

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/get \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"fragmentId": "safety"}'

Response: {"fragment": {...}}.

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/list \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "pageSize": 25}'

Response:

{
  "fragments": [
    {"fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice…"}
  ],
  "totalCount": 1,
  "hasMore": false,
  "setVersion": 7
}

setVersion is the thing to notice — see below.

Update a Fragment​

Partial update via updateMask, the same semantics as profile update.

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/update \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "fragmentId": "safety",
    "fragment": {
      "content": "Never give medical or dosage advice. Refer the user to a clinician."
    },
    "updateMask": "content"
  }'

Response: {"fragment": {...}}.

The change reaches every profile that includes this fragment on their next turn, and bumps the project-wide fragment-set version. There is no per-profile rollout.

Set Versions​

Fragments are versioned as a set, not individually: any fragment write bumps one project-wide setVersion, reported by prompt-fragments/list. Record that number alongside a turn and you can reconstruct the exact prompt text later.

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/get-set \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"setVersion": 7}'

Response: every fragment as it existed at that version, ordered by fragmentId.

{
  "setVersion": 7,
  "fragments": [
    {"fragmentId": "safety", "name": "Safety rules", "content": "Never give medical advice…"},
    {"fragmentId": "tone", "name": "Tone", "content": "Warm, direct, no filler."}
  ]
}

A profile version tells you what its own prompt looked like; the fragment-set version tells you what the blocks it included looked like. You need both to reconstruct a past turn's prompt — which is why the two version numbers are worth storing together with a trace.

setVersion is 0 when no fragment has ever been written in the project.

Delete a Fragment​

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/delete \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"fragmentId": "safety"}'

Response: empty body on success.

Deleting does not rewrite the profiles that include it

Rendering fails soft, not loudly: the system prompt is sent unrendered, so the literal {{template "safety" .}} text reaches the model. The turn succeeds, the output degrades, and nothing errors.

Check what references a fragment before removing it — agent-profiles/list returns full records, so grep the returned generationConfig.systemPrompt values for the id.

  • Agent Profiles — the profiles that include these fragments
  • Import — converting an @include-based library into fragments in one call