REST API

All public Messages API v3 endpoints are under:

https://msg.hidoba.com

Authentication

Send a quota API key with each generation request. Bearer auth is preferred.

curl https://msg.hidoba.com/v3/chat/completions \
  -H "Authorization: Bearer YOUR_QUOTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-2.5-flash","messages":[{"role":"user","content":"Say hello"}]}'

X-API-Key is also accepted:

X-API-Key: YOUR_QUOTA_API_KEY

Health

GET /health
GET /health/deep

Health endpoints are intended for uptime checks and deployment verification.

Chat Completions

POST /v3/chat/completions

Compatibility alias:

POST /v1/chat/completions

The request body follows the OpenAI Chat Completions shape. Messages API v3 also accepts a small number of Hidoba-specific additions.

Field	Type	Required	Description
model	String	Yes	Requested model name, for example google/gemini-2.5-flash.
messages	Array	Yes	OpenAI-compatible chat messages.
stream	Boolean	No	Set to true for streaming responses.
max_completion_tokens	Number	No	Preferred output-token limit for compatible providers.
max_tokens	Number	No	Compatibility output-token limit.
reasoning	Object	No	OpenRouter-style reasoning control.
fallback_model	String	No	Optional fallback model for routing/content-policy retry. This is not sent provider-visible as fallback_model.
metadata.hidoba	Object	No	Hidoba character metadata. See Hidoba Metadata.

Example

curl https://msg.hidoba.com/v3/chat/completions \
  -H "Authorization: Bearer $HIDOBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      { "role": "user", "content": "Reply with exactly: hello" }
    ],
    "max_completion_tokens": 32
  }'

The response is the provider/Bifrost OpenAI-compatible chat completion response.

Responses API

POST /v3/responses

Compatibility alias:

POST /v1/responses

The request body follows the OpenAI Responses API shape.

Field	Type	Required	Description
model	String	Yes	Requested model name.
input	String or Array	Yes	Responses API input.
instructions	String	No	Additional system instructions. Character and RAG prompts may be injected by Messages API v3 when configured.
stream	Boolean	No	Set to true for streaming responses when supported.
max_output_tokens	Number	No	Output-token limit for Responses API requests.
reasoning	Object	No	OpenRouter-style reasoning control.
fallback_model	String	No	Optional fallback model.
metadata.hidoba	Object	No	Hidoba character metadata. See Hidoba Metadata.

Example

curl https://msg.hidoba.com/v3/responses \
  -H "Authorization: Bearer $HIDOBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "input": "Write one concise sentence about Mars.",
    "max_output_tokens": 80
  }'

The response is the provider/Bifrost OpenAI-compatible Responses API response.

Reasoning

Use OpenRouter-style reasoning controls when the requested model/provider supports them.

Turn reasoning off:

{
  "reasoning": { "effort": "none" }
}

Use an effort level:

{
  "reasoning": { "effort": "low" }
}

Accepted effort values are none, low, medium, and high.

Use a token budget:

{
  "reasoning": { "max_tokens": 1024 }
}

Reasoning support depends on the resolved provider and model.

Errors

Generation requests may fail before reaching the model if rc2 rejects the API key, quota, character, or metadata.

Status	Meaning
400	Invalid request body, invalid metadata.hidoba, or character validation failure.
401	Missing or invalid quota API key.
403	Quota type or access is not allowed for this endpoint.
409	Duplicate request id in rc2 lifecycle tracking.
429	Quota is exhausted.
5xx	Provider, Bifrost, or internal service failure.

Example error:

{
  "detail": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "context": {
      "request_id": "7ed3d6f1-1a9f-4f3b-90d3-7c681a9d9fb8",
      "endpoint": "/v3/chat/completions"
    }
  }
}

Provider errors are proxied in the provider/Bifrost response shape.