API Reference

Base URL

https://gateway.datahippo.io/v1

Endpoints

POST /chat/completions

Create a chat completion. Supports both streaming and non-streaming responses.

Full path: POST /api/gateway/v1/chat/completions

Request Body

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

Field	Type	Required	Description
model	string	Yes	Model identifier (e.g., "gpt-4o", "claude-3-5-sonnet", "auto").
messages	array	Yes	Array of message objects. Max 1000 messages, max 1MB per message.
temperature	number	No	Sampling temperature, 0.0–2.0. Higher values produce more random output.
max_tokens	integer	No	Maximum tokens to generate. Max 1,000,000.
top_p	number	No	Nucleus sampling threshold, 0.0–1.0.
n	integer	No	Number of completions to generate. Max 10.
stream	boolean	No	If true, response is streamed as Server-Sent Events.
stop	string or array	No	Stop sequence(s) where generation halts.
frequency_penalty	number	No	Frequency penalty, -2.0–2.0.
presence_penalty	number	No	Presence penalty, -2.0–2.0.
user	string	No	End-user identifier for abuse monitoring.
seed	integer	No	Seed for deterministic sampling.
tools	array	No	Tool/function definitions the model may call.
tool_choice	string or object	No	Controls tool usage: "none", "auto", "required", or a specific function.
response_format	object	No	Response format: {"type": "text"}, {"type": "json_object"}, or {"type": "json_schema"}.
thinking	object	No	Extended thinking config: {"type": "enabled", "budget_tokens": 10000}.
reasoning_effort	string	No	For o-series models: "low", "medium", or "high".
prompt_config	string	No	Name of a Flow prompt config to apply. Alternative to the X-DataHippo-Prompt-Config header.
prompt_variables	object	No	Template variables for the managed prompt. Alternative to X-DataHippo-Var-* headers.

Message Object

Field	Type	Required	Description
role	string	Yes	"system", "user", "assistant", or "tool".
content	string or array	Yes	Text content or array of content parts (for multimodal).
name	string	No	Author name for multi-user conversations.
tool_calls	array	No	Tool calls made by the assistant.
tool_call_id	string	No	For tool messages: ID of the tool call being responded to.

Content Parts (Multimodal)

When content is an array, each element is a content part:

[
  {"type": "text", "text": "What's in this image?"},
  {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
  {"type": "document_url", "document_url": {"url": "data:application/pdf;base64,..."}}
]

Response (Non-Streaming)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 10,
    "total_tokens": 35
  }
}

Response (Streaming)

When stream: true, the response is a stream of SSE events:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":25,"completion_tokens":2,"total_tokens":27}}

data: [DONE]

GET /models

List supported model prefixes.

Full path: GET /api/gateway/v1/models

---

Request Headers

Required

Header	Description
Authorization	Bearer dh_your_key — your DataHippo API key.

Optional

Header	Description
X-DataHippo-Prompt-Config	Name of the prompt config to apply. Alternative to the prompt_config body field.
X-DataHippo-Session-Id	Session identifier for session budgets and session-sticky rollout allocation.
X-DataHippo-User-Id	User identifier for user-sticky rollout allocation.
X-DataHippo-Force-Variant	Force a rollout variant: "target" or "baseline". For debugging only.
X-DataHippo-Var-{name}	Template variable value. Header name is normalized: x-datahippo-var-user-name becomes user_name. Max 255 characters per value.

Response Headers

Header	Description
x-datahippo-provider	Provider that served the response (e.g., openai, anthropic).
x-datahippo-model-used	Model that generated the response.
x-datahippo-original-model	Original requested model (present when failover occurred).
x-datahippo-fallback-used	"true" when a fallback provider was used.
x-datahippo-retry-count	Number of retries before the request succeeded.
x-datahippo-cache	Cache status: "hit", "miss", or "skip".
x-datahippo-warning	Warning message (e.g., explicit mode but no prompt_config sent).
x-output-contract-violation	"true" when the response failed output schema validation but was passed through.
x-request-id	Unique request ID for tracing and correlation.

Error Responses

Errors follow a standard format:

{
  "error": {
    "message": "Description of what went wrong",
    "type": "error_type",
    "code": "error_code"
  }
}

HTTP Status	Condition
400	Validation error (empty messages, invalid temperature, etc.)
401	Missing or invalid API key / project ID
404	Prompt config not found
422	Template variable validation failed
429	Session budget exceeded
500	Provider error or internal failure
503	Provider unavailable after retries and failover