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.

GitHub Character

Use a GitHub character reference when the character is saved in Hidoba:

{
  "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"
    }
  }
}

Hidoba 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 Hidoba 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.

Knowledge Context

Knowledge context is configured in the character settings. This works the same way whether the character is referenced from GitHub or supplied inline.

For a GitHub character, configure the knowledge settings in the saved character file and reference the character:

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

For an inline character, include the knowledge settings inside the character parameters object:

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

When knowledge context is configured, Messages API v3 may add relevant context automatically before the model answers.

In character settings:

• rag_enabled turns knowledge context on for that character.
• rag_index_required selects which saved knowledge base the character should use.

Model Fallback

Do not send routing config in metadata.hidoba.

Invalid:

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

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 uses this as a routing option when supported.

Model Conversation Visibility

metadata.hidoba is Hidoba-only request metadata and is not included in the model conversation. Non-Hidoba metadata is preserved:

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

The model request keeps:

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