> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Quickstart

Keep prompts in Respan instead of in your code. Your app calls a prompt by its ID, and when you deploy a new version, the next call uses it with no code change.

#### Create a prompt

In the [platform](https://platform.respan.ai), go to **Gateway** › **Prompts** and click **New prompt** (or press **C**). Respan creates **Untitled prompt** and opens it in the editor. To rename it, hover its tab and click the pencil.

#### Write the messages

Fill in the **System** and **User** messages. Wrap anything that changes per request in double braces, like `{{customer_name}}`. Each variable gets a field in the **Variables** tab. Click **Add message** to add more turns.

![The prompt editor with a System message, a User message using the variables customer\_name, plan, and ticket\_body, and the Variables tab with a test value for each](/docs/_fern-img/1f3870c3a9162c1940b73a4a83ff63aabf14ac4fa44444a2d0d75bd8642a847c.webp)![The prompt editor with a System message, a User message using the variables customer\_name, plan, and ticket\_body, and the Variables tab with a test value for each](/docs/_fern-img/93d8ef353a9fdfd51e848f778a3e4271d3807632f527a88ea06555cbb6132f6d.webp)

#### Pick a model and test

Click **Open side panel** (the icon at the top right), or press **.**:

* **Settings**: choose the **Model**, click **Add fallback model** for a backup, and tune **Model settings** such as temperature and max tokens.
* **Variables**: enter a test value for each variable.

Click **Run** (**⌘ ↵**). The reply shows in the **Test run** tab.

#### Commit and deploy

Click **Commit** (**⌘ S**), type a message (or press **Tab** to generate one), and click **Commit + Deploy**. **Commit** alone saves a version without making it live.

![The Commit dialog with a commit message and two buttons: Commit + Deploy and Commit](/docs/_fern-img/7122db893b9ea9bda2d3e85ecac39a0662a8c30ff0f0ca88410c5542a41730be.webp)![The Commit dialog with a commit message and two buttons: Commit + Deploy and Commit](/docs/_fern-img/3bdd7fd3e71a4a830489293de0644374456bc0b8abcb5bfae9237f21dc5843f4.webp)

Respan shows **Your prompt was deployed** with the **Prompt ID**. Copy it. To find it later, click the copy icon next to the prompt name in the side panel and choose **Copy ID**.

#### Call the prompt

Send a `prompt` object with the prompt ID and your variables. Respan fills the variables into the deployed version and uses that version's messages, model, and settings. You need a Respan API key and credits or a provider key; see the [Gateway quickstart](/docs/documentation/features/gateway/gateway-quickstart).

#### OpenAI (Python)

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key=os.environ["RESPAN_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-5.5",  # the prompt's saved model is used
    messages=[],
    extra_body={
        "prompt": {
            "prompt_id": "YOUR_PROMPT_ID",
            "schema_version": 2,
            "variables": {
                "customer_name": "Maya Patel",
                "plan": "Team",
                "ticket_body": "Reset link opens a blank page.",
            },
        }
    },
)
print(response.choices[0].message.content)
```

#### OpenAI (TypeScript)

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.respan.ai/api/",
  apiKey: process.env.RESPAN_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-5.5", // the prompt's saved model is used
  messages: [],
  // @ts-expect-error `prompt` is a Respan field
  prompt: {
    prompt_id: "YOUR_PROMPT_ID",
    schema_version: 2,
    variables: {
      customer_name: "Maya Patel",
      plan: "Team",
      ticket_body: "Reset link opens a blank page.",
    },
  },
});
console.log(response.choices[0].message.content);
```

#### cURL

```bash
curl https://api.respan.ai/api/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": {
      "prompt_id": "YOUR_PROMPT_ID",
      "schema_version": 2,
      "variables": {
        "customer_name": "Maya Patel",
        "plan": "Team",
        "ticket_body": "Reset link opens a blank page."
      }
    }
  }'
```

To see the calls, click **Logs** next to the prompt's tab at the top (or press **L**). Logs opens filtered to this prompt.

## Ship a new version

Edit the prompt and click **Commit + Deploy** again. Your app gets the new version on its next call.

To see every version, click the version count at the top right (like **3 versions**), or press **H**. The live version is tagged **Deployed**, and edits you haven't committed show as **Draft**. To roll back, select an older version and click **Deploy**.

![The versions pane: the current draft (v3), the deployed version (v2), and an older version (v1), each with its commit message and author](/docs/_fern-img/16632b608308c75838253e69c348755bd6b7da6defea2bf0ab5a4756bbf01178.webp)![The versions pane: the current draft (v3), the deployed version (v2), and an older version (v1), each with its commit message and author](/docs/_fern-img/80b25f9ff5508e0bd536945617d62d817e1770b3f005e0818e06044dd56337b0.webp)

## Choose which version a call uses

Add `version` to the `prompt` object:

| `version`          | The call uses                                      |
| ------------------ | -------------------------------------------------- |
| Not set            | The deployed version                               |
| A number, like `3` | That version                                       |
| `"latest"`         | The newest version, including an uncommitted draft |

With `"schema_version": 2`, the prompt's saved settings win over the request body, and any `messages` you send are added after the prompt's messages. For the older `override` behavior, `patch`, and the versioning API, see [Advanced configurations](/docs/documentation/features/prompt-management/advanced).

To return JSON, let the model call functions, or reuse one prompt inside another, see [Structured output](/docs/documentation/features/prompt-management/structured-output), [Tool calling](/docs/documentation/features/prompt-management/tool-calling), and [Prompt composition](/docs/documentation/features/prompt-management/prompt-composition). To compare models before you commit, use the [Playground](/docs/documentation/features/prompt-management/playground).