From 6693798ba6c3dc0e3aaec18b1be8d79a64e98f3c Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Wed, 8 Apr 2026 22:03:47 -0500 Subject: [PATCH] docs(cloud): mark /api/history_v2 as deprecated, prefer /api/jobs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add `deprecated: true` on both /api/history_v2 operations in the OpenAPI spec so Mintlify renders a deprecation banner, and point readers at /api/jobs and /api/jobs/{job_id} as replacements. The prompt_id returned by /api/prompt is the same UUID as job_id, so client code can swap the path without any other changes. Update the complete-example snippets (EN + ZH) to fetch outputs via /api/jobs/${prompt_id} instead of /api/history_v2/${prompt_id}. The JobDetailResponse schema already exposes the same `outputs` field the snippets read. No runtime spec changes in the cloud repo — deprecation is docs-only until a Linear ticket is filed for the full removal pass. Co-Authored-By: Claude Opus 4.6 --- openapi-cloud.yaml | 6 ++++++ snippets/cloud/complete-example.mdx | 18 +++++++++--------- snippets/zh/cloud/complete-example.mdx | 18 +++++++++--------- 3 files changed, 24 insertions(+), 18 deletions(-) diff --git a/openapi-cloud.yaml b/openapi-cloud.yaml index 2503ed72d..7dd5e6f39 100644 --- a/openapi-cloud.yaml +++ b/openapi-cloud.yaml @@ -451,7 +451,10 @@ paths: tags: - job summary: Get execution history (v2) + deprecated: true description: | + **Deprecated.** Use [`/api/jobs`](#tag/job/GET/api/jobs) instead. This endpoint is maintained for ComfyUI compatibility but will be removed in a future release; no removal date set. + Retrieve execution history for the authenticated user with pagination support. Returns a lightweight history format with filtered prompt data (workflow removed from extra_pnginfo). operationId: getHistory @@ -494,7 +497,10 @@ paths: tags: - job summary: Get history for specific prompt + deprecated: true description: | + **Deprecated.** Use [`/api/jobs/{job_id}`](#tag/job/GET/api/jobs/{job_id}) instead — the `prompt_id` returned by `/api/prompt` is the same value as `job_id`. This endpoint is maintained for ComfyUI compatibility but will be removed in a future release; no removal date set. + Retrieve detailed execution history for a specific prompt ID. Returns full history data including complete prompt information. operationId: getHistoryForPrompt diff --git a/snippets/cloud/complete-example.mdx b/snippets/cloud/complete-example.mdx index 3d9095d7f..e3ed13651 100644 --- a/snippets/cloud/complete-example.mdx +++ b/snippets/cloud/complete-example.mdx @@ -34,12 +34,12 @@ async function main() { await new Promise((resolve) => setTimeout(resolve, 2000)); } - // 4. Get outputs via history endpoint - const historyRes = await fetch(`${BASE_URL}/api/history_v2/${prompt_id}`, { + // 4. Get outputs via job detail endpoint + const jobRes = await fetch(`${BASE_URL}/api/jobs/${prompt_id}`, { headers: { "X-API-Key": API_KEY }, }); - const history = await historyRes.json(); - const outputs = history.outputs; + const job = await jobRes.json(); + const outputs = job.outputs; // 5. Download output files for (const nodeOutputs of Object.values(outputs)) { @@ -104,13 +104,13 @@ def main(): raise RuntimeError(f"Job {status}") time.sleep(2) - # 4. Get outputs via history endpoint - history_res = requests.get( - f"{BASE_URL}/api/history_v2/{prompt_id}", + # 4. Get outputs via job detail endpoint + job_res = requests.get( + f"{BASE_URL}/api/jobs/{prompt_id}", headers={"X-API-Key": API_KEY} ) - history = history_res.json() - outputs = history["outputs"] + job = job_res.json() + outputs = job["outputs"] # 5. Download output files for node_outputs in outputs.values(): diff --git a/snippets/zh/cloud/complete-example.mdx b/snippets/zh/cloud/complete-example.mdx index 323f7dce4..fcc5039bd 100644 --- a/snippets/zh/cloud/complete-example.mdx +++ b/snippets/zh/cloud/complete-example.mdx @@ -34,12 +34,12 @@ async function main() { await new Promise((resolve) => setTimeout(resolve, 2000)); } - // 4. 通过历史端点获取输出 - const historyRes = await fetch(`${BASE_URL}/api/history_v2/${prompt_id}`, { + // 4. 通过任务详情端点获取输出 + const jobRes = await fetch(`${BASE_URL}/api/jobs/${prompt_id}`, { headers: { "X-API-Key": API_KEY }, }); - const history = await historyRes.json(); - const outputs = history.outputs; + const job = await jobRes.json(); + const outputs = job.outputs; // 5. 下载输出文件 for (const nodeOutputs of Object.values(outputs)) { @@ -104,13 +104,13 @@ def main(): raise RuntimeError(f"任务 {status}") time.sleep(2) - # 4. 通过历史端点获取输出 - history_res = requests.get( - f"{BASE_URL}/api/history_v2/{prompt_id}", + # 4. 通过任务详情端点获取输出 + job_res = requests.get( + f"{BASE_URL}/api/jobs/{prompt_id}", headers={"X-API-Key": API_KEY} ) - history = history_res.json() - outputs = history["outputs"] + job = job_res.json() + outputs = job["outputs"] # 5. 下载输出文件 for node_outputs in outputs.values():