Hidoba Metadata

Messages API v3 accepts optional Hidoba-specific request metadata under metadata.hidoba.

Only these fields are allowed:

Field	Type	Description
character	String or object	GitHub character reference or inline character object.
character_params	Object	Flat template parameters for the character personality. Values may be string, number, boolean, or null.

All other metadata.hidoba fields are rejected. This includes rag, routing, request_id, and unknown fields.

GitHub Character

Use a GitHub character reference when the character is stored server-side:

{
  "metadata": {
    "hidoba": {
      "character": "github:partner/CharacterName",
      "character_params": {
        "person_name": "Alex"
      }
    }
  }
}

github-force: is also accepted for force-refresh flows:

{
  "metadata": {
    "hidoba": {
      "character": "github-force:partner/CharacterName"
    }
  }
}

rc2 validates that the quota is allowed to use the requested character.

Inline Character

Use an inline character object for ad hoc testing or cases where the character is supplied with the request:

{
  "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 and helpful."
      }
    }
  }
}

Inline characters must pass rc2 character validation. Some existing character schemas include max_new_tokens as legacy character metadata. Messages API v3 does not use character max_new_tokens to control generation length; use request-level token limits instead.

Character Params

character_params are rendered into Jinja character personality templates.

{
  "metadata": {
    "hidoba": {
      "character": "github:partner/CharacterName",
      "character_params": {
        "person_name": "Alex",
        "plan": "premium"
      }
    }
  }
}

Rules:

• character_params must be a JSON object.
• Values must be string, number, boolean, or null.
• character_params.context is reserved and rejected.

RAG

Do not send RAG config in metadata.hidoba.

Invalid:

{
  "metadata": {
    "hidoba": {
      "rag": { "enabled": true }
    }
  }
}

RAG is server-owned and is derived from character and server config. Current character parameter keys recognized by Messages API v3 include:

Character parameter	Purpose
texting_rag_enabled or rag_enabled	Enables or disables RAG.
texting_rag_index, rag_index, or rag_index_required	Selects the RAG index.
texting_rag_max_context_tokens, rag_max_context_tokens, llm_texting_rag_retrieve_max_tokens_override, or llm_rag_retrieve_max_tokens_override	Sets the maximum retrieved context size.
texting_rag_rewrite_enabled, rag_rewrite_enabled, or query_rewrite_enabled	Enables query rewriting.
texting_rag_character_replacement_name, rag_character_replacement_name, or character_rag_you_replacement_name	Controls character name replacement in retrieved context.

When enabled, retrieval is handled internally and may use dense, SPLADE, and BM25 signals. The public Messages API v3 does not expose a SPLADE embedding endpoint.

Routing

Do not send routing config in metadata.hidoba.

Invalid:

{
  "metadata": {
    "hidoba": {
      "routing": {
        "primary_model": "google/gemini-2.5-flash"
      }
    }
  }
}

Routing is server-owned. To request a fallback model, use top-level fallback_model:

{
  "model": "google/gemini-2.5-flash",
  "fallback_model": "qwen/qwen3.6-27b"
}

Messages API v3 converts this into provider routing before the request reaches the model.

Provider Visibility

metadata.hidoba is removed before the provider-visible payload is sent. Non-Hidoba metadata is preserved:

{
  "metadata": {
    "client": "kept",
    "hidoba": {
      "character": "github:partner/CharacterName"
    }
  }
}

The model provider sees:

{
  "metadata": {
    "client": "kept"
  }
}