# Saved settings

`POST /v1/presets/{slug}/chat/completions` saves a request's settings under a name; seven routes
save, list and read your presets and their versions.

## Request

Send them with an API key. A request uses a preset by sending `@preset/<slug>` as its `model`:
the preset's settings apply, and any field the request sends itself wins. The
[Presets](/docs/presets) guide saves one and calls it.

| Route | Does |
|---|---|
| `POST /v1/presets/{slug}/chat/completions` | saves a preset from a Chat request body |
| `POST /v1/presets/{slug}/messages` | saves one from a Messages request body |
| `POST /v1/presets/{slug}/responses` | saves one from a Responses request body |
| `GET /v1/presets` | lists your presets |
| `GET /v1/presets/{slug}` | answers one preset, with the version a request runs |
| `GET /v1/presets/{slug}/versions` | lists its versions, oldest first |
| `GET /v1/presets/{slug}/versions/{version}` | answers one version |

### Save

The body is a request in the route's own shape, as you would send it to
[Chat](/docs/reference/chat-completions) or [Messages](/docs/reference/messages). The first save of
a slug makes the preset; every save after it adds a version, and the newest is the one a request
runs. Every version is kept.

| Field | Needed | You send |
|---|---|---|
| `slug` | yes | in the address: the preset's name, letters, digits, `.`, `_` and `-`, up to 120 characters, starting with a letter or a digit |
| `model` | yes | the model, `lab/model`, and with it any of the request's settings: `models`, `provider`, the Sampling fields, `max_tokens`, `reasoning`, `response_format` or `text`, `tools`, `tool_choice`, `plugins`, `cache_control` and the rest of the fields its reference page lists |
| `messages` | no | kept for one thing only: the system prompt, from a `system` or `developer` turn. On `/messages` it is `system`, on `/responses` `instructions`. The conversation itself is never kept |

Send `X-OpenDunes-Cache: true` with the save, and `X-OpenDunes-Cache-TTL`, to keep the response
cache in the preset too.

Yacine saves Souk Bot's settings as `souk-bot`; his app then sends `"model": "@preset/souk-bot"`.

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

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/presets/souk-bot/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
SYSTEM = "You answer customers of an Algerian marketplace, in their language."

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "temperature": 0.3,
            "messages": [{"role": "system", "content": SYSTEM}],
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    preset = json.load(response)["data"]

print(preset["slug"], preset["designated_version"]["version"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/presets/souk-bot/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const SYSTEM =
  "You answer customers of an Algerian marketplace, in their language.";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    temperature: 0.3,
    messages: [{ role: "system", content: SYSTEM }],
  }),
});
const { data } = await response.json();

console.log(data.slug, data.designated_version.version);
```

```go
package main

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

const (
	address = "https://opendunes.com/v1/presets/souk-bot/chat/completions"
	model   = "anthropic/claude-sonnet-4.5"
	system  = "You answer customers of an Algerian marketplace, " +
		"in their language."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model":       model,
		"temperature": 0.3,
		"messages": []map[string]string{
			{"role": "system", "content": system},
		},
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Data struct {
			Slug              string `json:"slug"`
			DesignatedVersion struct {
				Version int `json:"version"`
			} `json:"designated_version"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	fmt.Println(answer.Data.Slug, answer.Data.DesignatedVersion.Version)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/presets/souk-bot/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"
SYSTEM="You answer customers of an Algerian marketplace, in their language."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "temperature": 0.3,
    "messages": [
      { "role": "system", "content": "'"$SYSTEM"'" }
    ]
  }'
```

### List

`GET /v1/presets` and `GET /v1/presets/{slug}/versions` take their fields in the address, after
`?`.

| Field | Needed | You send |
|---|---|---|
| `limit` | no | how many one page holds, 1 to 100; absent, 50 |
| `offset` | no | how many to skip, for the next page |

## Response

A save and `GET /v1/presets/{slug}` answer `200 OK` with `data`, the preset and its
`designated_version`. The two lists answer `data`, a list, and `total_count`.

| Field | Holds |
|---|---|
| `data` | the preset, the version, or the list |
| `total_count` | on a list: how many there are in all |
| `id` | the preset's id |
| `slug` | its name: send `@preset/<slug>` as `model` |
| `name` | its name, the slug |
| `description` | `null` |
| `status` | `active` |
| `status_updated_at` | `null` |
| `creator_user_id` | your account's id |
| `designated_version_id` | the version a request runs |
| `designated_version` | that version, whole, on a save and on one preset |
| `created_at` · `updated_at` | when it was made and last saved, in UTC |

A version holds:

| Field | Holds |
|---|---|
| `preset_id` | its preset |
| `version` | its number, from 1 |
| `config` | the settings it keeps: the model and every setting the body sent, and `cache` when the save sent the cache headers |
| `system_prompt` | the system prompt it adds to a request that has none, or `null` |
| `creator_id` | your account's id |
| `id` · `created_at` · `updated_at` | the version's own id, and when it was saved, in UTC |

## What it cost

Free. Saving and reading a preset is never charged. A request that names `@preset/<slug>` is
charged as that request, at the rates of the model the preset sets.

## Errors

`error.code` carries the status, and `error.message` says why.

| Status | When |
|---|---|
| 400 | `model` is missing from a save, or the slug is not a name the route takes |
| 401 | the key is missing, wrong, disabled or expired |
| 403 | the key is kept to other addresses |
| 404 | no preset of yours has that slug, or it has no such version |
