Presets
Save a request's settings under a name, and call it by that name.
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 helpersHelperA tool run for you when a model reaches for it mid-answer: a web search, a page read, a sandbox. Named opendunes:‹name›.More on 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.
The preset routes take an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →, like a request to a model. No management keyManagement keyThe key that runs your account through the API: the balance, the usage history, your keys, guardrails, observability. It never calls a model.More on API keys → is needed.
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.
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"])The answer is charged as if you had written the settings out: at the rates of the model the preset names. usage.cost carries the charge, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →, as on any text request.
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.
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.
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.
| 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.
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.
Last modified on