From 73829e63863b7919604e6cf35cf070972f4e168f Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Tue, 14 Apr 2026 10:56:21 -0700
Subject: [PATCH] Mark /api/history endpoints as deprecated

Address Jacob's review feedback on PR #13397 by explicitly marking the
three /api/history operations as deprecated in the OpenAPI spec:

  * GET  /api/history              -> superseded by GET /api/jobs
  * POST /api/history              -> superseded by /api/jobs management
  * GET  /api/history/{prompt_id}  -> superseded by GET /api/jobs/{job_id}

Each operation gains deprecated: true plus a description that names the
replacement. A formal sunset timeline (RFC 8594 Deprecation and RFC 8553
Sunset headers, minimum-runway policy) is being defined separately and
will be applied as a follow-up.
---
 openapi.yaml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/openapi.yaml b/openapi.yaml
index 9dab3075f..d4f38eeed 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -336,7 +336,12 @@ paths:
       operationId: getHistory
       tags: [history]
       summary: Get execution history
+      deprecated: true
       description: |
+        **Deprecated.** Superseded by `GET /api/jobs`, which returns the same
+        execution records in a paginated, filterable format. Planned for removal
+        no earlier than a future major release; sunset timeline TBD.
+
         Returns a dictionary keyed by prompt_id. Each value is a HistoryEntry
         containing prompt metadata, outputs, status, and node meta.
       parameters:
@@ -364,6 +369,11 @@ paths:
       operationId: manageHistory
       tags: [history]
       summary: Clear or delete history entries
+      deprecated: true
+      description: |
+        **Deprecated.** Superseded by the forthcoming job-management endpoints
+        under `/api/jobs`. Planned for removal no earlier than a future major
+        release; sunset timeline TBD.
       parameters:
         - $ref: "#/components/parameters/ComfyUserHeader"
       requestBody:
@@ -381,6 +391,11 @@ paths:
       operationId: getHistoryByPromptId
       tags: [history]
       summary: Get history for a specific prompt
+      deprecated: true
+      description: |
+        **Deprecated.** Superseded by `GET /api/jobs/{job_id}`, which returns
+        the same execution record. Planned for removal no earlier than a future
+        major release; sunset timeline TBD.
       parameters:
         - $ref: "#/components/parameters/ComfyUserHeader"
         - name: prompt_id