Request & Response

Every interaction with Routeway follows the same request/response cycle. Understanding the shape of these objects makes it easier to integrate the API, handle edge cases, and debug issues.

Request Object

A minimal chat completion request looks like this:

{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "user", "content": "What is 2 + 2?" }
  ]
}

Common Parameters

Parameter	Type	Default	Description
`model`	string	required	Model ID to use (e.g. `"gpt-4o"`, `"claude-opus-4-5"`)
`messages`	array	required	Ordered list of conversation turns
`max_tokens`	integer	model default	Maximum output tokens to generate
`temperature`	number	`1.0`	Sampling temperature (`0` = deterministic, `2` = very random)
`top_p`	number	`1.0`	Nucleus sampling threshold
`stream`	boolean	`false`	Stream tokens as SSE chunks
`tools`	array	—	Function schemas the model may call
`tool_choice`	string / object	`"auto"`	How the model selects tools
`response_format`	object	—	Force `json_object` or `json_schema` output
`reasoning_effort`	string	—	`"low"` / `"medium"` / `"high"` for OpenAI reasoning models

temperature and top_p both control randomness. Use one or the other — not both. For deterministic tasks like data extraction, set temperature: 0. For creative tasks, try values between 0.7 and 1.2.

Full Request Example

Python
Node.js
cURL

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.routeway.ai/v1",
    api_key=os.getenv("ROUTEWAY_API_KEY")
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Name the planets in our solar system."}
    ],
    max_tokens=150,
    temperature=0.3,
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.routeway.ai/v1",
  apiKey: process.env.ROUTEWAY_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Name the planets in our solar system." },
  ],
  max_tokens: 150,
  temperature: 0.3,
});

console.log(response.choices[0].message.content);

curl https://api.routeway.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Name the planets in our solar system."}
    ],
    "max_tokens": 150,
    "temperature": 0.3
  }'

Response Object

A successful response looks like this:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1749052800,
  "model": "gpt-4o-2024-11-20",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The eight planets are Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 22,
    "total_tokens": 50
  }
}

Key Fields

Field	Description
`id`	Unique identifier for this completion
`model`	The exact model snapshot that was used
`choices`	Array of generated responses (usually one)
`choices[0].message.content`	The model’s text reply
`choices[0].finish_reason`	Why the model stopped generating
`usage`	Token counts for billing

`finish_reason` Values

Value	Meaning
`"stop"`	Model finished naturally
`"length"`	Hit `max_tokens` limit — response may be truncated
`"tool_calls"`	Model wants to call a function
`"content_filter"`	Response blocked by a content policy
`"null"`	Stream is still in progress (streaming only)

Always check finish_reason. A value of "length" means the response was cut off. Handle it by either increasing max_tokens or detecting and requesting a continuation.

Accessing the Response Text

The model’s reply lives at choices[0].message.content:

text = response.choices[0].message.content

When n > 1, multiple completions are returned and you index into choices[0], choices[1], etc. When the model calls a tool instead of replying with text, content may be null and tool_calls will be populated:

message = response.choices[0].message

if message.tool_calls:
    # model wants to call a function
    for tc in message.tool_calls:
        print(tc.function.name, tc.function.arguments)
else:
    # normal text response
    print(message.content)

Error Responses

When something goes wrong, Routeway returns a standard error object:

{
  "error": {
    "message": "Invalid model: 'gpt-999'.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

HTTP status	Type	Common causes
`400`	`invalid_request_error`	Bad parameters, context too long, invalid model ID
`401`	`authentication_error`	Missing or invalid API key
`429`	`rate_limit_error`	Too many requests or insufficient balance
`500`	`server_error`	Upstream provider error

See the Errors page for the full list and handling guidance.

HTTP Headers

Every request must include:

Authorization: Bearer YOUR_ROUTEWAY_API_KEY
Content-Type: application/json

The response includes a x-request-id header you can use when contacting support about a specific call.

Get Started

Platform Details

Help & Resources

Core Concepts

Account Management

Guides

Request Object

Common Parameters

Full Request Example

Response Object

Key Fields

`finish_reason` Values

Accessing the Response Text

Error Responses

HTTP Headers

​Request Object

​Common Parameters

​Full Request Example

​Response Object

​Key Fields

​finish_reason Values

​Accessing the Response Text

​Error Responses

​HTTP Headers

Request Object

Common Parameters

Full Request Example

Response Object

Key Fields

`finish_reason` Values

Accessing the Response Text

Error Responses

HTTP Headers