Observability & evalsPrompt management

Quickstart

Create, configure, version, and deploy prompt templates.

We recommend installing the Respan MCP so your AI coding tool can work with your prompts, logs, and traces directly. Authenticate with your Respan API key from the API keys page:

$claude mcp add \
>  --transport http \
>  --header "Authorization: Bearer YOUR_RESPAN_API_KEY" \
>  respan \
>  https://mcp.respan.ai/mcp

See the MCP docs for OAuth setup and other clients.

What is prompt management?

Prompt management lets you create, version, and deploy prompt templates centrally instead of hardcoding prompts in your application. Simply reference them by ID.

1response = client.chat.completions.create(
2    model="gpt-4o-mini",
3    messages=[
4        {
5            "role": "system",
6            "content": "You are a helpful copywriter. Write a short, friendly product description based on the details provided. Keep it to 2-3 sentences."
7        },
8        {
9            "role": "user",
10            "content": (
11                "Write a product description for the following:\n"
12                f"Product: {product_name}\n"
13                f"Category: {category}\n"
14                f"Key feature: {key_feature}\n"
15                f"Audience: {audience}"
16            )
17        }
18    ]
19)

Prerequisites

Before you begin, make sure you have:

  1. Respan API key: get one from the API keys page. See API keys for details.

  2. Credits: add credits on the Credits page to run models through the Respan gateway. This is the recommended way to get started.

    Add your provider credentials (e.g. OpenAI) on the Providers page instead. See LLM provider keys for details.

Create your first prompt

Go to the Prompts page and click New prompt. Then, follow these steps to make your first prompt:

Configure your prompt: add a title and description, write the system and user prompts, select default and fallback models, and adjust model settings.
1

Add a title and description

Give your prompt a title and a short description.

2

Write your system and user prompts

Add your system prompt to set the model’s role and rules, then add your user prompt containing the specific query or command.
Use {{variable_name}} for dynamic content. For prompt schema and merge behavior, see Advanced features.

3

Select your default and fallback models

Choose the default model to run your prompt, and add any fallback models to retry with if the primary one fails.

4

Adjust model settings

Set temperature, max output tokens, top P, and more in the right sidebar.

Note some models may not support a few of the settings (possibly throwing an error).
To avoid this, toggle the unsupported setting off or set it to 0.
5

Add variable values and test

In the Variables tab, add values for each variable you created, then click Run to test your prompt using those values.

6

Commit and deploy

Click Commit and write a message to save this version.
Once you commit, you can Deploy to push the version into production.

7

Use your prompt in code

Call your prompt from your application with the OpenAI SDK using prompt schema v1. Point the client at the Respan gateway and set override: true so your saved prompt configuration (model, messages, and settings) wins over the placeholder model and messages the SDK requires.

1import os
2from openai import OpenAI
3
4client = OpenAI(
5    api_key=os.environ["RESPAN_API_KEY"],  # keep your key in an env var
6    base_url="https://api.respan.ai/api",
7)
8
9response = client.chat.completions.create(
10    model="placeholder",
11    messages=[{"role": "user", "content": "placeholder"}],
12    extra_body={
13        "prompt": {
14            "prompt_id": "YOUR_PROMPT_ID",
15            # Prompt schema v1: override=True lets your saved prompt config
16            # (model, messages, settings) win over the placeholders above.
17            "override": True,
18            "variables": {
19                "product_name": "AeroLite Running Shoes",
20                "category": "athletic footwear",
21                "key_feature": "weighs under 200 grams",
22                "audience": "marathon runners",
23            },
24        }
25    },
26)
27
28print(response.choices[0].message.content)

For more, see Prompt composition, Structured output, and Tool calling. For schema details (v1 vs v2), deployment, streaming, and logging, see Advanced features.

Find your prompt ID

Now that you made your own prompt, learn how to call it. This is how you find the prompt_id, a unique identifier for Respan prompts.

Find the Prompt ID in the Overview panel on the Prompts page.

Find Prompt ID

Next steps