Advanced configurations

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

New to prompts? Start with the Quickstart. For more, see Prompt composition, Structured output, and Tool calling.

Prompt schema

The prompt object supports a schema_version field that controls how prompt configuration and request-body parameters are merged.

Prompt schema v2 (recommended)

Set schema_version=2 for the recommended merge behavior:

• Prompt configuration always wins for conflicting fields (no override flag needed).
• Uses prepend/instructions-style merging depending on the endpoint mode.
• Supports a patch field for applying additional parameter overrides. The patch object must not contain messages or input.

1
import requests
2
3
headers = {
4
    'Content-Type': 'application/json',
5
    'Authorization': 'Bearer YOUR_RESPAN_API_KEY',
6
}
7
8
data = {
9
    'prompt': {
10
        'prompt_id': 'YOUR_PROMPT_ID',
11
        'schema_version': 2,
12
        'variables': {
13
            'animal': 'octopus',
14
        },
15
        'patch': {
16
            'temperature': 0.9,
17
            'max_tokens': 500
18
        }
19
    }
20
}
21
22
response = requests.post(
23
    'https://api.respan.ai/api/chat/completions',
24
    headers=headers,
25
    json=data
26
)
27
print(response.json())

Prompt schema v1 (default, legacy)

When schema_version is absent or 1, merging is controlled by the override flag:

• override=true: prompt configuration wins for all conflicting fields.
• override=false (default): request body wins for conflicting fields.

1
request_body = {
2
    "prompt": {
3
        "prompt_id": "YOUR_PROMPT_ID",
4
        "override": True,
5
        "override_params": {
6
            "temperature": 0.8,
7
            "max_tokens": 150,
8
            "model": "gpt-5.5"
9
        }
10
    }
11
}

1
request_body = {
2
    "prompt": {
3
        "prompt_id": "YOUR_PROMPT_ID",
4
        "override_config": {"messages_override_mode": "append"},
5
        "override_params": {"messages": [{"role": "user", "content": "Additional context"}]},
6
    }
7
}

1
request_body = {
2
    "prompt": {
3
        "prompt_id": "YOUR_PROMPT_ID",
4
        "override_config": {"messages_override_mode": "override"},
5
        "override_params": {"messages": [{"role": "user", "content": "Completely new conversation"}]},
6
    }
7
}

Deployment & versioning

Via UI

Via code

Commit saves a new version of your prompt. Deploy makes a version live for production traffic.

Manage versions from the panel on the right side of the Editor. It has two tabs:

• Versions lists every committed version, newest first. Each entry shows its commit message, version number (v1, v2, …), author, and timestamp. The live version is tagged Deployed, and your current uncommitted edits show as a Draft.
• Activity shows a chronological log of changes made to the prompt.

Compare versions: use the Playground to run different versions side by side.

Deploy a version: select the version you want, then click Deploy to make it live. To roll back, deploy an earlier version the same way.

Fallback models

Add fallback models to retry on a different model if the primary one fails. The gateway tries each model in order until one succeeds.

Use in UI

Use in code

In the prompt editor’s Settings panel, click Add fallback model and select a model. Add as many as you need, then commit and deploy.

For fallbacks, load balancing, and retries applied at the gateway level, see the Gateway reliability docs.

Streaming

Enable streaming with the Stream toggle at the bottom of the model settings. After enabling, commit and deploy the prompt.

If you use a prompt with streaming enabled, you must also set stream=True in your SDK call:

1
response = client.chat.completions.create(
2
    model="placeholder",
3
    messages=[{"role": "user", "content": "placeholder"}],
4
    stream=True,
5
    extra_body={
6
        "prompt": {
7
            "prompt_id": "YOUR_PROMPT_ID",
8
            "override": True,
9
            "variables": {"animal": "octopus"},
10
        }
11
    },
12
)

For how streaming works at the gateway level, see the Chat Completions API reference.

Prompt logging

Respan prompts

External prompts

Log prompt usage to track performance metrics, compare versions, and analyze request distribution.

PythonTypeScript

1
import requests
2
3
url = "https://api.respan.ai/api/request-logs/create/"
4
payload = {
5
    "model": "claude-sonnet-4-6",
6
    "completion_message": {
7
        "role": "assistant",
8
        "content": "Octopuses have three hearts and blue blood."
9
    },
10
    "prompt": {
11
        "prompt_id": "xxxxxx",
12
        "variables": {
13
            "animal": "octopus"
14
        },
15
    },
16
    "generation_time": 5.7,
17
    "ttft": 3.1,
18
}
19
headers = {
20
    "Authorization": "Bearer YOUR_RESPAN_API_KEY",
21
    "Content-Type": "application/json"
22
}
23
24
response = requests.post(url, headers=headers, json=payload)

To see the logs for a specific prompt, click Logs on the Prompt page. This opens the Spans page with the Prompt filter already set to that prompt.

You can filter by any prompt yourself by selecting it under Prompt in the Spans filters.

Parameters reference

1
{
2
  "variables": {
3
    "user_name": "John",
4
    "task": "summarize"
5
  }
6
}

1
{
2
  "prompt": {
3
    "prompt_id": "my-prompt",
4
    "schema_version": 2
5
  },
6
  "fallback_models": ["gpt-5.5", "claude-sonnet-4-6", "gemini-2.5-flash"]
7
}

See all Respan supported params.