Zero data retention

A key in zero_retention mode is for workloads whose content must not persist: Belarel does not keep the prompt or the answer, and the call is only routed to model providers that offer zero data retention and do not train on prompts. This page describes exactly what that covers, and what it does not.

What zero retention does

For every call made with a zero_retention key, on POST /v1/chat/completions, POST /v1/responses and POST /v1/embeddings:

1. Routing is restricted. The call carries two routing requirements: zero data retention, and no training on prompts. Only providers that satisfy both may serve it.
2. A call that cannot be honoured is refused, not downgraded. If the model is not served through a route that supports zero retention, or no provider of that model can satisfy the requirements, the call fails with 400 model_not_zdr. It is never silently served by a provider that ignores the requirement.
3. No content is journaled. The request journal keeps no prompt, no output, no hash of either, no image URL and no content-derived cache key — regardless of how journaling is configured for standard keys.
4. No content is kept for retries. A JSON answer is never stored for Idempotency-Key replay. Retrying with the same key returns 409 idempotency_conflict naming the original request id, instead of the answer.

One exception: the idempotency fingerprint

If you send an Idempotency-Key header, Belarel keeps a fingerprint of the request body — prompt included — to detect a key reused with a different body. The fingerprint is a keyed hash (HMAC-SHA256) computed with a secret held only by Belarel’s servers, so it cannot be confirmed by guessing the prompt without that secret. If the secret is unavailable, Belarel refuses the call with 503 admission_unavailable rather than store an unkeyed hash. The fingerprint is kept for up to 48 hours (24 hours of validity, then removed by the next daily cleanup) and is never returned by the API. If even a keyed fingerprint is unacceptable for a workload, do not send Idempotency-Key with that key.

The answer itself is returned to you as usual; Belarel does not keep a copy.

Which models qualify

GET /v1/models marks each model with belarel.zero_retention_available:

{
  "id": "<model-id>",
  "object": "model",
  "belarel": {
    "category": "language",
    "zero_retention_available": true,
    "byok_available": false
  }
}

true means the model is served through a route that supports zero retention. Treat it as a prerequisite, not a guarantee: at call time, if no provider of that model can meet the requirements, the call is still refused with model_not_zdr. The list returned to a zero_retention key is not filtered on this flag, so filter it yourself.

Sandbox keys (bel_test_…) never reach a provider, so a sandbox zero_retention key accepts any model in its catalog. Test the real model list with a live key.

What is still recorded

Zero retention is about content. To bill you, enforce your caps and let you inspect your usage, each call still produces a record without content:

Recorded	Not recorded
Request id, key id, timestamp, duration	Messages, system prompt, input text
Model requested and served, and the provider it was routed to	Model output
Token counts (input, output, cached, reasoning)	Hashes of the prompt or output in the request journal
Cost (USD and credits), billing ledger entry	Image URLs
HTTP status, success or failure, error message	Content-derived cache keys
Tags (including the metadata field, and the automatic app and app_url tags from X-Title and HTTP-Referer)	Stored response for idempotent replay
Keyed fingerprint (HMAC-SHA256) of the request body, only when you send Idempotency-Key (up to 48 hours)

GET /v1/requests/{id} returns the same record for a zero_retention call as for any other: status, model, usage, cost and tags — never content.

Caution

Tags are attribution data and are recorded. Belarel reads the OpenAI metadata body field as tags, so anything you put in metadata, in belarel_tags or in the X-Belarel-Tags header — and the app and app_url tags derived from X-Title and HTTP-Referer — is stored with the call. Do not put personal data or secrets there.

Using a zero retention key

Nothing changes in your code. The mode belongs to the key, so you only swap the key.

curl

curl https://api.belarel.com/v1/chat/completions \
  -H "Authorization: Bearer $BELAREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [{ "role": "user", "content": "Summarize this clinical note: …" }]
  }'

Python

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.belarel.com/v1", api_key=os.environ["BELAREL_API_KEY"])

completion = client.chat.completions.create(
    model="<model-id>",
    messages=[{"role": "user", "content": "Summarize this clinical note: …"}],
)
print(completion.model_extra["belarel"]["data_mode"])  # "zero_retention"

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.belarel.com/v1', apiKey: process.env.BELAREL_API_KEY });

const completion = await client.chat.completions.create({
  model: '<model-id>',
  messages: [{ role: 'user', content: 'Summarize this clinical note: …' }],
});
console.log((completion as any).belarel.data_mode); // "zero_retention"

Errors specific to zero retention

Code	HTTP	Meaning	What to do
model_not_zdr	400	The model cannot be served with zero retention.	Pick a model with zero_retention_available: true. Do not retry the same model.
idempotency_conflict	409	You retried with an Idempotency-Key already used; the answer was not stored.	Inspect the original call with GET /v1/requests/{id}, or send a new request with a new key.

Limits of the guarantee

• Zero retention covers what Belarel stores and how calls are routed. What a provider does is governed by its own zero-retention commitments, which the routing requirement relies on.
• Content you send elsewhere — your own logs, your observability tools, another API — is outside its scope.
• The mode is set when the key is created and cannot be changed later.

See also

• Data modes
• Data handling & retention
• Idempotency
• Errors & debugging