opendunes
Your account · 3 min
Copy page ▾

Presets

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

  1. Save the preset.
  2. Call it by name.
  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 holdsFor example
the model, or its fallbacksmodel, models
the provider routingprovider
the system promptthe first system message; system on the Anthropic shape; instructions on the Responses shape
the parameterstemperature, 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 cachethe X-OpenDunes-Cache and X-OpenDunes-Cache-TTL headers sent with it

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

RouteSaves from a body in
POST /v1/presets/{slug}/chat/completionsthe OpenAI shape
POST /v1/presets/{slug}/messagesthe Anthropic shape
POST /v1/presets/{slug}/responsesthe Responses shape

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

Good to know

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

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.

Watch out

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.

RouteAnswers
GET /v1/presetsyour presets
GET /v1/presets/{slug}one preset, with the version in use under designated_version
GET /v1/presets/{slug}/versionsevery 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

StatusWhen
400the body to save is malformed, or {slug} holds a character it cannot
401the 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