Prompt Templates

Prompt Templates let you define a system prompt, base conversation turns, and default inference parameters once — then reference them by name from any chat completion request. Instead of hardcoding the same prompt logic in every client, you manage it centrally and inject runtime values using {{variable}} slots.

Authentication

Template management (create, read, update, delete) accepts either authentication method:

Method	How	Typical use
RSK key (`rsk_...`)	`Authorization: Bearer rsk_...`	Direct API access from your backend
Mesh Dashboard	Handled automatically	Managing templates through the dashboard UI

Using a template at inference time always uses your rsk_... key, the same as any other chat completion. See the Authentication guide for details on key types.

Creating a Template

Send a POST /v1/templates request with a name, an optional system prompt, and any variables you want to parameterize.

curl
Node.js
Python

curl https://api.meshapi.ai/v1/templates \
  -H "Authorization: Bearer <YOUR_RSK_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent",
    "description": "Customer support assistant with configurable tone",
    "system": "You are a {{tone}} support agent for {{company}}. Help users resolve their issues politely and accurately.",
    "model": "openai/gpt-4o-mini",
    "params": { "temperature": 0.5, "max_tokens": 512 },
    "variables": ["company", "tone"]
  }'

import { MeshAPI } from "meshapi-node-sdk";

const client = new MeshAPI({
  baseUrl: "https://api.meshapi.ai",
  token: "rsk_...",
});

const template = await client.templates.create({
  name: "support-agent",
  description: "Customer support assistant with configurable tone",
  system: "You are a {{tone}} support agent for {{company}}. Help users resolve their issues politely and accurately.",
  model: "openai/gpt-4o-mini",
  params: { temperature: 0.5, max_tokens: 512 },
  variables: ["company", "tone"],
});

console.log(template.id);

from meshapi import CreateTemplateParams, MeshAPI

client = MeshAPI(base_url="https://api.meshapi.ai", token="rsk_...")

template = client.templates.create(
    CreateTemplateParams(
        name="support-agent",
        description="Customer support assistant with configurable tone",
        system="You are a {{tone}} support agent for {{company}}. Help users resolve their issues politely and accurately.",
        model="openai/gpt-4o-mini",
        params={"temperature": 0.5, "max_tokens": 512},
        variables=["company", "tone"],
    )
)

print(template.id)

Response:

{
  "id": "0197a3c2-5b1e-7d40-9a8f-2c6e1b4d7f30",
  "name": "support-agent",
  "owner": "user_abc123",
  "org_id": "0197a3c0-1f2a-7b3c-8d4e-5f6a7b8c9d0e",
  "team_id": "0197a3c0-2a3b-7c4d-9e5f-6a7b8c9d0e1f",
  "is_global": false,
  "description": "Customer support assistant with configurable tone",
  "system": "You are a {{tone}} support agent for {{company}}. Help users resolve their issues politely and accurately.",
  "messages": null,
  "model": "openai/gpt-4o-mini",
  "params": { "temperature": 0.5, "max_tokens": 512 },
  "variables": ["company", "tone"],
  "category": null,
  "version": null,
  "is_beta": false,
  "creator_name": null,
  "creator_email": null,
  "created_at": "2026-06-01T10:00:00Z",
  "updated_at": "2026-06-01T10:00:00Z",
  "published_version": 1,
  "latest_version": 1
}

Template ids are UUIDs. Creating a template saves and publishes version 1.

Using Variables

Variables use double-brace syntax: {{ variable_name }}. Whitespace inside the braces is trimmed, so {{company}} and {{ company }} are equivalent. Variable names may contain letters, digits, and underscores. You can place variables in system and in any message content field:

{
  "name": "onboarding-guide",
  "system": "You are onboarding {{user_name}} to {{product_name}}. Be concise and encouraging.",
  "messages": [
    {
      "role": "assistant",
      "content": "Welcome, {{user_name}}! Let's get you set up with {{product_name}}."
    }
  ]
}

The variables field (list of strings) is informational — it documents which slots the template expects. It doesn’t enforce anything server-side, but it helps callers know what to pass.

Missing variables at inference time cause a 422 error. Extra variables in the request are silently ignored. Variable values must be strings.

Using a Template in Chat Completions

Pass template (name or UUID) and variables alongside your messages in a POST /v1/chat/completions request. The template’s system prompt and base messages are prepended to your messages before the request is forwarded to the model.

curl
Node.js
Python

curl https://api.meshapi.ai/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_RSK_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "support-agent",
    "variables": { "company": "Acme Corp", "tone": "friendly" },
    "messages": [{ "role": "user", "content": "How do I reset my password?" }]
  }'

const response = await client.chat.completions.create({
  template: "support-agent",
  variables: { company: "Acme Corp", tone: "friendly" },
  messages: [{ role: "user", content: "How do I reset my password?" }],
});

console.log(response.choices[0]?.message.content);

from meshapi import ChatCompletionParams, ChatMessage

response = client.chat.completions.create(
    ChatCompletionParams(
        template="support-agent",
        variables={"company": "Acme Corp", "tone": "friendly"},
        messages=[ChatMessage(role="user", content="How do I reset my password?")],
    )
)

print(response.choices[0].message.content)

The final messages sent to the model look like this:

[
  {
    "role": "system",
    "content": "You are a friendly support agent for Acme Corp. Help users resolve their issues politely and accurately."
  },
  { "role": "user", "content": "How do I reset my password?" }
]

You can reference a template by name or UUID. Name lookups are scoped to your key’s owner first, then fall back to global (admin-seeded) templates. UUID lookups work across any owner. Any value that isn’t a UUID is treated as a name.

By default a request uses the template’s published version. To freeze on a specific release, add template_version (a published version number) next to template; a version that doesn’t exist or was never published returns 404.

Parameter Priority

When a template and a request body both specify inference settings, Mesh resolves them in this order (highest wins):

Priority	Source	Example
3 — highest	Request body	`"temperature": 0.9` in the POST body
2	Key defaults	Default params configured on your API key
1 — lowest	Template defaults	`"params": { "temperature": 0.5 }` in the template

This means you can define sensible defaults in the template and still override them per-request without changing the template. The model resolves the same way: the request body’s model, then your key’s default model, then the template’s.

Managing Templates

List all templates

curl https://api.meshapi.ai/v1/templates \
  -H "Authorization: Bearer <YOUR_RSK_KEY>"

Returns your owned templates plus any global templates, ordered newest first. Add ?scope=custom for the non-global templates you can see, or ?scope=global for only the global templates your organization has enabled (the default is all).

Get a single template

curl https://api.meshapi.ai/v1/templates/<TEMPLATE_ID> \
  -H "Authorization: Bearer <YOUR_RSK_KEY>"

Update a template

PATCH changes metadata: name and description. Only the fields you include are changed.

curl -X PATCH https://api.meshapi.ai/v1/templates/<TEMPLATE_ID> \
  -H "Authorization: Bearer <YOUR_RSK_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Support assistant, v2 tone guide" }'

The content fields (system, messages, model, params, variables) are still accepted on PATCH, but deprecated: sending them saves and publishes a new version in one step. Use the version endpoints below to change content.

Versions

Content is versioned. Every save creates a new, immutable version; only the published version serves inference.

Action	Endpoint
Save a new version (unset fields carry over from the latest)	`POST /v1/templates/{id}/versions`
List versions	`GET /v1/templates/{id}/versions`
Get one version	`GET /v1/templates/{id}/versions/{version_id}`
Publish the latest version	`POST /v1/templates/{id}/publish`
Roll back: copy an old version into a new one and publish it	`POST /v1/templates/{id}/versions/{version_id}/rollback`

curl https://api.meshapi.ai/v1/templates/<TEMPLATE_ID>/versions \
  -H "Authorization: Bearer <YOUR_RSK_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "params": { "temperature": 0.3, "max_tokens": 1024 } }'

curl -X POST https://api.meshapi.ai/v1/templates/<TEMPLATE_ID>/publish \
  -H "Authorization: Bearer <YOUR_RSK_KEY>"

Saving never changes what’s live until you publish. A key with read-only template access sees only published versions.

Delete a template

curl -X DELETE https://api.meshapi.ai/v1/templates/<TEMPLATE_ID> \
  -H "Authorization: Bearer <YOUR_RSK_KEY>"

Returns 204 No Content on success.

Global vs. Owned Templates

	Owned	Global
Created by	You (via `rsk_...`)	Mesh admins
Name lookup scope	Your owner only	Available to all users
Can edit / delete	Yes	No
UUID lookup	Shareable by ID	Shareable by ID

Global templates are useful for standard system roles (e.g., a generic coding assistant or translation prompt) that Mesh pre-seeds for all users. If you create a template with the same name as a global one, your owned template takes precedence in name lookups.

UUID-based lookups are intentionally cross-owner — this lets you share a template with another team by passing them the template ID. Name-based lookups are always scoped to your own account, so there’s no risk of accidentally using someone else’s template by name.

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh Code

Mesh CLI

Platform

Reference

Authentication

Creating a Template

Using Variables

Using a Template in Chat Completions

Parameter Priority

Managing Templates

List all templates

Get a single template

Update a template

Versions

Delete a template

Global vs. Owned Templates

​Authentication

​Creating a Template

​Using Variables

​Using a Template in Chat Completions

​Parameter Priority

​Managing Templates

​List all templates

​Get a single template

​Update a template

​Versions

​Delete a template

​Global vs. Owned Templates

Authentication

Creating a Template

Using Variables

Using a Template in Chat Completions

Parameter Priority

Managing Templates

List all templates

Get a single template

Update a template

Versions

Delete a template

Global vs. Owned Templates