Data Controls for AvalAI APIs

Use this guide to design privacy-safe AvalAI integrations. It adapts OpenAI's official data controls, conversation state, background mode, and prompt caching guidance to AvalAI's OpenAI-compatible gateway.

AvalAI's own API policy is documented in the Privacy Policy and Content Policy. Because AvalAI routes requests to upstream model providers, always separate AvalAI service metadata from provider-side application state.

Data Layers

Layer	What it may contain	Developer action
Request and response content	prompts, messages, tool outputs, files, images, audio	Send only the minimum data needed for the task.
AvalAI service metadata	model, route, token usage, cost, IP, request IDs	Keep logs safe for billing, support, rate-limit debugging, and abuse review.
Provider application state	stored Responses, files, batches, vector stores, background jobs	Use store: false, expires_after, deletion APIs, or app-managed state when available.
Third-party tools and providers	web search, MCP servers, external APIs, provider-native services	Review each service's retention policy before sending customer data.

OpenAI Reference Behaviors to Map

Use OpenAI's published behavior as a checklist, then verify the exact AvalAI route and upstream provider before promising retention guarantees:

OpenAI separates abuse monitoring logs from application state: abuse logs may include prompts, responses, and derived safety metadata for policy enforcement, while application state is data a feature must persist to fulfill the request. In AvalAI, keep the same mental model but map it to the selected provider route. Store operational metadata such as x-request-id, model, usage, cost, and error class separately from customer content, and avoid treating billing or support logs as a safe place for full prompts.

OpenAI's reference defaults are useful numbers for risk reviews, not automatic AvalAI guarantees: abuse-monitoring logs are generally retained for up to 30 days, stored Responses are retained for at least 30 days when storage is enabled, background Responses keep data briefly for polling, and audio outputs can create short-lived state for multi-turn audio. Zero Data Retention and Modified Abuse Monitoring are approved account controls; under OpenAI's ZDR behavior, store is treated as false, but endpoints that need application state may still be ineligible. Treat every AvalAI claim as route-, provider-, and contract-specific.

Feature	OpenAI reference behavior	AvalAI-safe default
API training	API data is not used for OpenAI model training unless explicitly opted in.	Do not infer upstream training policy; document the provider contract for the selected route.
/v1/responses	Stored Response objects are retained by default or when store: true; store: false disables retrieval.	Set store: false unless the product needs later retrieval or previous_response_id.
Background mode	Stores response data briefly for polling and requires stored state.	Use only when supported; otherwise run your own async job and stateless model call.
Files and batches	Uploaded files, batches, evals, and fine-tuning artifacts persist until deleted or expired.	Add expires_after where supported and schedule cleanup jobs.
Tools and MCP	Data sent to remote tools or MCP servers follows that third party's policy.	Classify every tool call as an external data transfer.
Prompt caching	Caches can improve latency/cost but are not a deletion or privacy boundary.	Keep user-specific data after the shared prefix and avoid raw identifiers in cache keys.

Retention controls are not universal

OpenAI's Zero Data Retention and Modified Abuse Monitoring controls are approved account settings, not request flags that every endpoint automatically honors. Even when a provider offers similar controls, some features may still create application state because the feature cannot work without it: stored responses, background polling, files, batches, eval artifacts, vector stores, hosted tools, video jobs, or third-party tool calls. For AvalAI deployments, treat retention as a per-route contract: confirm the selected model, endpoint, provider, and feature flags before accepting regulated data or promising deletion timelines.

If your privacy design depends on stateless behavior, prefer store: false, app-managed conversation history, short-lived files, explicit cleanup jobs, and standalone /v1/moderations calls that do not retain application state.

Responses-specific retention checks

For Responses workflows, review these surfaces before launch:

• Stored responses: when a route honors OpenAI-style storage, a Response can be retrievable later unless you set store: false; OpenAI's reference retention for stored Responses is at least 30 days. Use store: true only for features that need previous_response_id, polling, retrieval, or debugging with explicit retention approval.
• Background mode: OpenAI's reference behavior stores response data for roughly 10 minutes so clients can poll or reconnect. In AvalAI, treat background: true as incompatible with strict stateless or zero-retention designs unless your route contract says otherwise.
• Audio outputs: multi-turn audio workflows may require short-lived application state so later turns can reference generated audio; OpenAI's reference retention for this state is 1 hour. Keep audio retention separate from text-response retention in your data-flow diagram.
• Compaction: server-side compaction is designed to carry forward opaque machine state. If the route supports store: false, do not persist compaction items outside your own retention policy.
• Third-party tools: remote MCP servers, hosted code/shell tools, live web search, and provider-native connectors can create separate external retention obligations. Document them as data processors, not as ordinary model parameters.

Stateless by Default

For new Responses API workflows, set store: false unless you explicitly need to retrieve the response later. If the selected route does not support store, treat the request as provider-dependent and keep your own retention policy conservative.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    instructions="Answer using only the provided support policy.",
    input="Summarize the refund policy in two bullets.",
    store=False,
    safety_identifier="user_hash_8f3a2c",
)

print(response.output_text)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.5",
  instructions: "Answer using only the provided support policy.",
  input: "Summarize the refund policy in two bullets.",
  store: false,
  safety_identifier: "user_hash_8f3a2c",
});

console.log(response.output_text);

For Chat Completions, resend only the turns needed for the answer and keep long-term conversation memory in your own database when policy allows. Do not log full prompts by default.

For stateless multi-turn reasoning, preserve required reasoning continuity without storing the response object by requesting encrypted reasoning items and replaying the returned response.output items in your own history.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

history = [{"role": "user", "content": "Draft a two-step migration plan."}]

response = client.responses.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    input=history,
    store=False,
    include=["reasoning.encrypted_content"],
)

history += response.output
history.append({"role": "user", "content": "Now make it safer for production."})

follow_up = client.responses.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    input=history,
    store=False,
    include=["reasoning.encrypted_content"],
)

print(follow_up.output_text)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const history = [{ role: "user", content: "Draft a two-step migration plan." }];

const response = await client.responses.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.5",
  input: history,
  store: false,
  include: ["reasoning.encrypted_content"],
});

history.push(...response.output);
history.push({ role: "user", content: "Now make it safer for production." });

const followUp = await client.responses.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.5",
  input: history,
  store: false,
  include: ["reasoning.encrypted_content"],
});

console.log(followUp.output_text);

When Stored State Is Useful

Some features need stored state to work well:

• previous_response_id and conversation objects: useful for multi-turn workflows, but prefer manual replay with store: false for regulated data.
• Background processing: OpenAI's reference background mode stores response data briefly for polling and requires stored state. In AvalAI, use hosted background: true only when the selected route supports it; otherwise use your own job table and a stateless model call.
• Files API: set expires_after for temporary files and call DELETE when you no longer need a file.
• Batch, evals, fine-tuning, and vector stores: treat uploaded datasets and generated artifacts as persistent until deleted or expired by the provider.

Prompt Caching and Privacy

Prompt caching is an optimization, not a data-control boundary. Use it carefully:

• Put stable policy text and tool schemas first; put user-specific details last.
• Use prompt_cache_key for workload bucketing, not as a raw user identifier.
• Keep prompt_cache_key separate from safety_identifier.
• Use prompt_cache_retention only when the selected model, route, and account support it.
• For strict retention requirements, confirm whether the provider uses in-memory or extended cache retention.
• For OpenAI-family models that require extended prompt caching, do not set prompt_cache_retention: "in_memory" unless the selected AvalAI route explicitly documents support for it.

OpenAI documents that extended prompt caching can retain model key/value tensors for up to 24 hours on supported models; AvalAI availability depends on the upstream route. Do not promise cache-retention guarantees to customers without provider confirmation.

File and Tool Hygiene

• Prefer public URLs only for public documents; use Base64 or Files API for private documents.
• Delete uploaded files after processing if they do not need reuse.
• Treat image and file inputs as special retention surfaces: upstream safety scanners may retain flagged media for manual review even when stricter retention controls are enabled.
• Redact secrets, credentials, payment details, private keys, and unrelated PII before model calls.
• Validate tool arguments before execution and tool outputs before returning them to the model.
• Require human approval before tools modify accounts, send messages, delete data, make payments, or call external systems.
• Classify live web search, remote MCP servers, hosted code/shell tools, and provider-native connectors as external or provider-managed processing. Use offline/cache-only search modes only when the selected AvalAI route explicitly supports them, and do not assume third-party retention, residency, HIPAA, or BAA terms match AvalAI's policy.

Data Residency and Regional Routes

OpenAI's data residency controls are configured at the project level and use region-specific API domains for eligible endpoints, models, and account settings. When you call through AvalAI, do not assume those OpenAI regional domains, Zero Data Retention settings, or regional processing guarantees automatically apply to the AvalAI route.

For regulated deployments, capture a provider-route evidence record before launch:

• selected AvalAI endpoint, provider, model ID, and service tier;
• whether customer content is stored only in the required region, processed in-region, or routed globally;
• whether prompt caching, background jobs, Files API, tools, web search, video generation, or provider-native connectors create application state outside the primary model call;
• whether the customer account has a signed data-processing, residency, BAA/HIPAA, or enterprise retention agreement for that exact route;
• fallback behavior if the preferred regional route is unavailable.

Keep residency separate from security controls. Encryption, store: false, moderation, prompt caching, and data residency solve different problems and should be verified independently.

Enterprise Key Management and BYOK

OpenAI documents Enterprise Key Management (EKM) for eligible application state, with keys synced from supported external key-management systems. Do not assume those OpenAI controls apply automatically when you access models through AvalAI or another upstream provider.

For customer-managed encryption requirements:

• confirm whether the exact AvalAI route, provider, endpoint, and stored artifact type support BYOK/EKM;
• identify which state is covered: stored Responses, Files API objects, vector stores, batches, evals, fine-tuning artifacts, hosted tool containers, or provider logs;
• define the error path when a requested endpoint is incompatible with the customer's key-management policy;
• keep application-side encryption for your own databases, logs, queues, and object storage even when a provider offers EKM for its application state.

Production Checklist

• Add a data-flow diagram for each route that receives customer content.
• Document whether each request uses store, previous_response_id, background mode, Files API, Batch API, tools, or external search.
• Record whether provider-side application state is covered by customer-managed encryption or must be avoided for that workflow.
• Set safety_identifier to a stable hash or opaque ID; never send raw email, phone, or username.
• Log x-request-id, model, route, token usage, latency, and error class without storing full customer content.
• Verify provider retention behavior for the exact model and endpoint before accepting regulated or sensitive data.

Related Guides

• Privacy Policy
• Content Policy
• Conversation State
• Background Processing
• Prompt Caching
• Safety Best Practices
• Files API