Add OpenAPI 3.1 specification for ComfyUI API

[MillerMedia]

Summary

• Adds a comprehensive OpenAPI 3.1 specification (openapi.yaml) documenting all HTTP endpoints exposed by ComfyUI's server
• Covers prompt execution, queue management, file uploads, userdata, settings, system stats, object info, assets, model management, and internal routes
• Includes WebSocket message schemas via x-websocket-messages extension
• Documents dual-path routing (bare paths and /api/ prefix)
• Removes openapi.yaml from .gitignore so the spec is tracked in version control

Details

The spec was:

• Written against the current source code (server.py, app/, api_server/)
• Cross-reviewed against the actual route handlers to catch drift
• 17 critical/high corrections applied based on code review (e.g., fixing fabricated response fields, correcting query parameter names, adding missing schema properties)
• Passes Spectral OpenAPI linting with 0 errors and 62 warnings (all cosmetic — missing operation descriptions, etc.)

Endpoints covered

Category	Endpoints
Prompt & Queue	/api/prompt, /api/queue
History	/api/history, /api/history/{prompt_id}
File Operations	/api/view, /api/upload/image, /api/upload/mask
System	/api/system_stats, /api/interrupt, /api/free
Node Info	/api/object_info, /api/object_info/{node_class}
User Data	/api/userdata/*, /api/settings, /api/users
Assets	/api/assets/*
Models	/api/experiment/models/*
Jobs	/api/jobs, /api/jobs/{job_id}
Templates	/api/workflow_templates
Embeddings	/api/embeddings
Extensions	/api/extensions
Internal	/internal/*

Test plan

• Validate spec with npx @stoplight/spectral-cli lint openapi.yaml
• Verify generated client code matches actual server behavior
• Spot-check 3-5 endpoints against running ComfyUI instance

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request modifies the .gitignore file to remove openapi.yaml from the list of ignored files. This change means that openapi.yaml will now be tracked by version control, whereas previously it was excluded. The filtered-openapi.yaml file remains in the ignore list. This is a minimal change affecting only one line in the configuration file.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding an OpenAPI 3.1 specification for the ComfyUI API, which matches the PR's primary objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The description comprehensively describes the OpenAPI specification being added and the .gitignore change, directly aligning with the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[guill]

Since we're trying to deprecate this endpoint (in favor of /jobs), do we want to exclude it from the OpenAPI spec?

[MillerMedia]

Added deprecated:true and description on this one.

[guill]

Same comment as above -- should we include deprecated endpoints?

[MillerMedia]

Added deprecated:true and description on this one.

[guill]

Looks good to me other than either removing or documenting in some way that some endpoints (e.g. /api/history) are deprecated.

[MillerMedia]

Looks good to me other than either removing or documenting in some way that some endpoints (e.g. /api/history) are deprecated.

I've added deprecated to the two endpoints called out. Any other endpoints planned for deprecation?

[MillerMedia]

@guill heads up — ran Spectral against this spec (using our cloud ruleset as a baseline) and pushed a commit (3fcbaee) with the cosmetic fixes it surfaced:

• Added descriptions to 52 operations, 22 schemas, and 8 path params
• Removed 6 unused component schemas (TaskOutput, EmbeddingsResponse, ExtensionsResponse, LogRawResponse, UserInfo, UserDataFullInfo)

No wire/shape changes. Findings went from 92 → 4. The remaining 4 are real issues I didn't want to bundle in a cosmetic sweep:

1. /ws only declares a 101 response (legitimate for WebSocket upgrade, but Spectral wants 2xx/3xx)
2. PromptErrorResponse uses additionalProperties: true — loose but matches the real server shape
3. ModelFile.pathIndex — snake_case warning, but it's the actual wire field emitted by app/model_manager.py
4. ProgressTextWsMessage.nodeId — schema says JSON, but the server actually emits binary here; looks like a deeper protocol bug rather than a naming nit

Happy to follow up on any of those separately.

[jtreminio]

You should really avoid using oneOf without a discriminator. When someone takes this spec and generates an SDK using openapi-generator, the code won't work as expected.

[Kosinkadink]

From my view, this PR and #13410 can go in at any time. As long as everyone's good to go.