---
name: check-api-compat
description: Determine the correct behavior of vLLM's OpenAI-compatible or Anthropic-compatible API by checking the official upstream spec, instead of guessing from vLLM's own code. Use for any bug, issue, PR, review, or question touching /v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings, /v1/messages, or their request/response models — including "is this a bug or intended", "what should this field default to", "does upstream allow this", and any change that adds, removes, or renames a field on those models. Do not use for vLLM-internal APIs (engine, scheduler, LLM class) or for endpoints with no upstream counterpart.
title: check-api-compat
canonical_url: https://skilld.dev/gh/vllm-project/vllm/check-api-compat
last_updated: 2026-10-10T14:31:13.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/vllm-project/vllm/check-api-compat/agents/openai.yaml).
>
> If the user asked to install this Skill, run `npx skilld install vllm-project/vllm/check-api-compat`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/check-api-compat`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/vllm-project/vllm/check-api-compat) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/check-api-compat`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/check-api-compat --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/check-api-compat --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Checking vLLM API compatibility against the upstream spec

vLLM's OpenAI and Anthropic server surfaces are *reimplementations* of someone
else's spec. vLLM's own code, tests, and docstrings are not evidence of correct
behavior — they are the thing under test. Establish what upstream says first,
then compare.

Never answer "what should this field do" from memory. Field names, types, and
especially defaults drift between spec versions.

## 1. Pin down the question

Name three things before looking anything up:

- **Which surface** — OpenAI-compatible or Anthropic-compatible. They are separate
  code paths in vLLM and separate specs.
- **Which endpoint**, by path.
- **Which field or behavior** — a request field, a response field, a streaming
  event shape, an error code, or a status code.

## 2. Read vLLM's implementation

In a vLLM checkout, the request/response models live beside each endpoint:

| surface | path |
| --- | --- |
| OpenAI chat | `vllm/entrypoints/openai/chat_completion/` |
| OpenAI completions | `vllm/entrypoints/openai/completion/` |
| OpenAI responses | `vllm/entrypoints/openai/responses/` |
| OpenAI embeddings | `vllm/entrypoints/pooling/embed/` |
| OpenAI shared base models, errors, usage | `vllm/entrypoints/serve/engine/protocol.py` |
| Anthropic messages | `vllm/entrypoints/anthropic/` |
| audio | `vllm/entrypoints/speech_to_text/*/protocol.py` |

Each directory holds `protocol.py` (the Pydantic models), `serving.py` (behavior),
and `api_router.py` (routing and status codes). Read the field declaration *and*
the code that consumes it — a field can be declared faithfully and then ignored,
which is still an incompatibility.

## 3. Fetch the upstream spec

Prefer a source that can actually be read as text, in this order.

### OpenAI

1. The OpenAPI spec — authoritative, machine-readable, and fetches cleanly:
   `https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml`
2. The installed `openai` Python SDK's typed params, which track the spec closely.
   Locate them with `python -c "import openai,os;print(os.path.dirname(openai.__file__))"`,
   then read e.g. `types/chat/completion_create_params.py`,
   `types/chat/chat_completion.py`, `types/chat/chat_completion_chunk.py`,
   `types/responses/`. Note the SDK version — an old SDK is an old spec.
3. The prose reference at `https://platform.openai.com/docs/api-reference/...`
   for semantics the types do not carry. It is script-heavy and often fetches
   poorly; treat a failed fetch as a fetch failure, not as absence of a field.

### Anthropic

1. `https://docs.claude.com/en/api/messages` and
   `https://docs.claude.com/en/api/messages-streaming` — these render as clean
   text and are the primary source for both fields and streaming event order.
2. The installed `anthropic` SDK's `types/message_create_params.py`,
   `types/message.py`, `types/raw_message_stream_event.py`.

Say which source and which version answered the question, so the finding can be
re-checked later.

## 4. Compare on all four axes

A field is compatible only when **name**, **type**, **default**, and **semantics**
all match. Most real bugs hide in the last two: a field that exists with the right
type but the wrong default, or one that is accepted and silently dropped.

Also check, when relevant:

- **Streaming** — chunk shape, the order of events, and the terminal event
  (`data: [DONE]` for Chat Completions and Completions; `response.completed`,
  `response.failed`, or `response.incomplete` with no `[DONE]` for Responses;
  `message_stop` for Anthropic).
- **Errors** — HTTP status *and* the error body's `type`/`code` strings.
- **Omitted vs null** — upstream often distinguishes an absent field from an
  explicit `null`. Pydantic defaults erase that distinction unless the model is
  written to preserve it.

## 5. Classify before calling it a bug

Three outcomes, and they are not the same:

- **Matches upstream** — no action.
- **vLLM extension** — a field upstream has no name for at all (`vllm_xargs`,
  `chat_template_kwargs`, sampling knobs like `min_p`). These are intentional and
  allowed. Do not report them as violations. Check per surface: `top_k` is an
  extension on OpenAI but a real upstream field on Anthropic Messages.
- **Incompatibility** — a field that *shares a name with upstream* but differs in
  type, default, or behavior, or an upstream field that is missing, ignored, or
  malformed. This is the reportable case.

An unsupported-but-declared field is its own subcase: decide whether vLLM rejects
it explicitly or accepts and ignores it, and report which, since silently ignoring
a documented field is the more damaging failure.

## 6. Report

State: the endpoint and field, what upstream specifies (with the source), what
vLLM does (with `file:line`), which of the three outcomes it is, and the smallest
fix. When behavior turns on a spec detail that is easy to disbelieve, quote the
upstream line rather than paraphrasing it.
