OpenAI protocol compatibility: chat/completions vs responses

The two endpoints

chat/completions: the de facto standard

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are an assistant" },
    { "role": "user", "content": "Hello" }
  ],
  "stream": true
}

Why it became the standard: it arrived early, the structure is simple, and the ecosystem is wide. Practically any OpenAI SDK code you write will run.

responses: the newer shape

{
  "model": "gpt-4o",
  "input": "Hello"
}

It is designed around a single interaction rather than a conversation history, and its support for tool calls and multi-step tasks is more structured. Newer official tools such as Codex CLI depend on it.

What the incompatibility looks like in practice

your tool needs /v1/responses
        |
the site only implements /v1/chat/completions
        |
404 Not Found

This is why so many people find that everything is configured correctly but nothing works.

How to check which endpoints a site supports

# test chat/completions
curl -s -o /dev/null -w "chat: %{http_code}\n" -X POST https://your-endpoint/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

# test responses
curl -s -o /dev/null -w "responses: %{http_code}\n" -X POST https://your-endpoint/v1/responses \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","input":"hi"}'

A 200 or a 400, where the 400 is a parameter problem, both mean the endpoint exists. A 404 or a 405 means it is not implemented.

Beyond the protocol, other compatibility gaps

Even when the endpoint exists, the depth of the implementation can differ:

This is why it works and it works well are different claims.

One practical suggestion

Test with your real tool, not with curl.

curl can only confirm that an endpoint exists. It cannot confirm the details your actual tool depends on. Run one minimal but real workflow end to end and most compatibility problems will surface at once.

What to do when no site supports responses

1. Change tools -- use an equivalent tool that only depends on chat/completions
2. Build a protocol translation layer -- use a gateway such as LiteLLM
3. Go official -- official endpoints support everything, of course

Option 2 demands more engineering, but it solves the compatibility problem once and for all.

Related reading

• Pointing Codex CLI at a third-party API: what to watch for
• Claude Code with a relay service: full configuration and troubleshooting
• What the /v1/models endpoint is, and why it can verify a relay service