# Presets

Save a request's settings under a name, and call it by that name.

1. [Save the preset](#1-save-the-preset).
2. [Call it by name](#2-call-it-by-name).
3. [Read its versions](#3-read-its-versions).

## 1. Save the preset

A preset is a request's settings, saved under a name. You write the request once, as you would send it, and post it to the preset's address instead of the model's. What it holds:

| A preset holds | For example |
|---|---|
| the model, or its fallbacks | `model`, `models` |
| the provider routing | `provider` |
| the system prompt | the first `system` message; `system` on the Anthropic shape; `instructions` on the Responses shape |
| the parameters | `temperature`, `max_tokens`, `reasoning`, `response_format` |
| the helpers | `tools`, `plugins` |
| the cache | the `X-OpenDunes-Cache` and `X-OpenDunes-Cache-TTL` headers sent with it |

The conversation itself is never saved: each request brings its own.

| Route | Saves from a body in |
|---|---|
| `POST /v1/presets/{slug}/chat/completions` | the OpenAI shape |
| `POST /v1/presets/{slug}/messages` | the Anthropic shape |
| `POST /v1/presets/{slug}/responses` | the Responses shape |

`{slug}` is yours: letters, digits, `.`, `_` and `-`. Saving a body runs no model and costs nothing.

<div class="good-to-know">
<p>The preset routes take an API key, like a request to a model. No management key is needed.</p>
</div>

## 2. Call it by name

Name the preset as the model: `@preset/<slug>`. The request brings the conversation; the preset brings the rest. A setting the request sends itself wins over the preset's.

Souk Bot answers the customers of a clothing shop in Oran in the same voice on every page. The sample saves that voice as `souk-bot`, then asks a question through it.

```python
import json
import os
import urllib.request

key = os.environ["OPENDUNES_API_KEY"]
base_url = "https://opendunes.com/v1"
model = "anthropic/claude-sonnet-4.5"
preset = "souk-bot"

system = (
    "You are Souk Bot, for a clothing shop in Oran. "
    "Answer in two short sentences, in the shopper's language."
)
question = "Do you deliver to Constantine?"


def call(path, body):
    request = urllib.request.Request(
        base_url + path,
        data=json.dumps(body).encode(),
        headers={
            "Authorization": "Bearer " + key,
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)


saved = call("/presets/" + preset + "/chat/completions", {
    "model": model,
    "messages": [{"role": "system", "content": system}],
    "temperature": 0.3,
    "max_tokens": 300,
})["data"]
print("version", saved["designated_version"]["version"])

answer = call("/chat/completions", {
    "model": f"@preset/{preset}",
    "messages": [{"role": "user", "content": question}],
})
print(answer["choices"][0]["message"]["content"])
print(answer["usage"]["cost"])
```

```javascript
const key = process.env.OPENDUNES_API_KEY;
const baseURL = "https://opendunes.com/v1";
const model = "anthropic/claude-sonnet-4.5";
const preset = "souk-bot";

const system =
  "You are Souk Bot, for a clothing shop in Oran. " +
  "Answer in two short sentences, in the shopper's language.";
const question = "Do you deliver to Constantine?";

async function call(path, body) {
  const response = await fetch(baseURL + path, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    throw new Error(`${response.status} ${await response.text()}`);
  }
  return response.json();
}

const saved = await call(`/presets/${preset}/chat/completions`, {
  model,
  messages: [{ role: "system", content: system }],
  temperature: 0.3,
  max_tokens: 300,
});
console.log("version", saved.data.designated_version.version);

const answer = await call("/chat/completions", {
  model: `@preset/${preset}`,
  messages: [{ role: "user", content: question }],
});
console.log(answer.choices[0].message.content);
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

var key = os.Getenv("OPENDUNES_API_KEY")

const (
	baseURL = "https://opendunes.com/v1"
	model   = "anthropic/claude-sonnet-4.5"
	preset  = "souk-bot"
)

const system = "You are Souk Bot, for a clothing shop in Oran. " +
	"Answer in two short sentences, in the shopper's language."
const question = "Do you deliver to Constantine?"

type message map[string]string

func call(path string, body any, out any) {
	encoded, err := json.Marshal(body)
	if err != nil {
		panic(err)
	}

	url := baseURL + path
	req, err := http.NewRequest("POST", url, bytes.NewReader(encoded))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+key)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		text, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("%d %s", res.StatusCode, text))
	}
	if err := json.NewDecoder(res.Body).Decode(out); err != nil {
		panic(err)
	}
}

func main() {
	var saved struct {
		Data struct {
			DesignatedVersion struct {
				Version int `json:"version"`
			} `json:"designated_version"`
		} `json:"data"`
	}
	call("/presets/"+preset+"/chat/completions", map[string]any{
		"model":       model,
		"messages":    []message{{"role": "system", "content": system}},
		"temperature": 0.3,
		"max_tokens":  300,
	}, &saved)
	fmt.Println("version", saved.Data.DesignatedVersion.Version)

	var answer struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	call("/chat/completions", map[string]any{
		"model":    fmt.Sprintf("@preset/%s", preset),
		"messages": []message{{"role": "user", "content": question}},
	}, &answer)
	fmt.Println(answer.Choices[0].Message.Content)
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
BASE_URL="https://opendunes.com/v1"
MODEL="anthropic/claude-sonnet-4.5"
PRESET="souk-bot"
PRESET_MODEL="@preset/$PRESET"

SYSTEM="You are Souk Bot, for a clothing shop in Oran."
SYSTEM="$SYSTEM Answer in two short sentences, in the shopper's language."

curl "$BASE_URL/presets/$PRESET/chat/completions" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {
        "role": "system",
        "content": "'"$SYSTEM"'"
      }
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$PRESET_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "Do you deliver to Constantine?"
      }
    ]
  }'
```

The answer is charged as if you had written the settings out: at the rates of the model the preset names. [`usage.cost`](/docs/balance-and-charges) carries the charge, in DA, as on any [text](/docs/text) request.

<div class="do">
<p>Do keep the model and the system prompt in the preset, and the conversation in your code. A new prompt then ships without a deploy.</p>
</div>

## 3. Read its versions

Every save of the same name is a new version. A preset keeps every version, and a request uses the newest.

<div class="watch-out">
<p>A save takes effect at once: the next request that names the preset runs the new version. To go back, save the earlier settings again.</p>
</div>

| Route | Answers |
|---|---|
| `GET /v1/presets` | your presets |
| `GET /v1/presets/{slug}` | one preset, with the version in use under `designated_version` |
| `GET /v1/presets/{slug}/versions` | every version, oldest first |
| `GET /v1/presets/{slug}/versions/{version}` | one version: its settings in `config`, its `system_prompt` |

Every preset route is free. Every field: [Saved settings](/docs/reference/presets).

## Errors

| Status | When |
|---|---|
| 400 | the body to save is malformed, or `{slug}` holds a character it cannot |
| 401 | the key is missing, wrong, disabled or expired |
| 404 | `@preset/<slug>` names no preset of yours, or the version does not exist |

A request through a preset meets the errors of the model it names. What to do on each: [Errors and retries](/docs/errors-and-retries).
