# Plugins

Add a step to a request without writing the step yourself.

1. [Name a plugin in the request](#1-name-a-plugin-in-the-request).
2. [Pick the plugin](#2-pick-the-plugin).
3. [Switch a plugin on for a key](#3-switch-a-plugin-on-for-a-key).
4. [Read what it cost](#4-read-what-it-cost).

## 1. Name a plugin in the request

Put a `plugins` list in the request body. Each entry is an object with an `id`, and the options that plugin takes. The plugin runs once on that request, before the answer reaches you.

This sample asks for a JSON order and names `response-healing`, so a reply that comes back with a stray comma or a cut-off bracket is repaired before you parse it.

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

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = (
    "Return a JSON object with the keys item and quantity for this "
    "order: two sfenj and one mint tea for table 4 at the Oran cafe."
)

body = {
    "model": MODEL,
    "messages": [{"role": "user", "content": PROMPT}],
    "response_format": {"type": "json_object"},
    "plugins": [{"id": "response-healing"}],
}

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    reply = json.load(response)

order = json.loads(reply["choices"][0]["message"]["content"])
print(order)
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT =
  "Return a JSON object with the keys item and quantity for this " +
  "order: two sfenj and one mint tea for table 4 at the Oran cafe.";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    messages: [{ role: "user", content: PROMPT }],
    response_format: { type: "json_object" },
    plugins: [{ id: "response-healing" }],
  }),
});
const reply = await response.json();

const order = JSON.parse(reply.choices[0].message.content);
console.log(order);
```

```go
package main

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

const (
	address = "https://opendunes.com/v1/chat/completions"
	model   = "anthropic/claude-sonnet-4.5"
	prompt  = "Return a JSON object with the keys item and quantity " +
		"for this order: two sfenj and one mint tea for table 4 " +
		"at the Oran cafe."
)

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

	body, err := json.Marshal(map[string]any{
		"model": model,
		"messages": []any{
			map[string]any{"role": "user", "content": prompt},
		},
		"response_format": map[string]any{"type": "json_object"},
		"plugins": []any{
			map[string]any{"id": "response-healing"},
		},
	})
	if err != nil {
		panic(err)
	}

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

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

	var reply struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
	}
	if err := json.NewDecoder(response.Body).Decode(&reply); err != nil {
		panic(err)
	}

	var order map[string]any
	err = json.Unmarshal([]byte(reply.Choices[0].Message.Content), &order)
	if err != nil {
		panic(err)
	}
	fmt.Println(order)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"
PROMPT="Return a JSON object with the keys item and quantity for this \
order: two sfenj and one mint tea for table 4 at the Oran cafe."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "'"$PROMPT"'"
      }
    ],
    "response_format": {"type": "json_object"},
    "plugins": [{"id": "response-healing"}]
  }'
```

<div class="good-to-know">
<p>A plugin works on the request that names it and on no other. Name it again on the next request, or switch it on for the key: <a href="#3-switch-a-plugin-on-for-a-key">section 3</a>.</p>
</div>

## 2. Pick the plugin

| `id` | Does | Options |
|---|---|---|
| `file-parser` | reads a PDF sent with the request, so a model that cannot open PDFs can still answer about one | `pdf.engine`: `native`, `cloudflare-ai` or `mistral-ocr`. How to send the file and which engine suits it: [PDFs in](/docs/pdfs-in) |
| `response-healing` | repairs a JSON answer that is broken: a missing bracket, a trailing comma, text around the object | none |
| `context-compression` | cuts the middle of a prompt that is too long for the model, and keeps its start and its end | none |
| `web` | attaches search results to the prompt. Retired: use the web search helper, [Helpers](/docs/helpers) | none |

<div class="watch-out">
<p>Response healing repairs the shape of the JSON, never its meaning. A reply that is valid JSON with the wrong values stays wrong: check the fields you rely on.</p>
</div>

<div class="watch-out">
<p>Context compression drops the middle of the prompt. When the middle holds the answer, send a model with a longer context instead, or shorten the prompt yourself.</p>
</div>

An `id` the door does not know is refused with a 400, and so is an option that points the plugin at an engine billed to your own account somewhere else. The router has a plugin of its own, `auto-router`, which is described on [Auto router](/docs/auto-router).

## 3. Switch a plugin on for a key

To run a plugin on every request of one key without changing the code that sends them, switch it on in the key's settings in your dashboard. Every request of that key then runs it, as if each had named it.

| Where | Runs the plugin on |
|---|---|
| the request's `plugins` list | that request |
| the key's settings in the dashboard | every request of that key |

<div class="do">
<p>Switch a plugin on for a key when the whole app needs it, such as response healing on a key that only returns JSON. Name it in the request when only one call does.</p>
</div>

## 4. Read what it cost

`response-healing` and `context-compression` are free. `file-parser` is charged only when the model cannot read the PDF itself; a model that reads PDFs natively is charged for the request alone. Whatever a plugin cost is counted in `usage.cost` of the answer, like the rest of the request: [Balance and charges](/docs/balance-and-charges).

<div class="dont">
<p>Don't name <code>file-parser</code> for a model that reads PDFs by itself, to be safe. It adds nothing there. Name it when the model you picked cannot open the file.</p>
</div>

## Errors

The body says why. What to do on every status: [Errors and retries](/docs/errors-and-retries).

| Status | Means |
|---|---|
| 400 | the `id` is not a plugin the door knows, or an option is refused; the message names which |
| 401 | the key is missing or wrong |
| 402 | the balance cannot cover the request |
