API Reference Overview

The DeepIntShield gateway exposes documented routes compatible with selected OpenAI, Anthropic, and Google Gemini wire formats. Point a supported client at the matching route and supply a Virtual Key. Guardrails, caching, routing, and logging apply only when enabled, entitled, and supported for that route. For a compatible endpoint, migration usually needs a base-URL and credential change; verify route-specific parameters, streams, tools, uploads, batches, headers, and error shapes before migration.

For Python applications, the deepintshield SDK adds typed provider builders, explicit guardrail and RAG evaluation, MCP adapters, Agentic enforcement, and a centralized error-code catalog.

Base URL

Point your client at the hosted DeepIntShield cloud gateway:

https://app.deepintshield.com

If you run an Enterprise VPC or self-hosted data plane, replace the host with the ingress for your data-plane gateway (for example https://<your-deepintshield-host>). Exact enabled routes depend on the deployed release and configuration. See Setting up the gateway.

Authentication

Inference requests are authenticated with a virtual key. Create and manage keys from the Web UI - see Virtual Keys.

The gateway accepts the virtual key in any of the following headers, so you can keep using whichever header your existing client already sends:

Header	Typical client
x-deepintshield-vk: sk-ds-your-virtual-key	DeepIntShield-native clients
Authorization: Bearer sk-ds-your-virtual-key	OpenAI SDKs and most HTTP clients
x-api-key: sk-ds-your-virtual-key	Anthropic SDK
x-goog-api-key: sk-ds-your-virtual-key	Google Gemini SDK

curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPINTSHIELD_VIRTUAL_KEY" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello, DeepIntShield!"}]
  }'

Note

The model value carries the provider prefix (for example openai/gpt-4o-mini or anthropic/claude-3-5-sonnet). DeepIntShield uses the prefix to resolve which configured provider to route to. See Supported providers.

Unified OpenAI-compatible endpoints

These routes use the unified OpenAI-style request/response shape. The gateway translates when the selected provider supports the corresponding request type; not every provider implements every endpoint or parameter. Send them to the gateway base URL.

Method	Path	Purpose
POST	/v1/chat/completions	Chat completions (streaming and non-streaming)
POST	/v1/responses	OpenAI Responses API
POST	/v1/responses/compact	Compact a Responses conversation
GET, DELETE	/v1/responses/{response_id}	Retrieve, stream retrieval, or delete a stored response
POST	/v1/responses/{response_id}/cancel	Cancel a stored response
GET	/v1/responses/{response_id}/input_items	List input items when the provider supports it
POST	/v1/completions	Legacy text completions
POST	/v1/embeddings	Embeddings
POST	/v1/rerank	Reranking
POST	/v1/audio/speech	Text-to-speech
POST	/v1/audio/transcriptions	Speech-to-text
POST	/v1/images/generations	Image generation
GET	/v1/models	List available models
GET	/health	Gateway health check (no auth)

Streaming responses follow the standard OpenAI Server-Sent Events format - set "stream": true in the request body. See Streaming. Stored Responses availability differs by provider; see the exact lifecycle matrix.

Resource, realtime, and OCR routes

These routes retain their provider-native resource semantics. Model-less operations require a provider selector and, when more than one key is eligible, the same explicit configured-key selector used to create the resource.

Method	Path	Purpose
POST, GET	/v1/cached_contents	Create or list named Gemini or Vertex cached content
GET, PATCH, DELETE	/v1/cached_contents/{cached_content_name}	Inspect metadata, update expiry, or delete cached content
POST	/v1/ocr	Run Mistral OCR
GET	/v1/realtime	Upgrade to a Realtime WebSocket frame relay
POST	/v1/realtime/client_secrets	Create an ephemeral Realtime client secret
POST	/v1/realtime/sessions	Pass through WebRTC SDP/session negotiation
POST	/v1/realtime/transcription_sessions	Negotiate realtime transcription
POST	/v1/realtime/translations/client_secrets	Create a translation client secret
POST	/v1/realtime/calls	Proxy provider-native call creation
POST	/v1/realtime/calls/{call_id}/{action}	Proxy accept, hangup, refer, or reject

Gemini-compatible cached-content routes are also exposed as /v1beta/cachedContents. Realtime call control is a provider-native proxy, not SIP or full telephony orchestration. See Protocol operations for request formats, provider coverage, key affinity, and transport limits.

Management and enterprise routes

When durable webhooks are enabled with a SQL store, management routes under /api/webhooks create and disable subscriptions, enqueue idempotent events, inspect deliveries, and replay any delivery that is not currently in progress. They use management authorization rather than an inference virtual key. See Durable webhooks and object storage for the canonical route table and deployment constraints.

Delegated MCP authentication remains part of inference/tool execution rather than a separate public route family. Callers provide X-MCP-Subject-Token only for a configured OAuth-enabled Streamable HTTP client. See Delegated MCP authentication for isolation, pool, and protocol boundaries.

Asynchronous jobs

The current gateway exposes asynchronous submit and poll routes for the following request types. Submission returns a job ID; polling uses the same path plus /{job_id}.

Submit path
/v1/async/completions
/v1/async/chat/completions
/v1/async/responses
/v1/async/embeddings
/v1/async/rerank
/v1/async/audio/speech
/v1/async/audio/transcriptions
/v1/async/images/generations
/v1/async/images/edits
/v1/async/images/variations

Async Responses rejects stream=true. See Async inference for submission and polling examples.

Provider-format compatibility routes

If you prefer to keep your client speaking a provider’s exact dialect, send requests to the matching compatibility prefix. The gateway converts the documented shapes and applies features supported on that route.

OpenAI

Prefix every OpenAI path with /openai:

POST /openai/v1/chat/completions
POST /openai/v1/responses
POST /openai/v1/embeddings
GET  /openai/v1/models

See the OpenAI integration.

Anthropic

Prefix every Anthropic path with /anthropic:

POST /anthropic/v1/messages
POST /anthropic/v1/messages/count_tokens
GET  /anthropic/v1/models

See the Anthropic integration.

Gemini

Prefix every Google Gemini path with /genai:

POST /genai/v1beta/models/{model}:generateContent
POST /genai/v1beta/models/{model}:streamGenerateContent
POST /genai/v1beta/models/{model}:embedContent
GET  /genai/v1beta/models

See the Gemini (GenAI) integration.

Raw provider passthrough is a separate route family and can have different policy/cache behavior. See Passthrough integrations and browse the compatibility guides under Integrations.

Errors

Errors are returned with standard HTTP status codes and a JSON body. Do not use HTTP status alone as the application branch: parse the stable code when the body supplies one and retain the request/decision identifier for operations. Common status classes include:

Status	Meaning
401	Missing or invalid virtual key
403	Request blocked by a guardrail or governance policy
429	Rate limit or budget exceeded
5xx	Upstream provider or gateway error

Provider-native clients raise their own HTTP exception types. Direct DeepintShield.request(), RAG, guardrail, and MCP calls raise DeepintShieldError with normalized code, trusted description, retryable, details, status_code, and raw message/payload fields. Review details before display or logging, and keep raw gateway data in protected diagnostics. See SDK error codes for the catalog, retry rules, and forward-compatibility contract.

Where to next

Connect a provider

Add your provider keys and pick models.

Supported providers →

Use protocol operations

Manage stored Responses, cached content, realtime sessions, and OCR.

Protocol operations →

Use an SDK

Drop-in adapters for OpenAI, Anthropic, Gemini, and more.

Browse integrations →

Secure traffic

Configure guardrails across input, output, and tool calls.

Configure guardrails →

Manage keys

Create virtual keys, budgets, and rate limits.

Virtual keys →