> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# GMI Router Overview
The GMI Router turns a plain-language request into the right model for the job. You send an intent or a full chat, and the API ranks the eligible models by task-category fit, quality, and cost, then either hands back a ranked list or routes the request straight to the best model and returns the completion.
Access the playground here: [https://console.gmicloud.ai/user-console/ie/gmi-router/test-routing](https://console.gmicloud.ai/user-console/ie/gmi-router/test-routing)
## **How routing works**
Autoroute treats model selection as a process, not a single guess. Every Autoroute request moves through the same sequence:
1. **Understand.** The router reads your latest message and classifies the task and its requirements.
2. **Compare.** It scores the allowed model pool across quality, cost, and latency.
3. **Validate.** The top candidate is checked before it is committed. A high score alone does not win the request.
4. **Select.** The router locks in the winning model.
5. **Respond.** The selected model generates the completion, returned inline or streamed token by token.
The flow, at a glance: Prompt -> Understand -> Compare -> Validate -> Select -> Respond.
Two ways to use it:
* **/autoroute** picks the model and returns the completion in one call. Streaming is the default.
## **Authentication**
Base URL: `https://console.gmicloud.ai/api/v1/ie/recommendation`
Send a bearer token in the Authorization header:
`Authorization: Bearer YOUR_TOKEN`
Most routed responses include an X-Recommendation-ID header. It is absent on auth and early validation errors. Keep this value if you plan to submit feedback later.
## **Quick start: Autoroute**
Send an OpenAI-style messages\[] array. The router reads the latest user message, ranks the model pool, and generates with the top candidate.
```text theme={null}
curl -X POST https://console.gmicloud.ai/api/v1/ie/recommendation/autoroute \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{ "role": "user", "content": "Summarize this contract in three bullet points." }
],
"mode": "balanced",
"stream": false
}'
```
Non-streaming response:
```text theme={null}
{
"model": "provider/model-name",
"message": { "role": "assistant", "content": "..." },
"routing_metadata": {
"selected_model": "provider/model-name",
"task_type": "summarization",
"selected_mode": "balanced",
"fallback_models": ["provider/backup-a"],
"recommendation_id": "bab0a8bb-195f-49c5-8f9c-016da0d89cc8"
}
}
```
### **Request fields**
| **Field** | **Type** | **Required** | **Description** |
| :--------- | :------- | :----------- | :----------------------------------------------------------------------------------------------- |
| `messages` | array | Yes | OpenAI-style conversation. The full conversation influences routing, not only the latest message |
| `mode` | string | No | Accepted values are cost, balanced, or quality. Unknown request fields are ignored. |
| `stream` | boolean | No | Streaming is the default. Set false for one-shot JSON. |
### **Streaming vs non-streaming**
* **Streaming (default).** Returns text/event-stream. Chunks are proxied as they arrive, followed by a routing\_metadata event, then \[DONE]. One backup model may be tried before the first token on a 5xx, provider error, 429, or a 10-second first-token timeout. Once tokens start flowing, no further fallback happens; a mid-stream failure keeps the partial output, sends an error event, and closes the stream.
* **Non-streaming (stream: false).** Returns one JSON object with up to two ordered backups on a transient failure (5xx, provider error, 429, or a 30-second timeout).
The router is stateless. Resend the full conversation on every request.
## **Quick start: Recommendations**
Get a ranked list of models without generating anything.
```text theme={null}
curl -X POST https://console.gmicloud.ai/api/v1/ie/recommendation/recommendations \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"intent": "cheap text generation for summarization",
"mode": "balanced"
}'
```
Response:
```text theme={null}
{
"recommendation_id": "bab0a8bb-195f-49c5-8f9c-016da0d89cc8",
"parsed": { "category": "llm", "use_case": "summarization", "confidence": 0.95 },
"recommendations": [
{
"model_id": "provider/model-name",
"name": "Model Name",
"provider": "provider",
"is_top": true,
"reason_badge": "best value",
"estimated_cost_savings": { "amount": 0.0042, "currency": "USD" }
}
]
}
```
Notes on the response:
* estimated\_cost\_savings appears only on the top recommendation, and only when the estimate is positive.
* V1 recommends LLMs only, so category is always llm.
### **Request fields**
| **Field** | **Type** | **Required** | **Description** |
| :-------- | :------- | :----------- | :---------------------------------------------------- |
| `intent` | string | Yes | Plain-language description of the task. |
| `mode` | string | No | cost, balanced, or quality. Unknown keys are ignored. |
## **Submitting feedback**
Feedback is write-once per recommendation. Use the recommendation\_id from a recommendation or from autoroute routing metadata.
```text theme={null}
curl -X POST https://console.gmicloud.ai/api/v1/ie/recommendation/recommendations/{id}/feedback \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "signal": "down", "reasons": ["wrong_task_type", "too_slow"] }'
```
Rules:
* `signal` is `up` or `down`.
* For `down`, include one or more `reasons` with no duplicates.
* For `up`, omit `reasons` entirely.
* A second submission for the same recommendation returns `409`.
Allowed reasons: `not_the_model_i_want, wrong_task_type, model_quality_poor, too_slow, cost_not_meaningfully_lower, model_unavailable, not_allowed_by_policy, prefer_another_model, other.`
## **Routing settings**
Routing settings define which models are eligible and how they are ranked. Org owners set the hard bounds; each user sets a preference within those bounds.
| **Endpoint** | **Method** | **Purpose** |
| :----------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/routing-settings` | GET | Read the org bounds, your preference, and the resolved merge. is\_org\_owner shows whether org settings are editable. |
| `/routing-settings/org` | PUT | Replace org-level bounds: model scope, allowed model pool, and workspace defaults. Org owners only.
For PUT /routing-settings/org, allowed\_model\_pool cannot be omitted or empty. To allow all models, list every supported model ID. However, orgs with no saved settings, or legacy empty pools, resolve to the full catalog on GET. |
| `/routing-settings/user` | PUT | Set your own mode and Auto Mode preference within the org bounds. |
Defaults when fields are omitted on the org update: model scope all, mode balanced, and Auto Mode on.
## **Health checks**
Both are unauthenticated.
| **Endpoint** | **Method** | **Purpose** |
| :----------- | :--------- | :----------------- |
| `/health` | GET | Service health. |
| `/ready` | GET | Service readiness. |
## **Status codes**
| **Code** | **Meaning** |
| :------- | :-------------------------------------------------- |
| `200` | Success. |
| `401` | Missing or invalid credentials. |
| `403` | Caller is not an org owner (org settings only). |
| `404` | No eligible models survived the filters. |
| `409` | Feedback already submitted for this recommendation. |
| `422` | Invalid body, or no user message. |
| `500` | Ranking weights unavailable. |
| `502` | Every candidate model failed to generate. |
| `504` | Upstream pricing or signal source timed out. |