Welcome to the Frosty AI API Reference! Below you'll find everything you need to know to interact with Frosty AI, including authorization, endpoints, request/response formats, and error handling.
🔑 Authorization
To interact with the Frosty AI API, you need:
-
Router ID — Unique ID for your Frosty router.
-
Router Key — Secret key for authenticating requests.
You can find both inside the Router Details page in the Frosty AI console.
🔐 Example of Authorization (Query Params)
https://api.gofrosty.ai/chat?router_id={ROUTER_ID}&router_key={ROUTER_KEY}&prompt=Hello&rule=cost
🚀 Endpoints
1. /chat (GET)
URL
https://api.gofrosty.ai/chat
Method
GET
Query Parameters
Parameter | Type | Description | Required |
|---|---|---|---|
| string | Your Frosty AI Router ID | ✅ |
| string | Your Frosty AI Router Key | ✅ |
| string | The AI prompt you want Frosty to handle | ✅ |
| string | Route based on specific logic: | ✅ |
✨ Routing with rule
Frosty AI lets you manually specify a routing rule to direct traffic to:
-
cost: The most affordable configured model -
performance: The fastest/most optimized configured model -
none: Use your primary model or fallback if configured
Note: Ensure you have your cost or performance models configured in the Frosty AI console for this to work.
✅ Sample Request
GET /chat?router_id=your_router_id&router_key=your_router_key&prompt=Tell me a joke&rule=cost
✅ cURL Example
curl "https://api.gofrosty.ai/chat?router_id=your_router_id&router_key=your_router_key&prompt=Tell me a joke&rule=cost"
📤 Response Example (Success)
{
"trace_id": "abc-1234-5678-xyz",
"total_tokens": 56,
"prompt_type": "chat",
"prompt_tokens": 20,
"response_tokens": 36,
"model": "claude-3-sonnet",
"provider": "Anthropic",
"total_time": 1423,
"prompt": "Tell me a joke",
"cost": "0.01",
"rule": "cost",
"response": "Why don’t skeletons fight each other? They don’t have the guts.",
"success": "True"
}
📤 Response Example (Failure)
{
"trace_id": "abc-1234-5678-xyz",
"total_tokens": 0,
"prompt_type": "chat",
"prompt_tokens": 0,
"response_tokens": 0,
"model": "None",
"provider": "None",
"total_time": 0,
"prompt": "Tell me a joke",
"cost": "- -",
"rule": "cost",
"response": "No fallback provider configured",
"success": "False"
}
❗️ Error Codes & Handling
Status Code | Description | Example Error Message |
|---|---|---|
401 | Unauthorized: Invalid | "Unauthorized. Invalid router_id or router_key." |
403 | Trial expired / Access denied | "Your Frosty AI trial has ended. Subscribe now." |
429 | Rate limit exceeded | "Rate limit exceeded. Please try again." |
502 | No fallback provider configured / Upstream failure | "No fallback provider configured." |
500 | Unknown internal error | "Unexpected error occurred." |
💡 Example Use Cases
-
Smart AI Routing: Automatically choose the best AI model based on cost and performance.
-
Failover: Switch to backup AI models if the primary model fails or is too slow.
-
Multi-model optimization: Select models based on the type of task or user-defined rules.
-
Cost control: Prioritize cheaper models when possible to reduce costs.
-
Performance tuning: Route to fastest models for time-sensitive tasks.
-
Compliance routing: Route sensitive data to specific compliant models/providers.
✅ Status Fields Explained
Field | Description |
|---|---|
| Unique request identifier |
| Total tokens used (input + output) |
| Type of operation (e.g., "chat") |
| Number of tokens in user prompt |
| Number of tokens in AI-generated response |
| AI model used for response |
| AI provider (e.g., OpenAI, Anthropic, Mistral) |
| Time in milliseconds taken for full response |
| The user prompt submitted |
| Estimated cost (if calculated) |
| Routing rule applied (e.g., "cost", "perf") |
| AI-generated response |
| True if operation succeeded, False otherwise |
📬 Contact & Support
For help or questions, reach out to us:
-
Email: support@gofrosty.ai
-
Console: https://console.gofrosty.ai
-
Docs: https://docs.gofrosty.ai