OpenAI-compatible API · endpoint choice

Responses API vs Chat Completions: choose the right endpoint

OpenAI recommends the Responses API for new projects, but Chat Completions remains supported. That does not make the two endpoints interchangeable. The request fields, output shape, tool calls and state handling differ, and a compatible gateway may support them unevenly.

The short answer

Question	Chat Completions	Responses
Endpoint	`POST /v1/chat/completions`	`POST /v1/responses`
Main input	`messages`	`input`, plus `instructions` when needed
Text output	`choices[0].message.content`	Typed `output` items; SDK helper `output_text`
Conversation state	Your application usually resends prior messages	`previous_response_id`, prior output items, or Conversations API
OpenAI guidance	Still supported	Recommended for new projects

For MonkeyAI, unauthenticated production checks returned structured 401 API_KEY_REQUIRED from both routes on 2026-08-03. This confirms route and auth-middleware reachability only. It is not an authenticated model or feature test.

Verify the route before changing application code

Fetch the model list with your real key first. Then send one minimal request to each endpoint with a model visible to that key.

curl -sS https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer $MONKEYAI_API_KEY"

# Chat Completions request template
curl -sS https://monkeytheme.com/v1/chat/completions \
  -H "Authorization: Bearer $MONKEYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"Reply with OK"}],"max_completion_tokens":16}'

# Responses request template
curl -sS https://monkeytheme.com/v1/responses \
  -H "Authorization: Bearer $MONKEYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","input":"Reply with OK","max_output_tokens":16,"store":false}'

The authenticated request templates above were not run with a customer key during this review. Model availability and optional fields can differ by account and upstream. Use a model returned by your own /v1/models call.

Migration changes that break real clients

Input field

Chat Completions accepts messages. Responses uses input, which may be a string or a list of input items. A blind path replacement leaves the old request body behind.

Output parser

Code that reads choices[0].message.content will not parse a Responses object. Read typed output items or use the official SDK's output_text helper.

State

previous_response_id can chain turns, but it does not carry the previous top-level instructions. Resend stable instructions on every request.

Tools

Function configuration and returned calls use different shapes. Built-in tools documented by OpenAI are not proof that every compatible gateway or model implements them.

Structured output

OpenAI documents response_format for Chat Completions and text.format for Responses. Treat this as a code migration, not a URL edit.

Storage

OpenAI's migration guide says responses are stored by default. Set store: false when your data policy requires it, then verify gateway behavior.

A practical decision rule

Keep Chat Completions when an existing client only implements that response shape and it already works.
Prefer Responses for a new OpenAI integration when its models and required features pass authenticated tests.
Do not infer tool, streaming, state or background support from a 401 or a successful model-list request.
During migration, compare status, first-byte time, final text, tool events and usage fields on the same small prompt.
Retain a tested rollback path until production traffic is stable.

Failure map

Symptom	Likely layer	Next check
401 JSON	Authentication	Bearer header, key and hostname
404 on one route	Gateway routing or unsupported endpoint	Exact Base URL and endpoint support
400 unknown field	Request body still uses the other API shape	`messages` vs `input`; output and tool fields
200 but parser fails	Client expects `choices` instead of `output`	Log a redacted top-level response shape
Model not found	Model visibility or route mapping	Use the exact ID returned by `/v1/models`

FAQ

Should a new project use Responses or Chat Completions?

OpenAI recommends Responses for new projects, while Chat Completions remains supported. On a compatible gateway, confirm that the selected model and every required feature work on the chosen route before migrating.

Can I change only the endpoint path?

Not safely. The request field changes from messages to input, and the response changes from choices to typed output items. Tool calling, structured output and conversation state also use different shapes.

Does a 401 from both routes prove full compatibility?

No. It proves that both paths reach the gateway authentication layer. It does not prove that your key, model, tools, streaming or state features work after authentication.

Can I reuse choices[0].message.content with Responses?

No. Responses returns typed output items. The official SDK also exposes an output_text helper for aggregated text.

Does previous_response_id carry my instructions forward?

OpenAI says top-level instructions are not carried over by previous_response_id. Send stable instructions again on each request.

Does MonkeyAI support every Responses API feature?

This page does not claim that. Route-level checks confirm that /v1/responses exists, but each model and feature still needs an authenticated test.

Sources and related guides

OpenAI: Migrate to the Responses API — endpoint, input/output, storage and state differences.
OpenAI Python SDK with a custom Base URL
API key, 401, 404 and model-not-found troubleshooting
API 504 upstream timeout troubleshooting