Examples

Chat Completion

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": "Hi, can you help me test the API?" },
      { "role": "assistant", "content": "Yes. Send me the exact reply you want." },
      { "role": "user", "content": "Reply with exactly: hello" }
    ],
    "max_completion_tokens": 32
  }'

Streaming Chat Completion

curl -N 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": "Can you write short poems?" },
      { "role": "assistant", "content": "Yes, I can keep them concise." },
      { "role": "user", "content": "Write a two-line poem about rain." }
    ],
    "stream": true,
    "max_completion_tokens": 80
  }'

Responses API

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": "Explain semantic search in one sentence.",
    "max_output_tokens": 80
  }'

Streaming Responses With Knowledge Sources

When a character has knowledge context enabled, streaming Responses calls can include status and source events before the model's answer.

curl -N https://msg.hidoba.com/v3/responses \
  -H "Authorization: Bearer $HIDOBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "stream": true,
    "input": [
      { "role": "user", "content": "What should I know from the knowledge base?" }
    ],
    "max_output_tokens": 240,
    "metadata": {
      "hidoba": {
        "character": "github:partner/KnowledgeCharacter"
      }
    }
  }'

Example stream fragments:

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"rs_hidoba_rag_loading_123","type":"reasoning","summary":[{"type":"summary_text","text":"Looking through the knowledge base..."}]}}

event: response.file_search_call.completed
data: {"type":"response.file_search_call.completed","output_index":1,"item":{"id":"fs_hidoba_123","type":"file_search_call","status":"completed","queries":["What should I know from the knowledge base?"],"results":[{"file_id":"file_hidoba_07d6ebeddf6a421c","filename":"Product Notes","score":0.91,"text":"Product Notes # Overview The product supports...","attributes":{"chunk_index":0,"retrievers":"dense,splade"}}]}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":2,"item":{"id":"rs_hidoba_rag_found_123","type":"reasoning","summary":[{"type":"summary_text","text":"Found 1 relevant documents, thinking..."}]}}

Render the reasoning.summary[].text values as status messages and file_search_call.results[] as sources. Each source text value is a short preview, not the full document chunk.

If model thinking is enabled, you may also receive response.reasoning_text.delta and response.reasoning_text.done events. Display those as thinking text, not as the final answer.

GitHub Character

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": "I want a practical coaching answer." },
      { "role": "assistant", "content": "I will keep it practical and encouraging." },
      { "role": "user", "content": "How should I start practicing today?" }
    ],
    "max_completion_tokens": 120,
    "metadata": {
      "hidoba": {
        "character": "github:partner/Coach",
        "character_params": {
          "person_name": "Alex"
        }
      }
    }
  }'

Inline Character

Use an inline character when you want to provide the character prompt in the request.

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Give me a warm one-sentence greeting." }
  ],
  "max_completion_tokens": 80,
  "metadata": {
    "hidoba": {
      "character": {
        "parameters": {
          "name": "Mira",
          "language": "en",
          "person_name": "Alex",
          "robot_name": "Mira",
          "name_colon": "Mira:",
          "conversation_prefix": "",
          "interruption_message": "",
          "easy_questions": [],
          "difficult_questions": [],
          "voice": null,
          "greetings": [],
          "max_new_tokens": 128
        },
        "personality": "You are {{ robot_name }}. Be concise, friendly, and helpful."
      }
    }
  }
}

Reasoning Effort

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "I need a direct answer." },
    { "role": "assistant", "content": "Understood. I will keep it direct." },
    { "role": "user", "content": "Think briefly, then answer with one paragraph." }
  ],
  "reasoning": { "effort": "low" },
  "max_completion_tokens": 200
}

Use none to turn reasoning off:

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

Use a token budget when the model supports it:

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

Fallback Model

{
  "model": "google/gemini-2.5-flash",
  "fallback_model": "qwen/qwen3.6-27b",
  "messages": [
    { "role": "user", "content": "I am brainstorming features." },
    { "role": "assistant", "content": "Great. I can suggest concise ideas." },
    { "role": "user", "content": "Give me one concise product idea." }
  ],
  "max_completion_tokens": 100
}

fallback_model is a Hidoba routing option. It is not part of the model conversation.

Character With Knowledge Context

Knowledge context is configured in the character settings. With a GitHub character, the settings live in the saved character. With an inline character, put them in the character parameters.

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "What should I remember from the knowledge base?" }
  ],
  "max_completion_tokens": 160,
  "metadata": {
    "hidoba": {
      "character": {
        "parameters": {
          "robot_name": "Mira",
          "rag_index_required": "partner/knowledge-base-name",
          "rag_enabled": true
        },
        "personality": "You are {{ robot_name }}. Use the available knowledge context when relevant."
      }
    }
  }
}

Here, rag_enabled turns knowledge context on, and rag_index_required selects the saved knowledge base for the character.