This is an automated email from the ASF dual-hosted git repository.
davidzollo pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new 42417036da [Docs][Zeta] Clarify REST API v2 is Zeta-only and document
pause/resume/delete (#11680)
42417036da is described below
commit 42417036da0aa36c2053866b6e02e35e005356c0
Author: Daniel <[email protected]>
AuthorDate: Fri Aug 7 14:14:22 2026 +0800
[Docs][Zeta] Clarify REST API v2 is Zeta-only and document
pause/resume/delete (#11680)
Co-authored-by: danielnadean
<[email protected]>
Co-authored-by: Claude Sonnet 5 <[email protected]>
---
docs/en/engines/overview.md | 6 +++++-
docs/en/engines/zeta/rest-api-v2.md | 21 +++++++++++++++++++++
docs/zh/engines/overview.md | 6 +++++-
docs/zh/engines/zeta/rest-api-v2.md | 19 +++++++++++++++++++
4 files changed, 50 insertions(+), 2 deletions(-)
diff --git a/docs/en/engines/overview.md b/docs/en/engines/overview.md
index 04f91f5c4f..83e995e061 100644
--- a/docs/en/engines/overview.md
+++ b/docs/en/engines/overview.md
@@ -42,11 +42,15 @@ For most new deployments, SeaTunnel Engine is the
recommended default because it
| **Exactly-Once** | ✅ | ✅ | ✅ |
| **Multi-Table Sync** | ✅ | ✅ | ✅ |
| **Schema Evolution** | ✅ | ✅ | ❌ |
-| **REST API** | ✅ | ✅ | ❌ |
+| **REST API** | ✅ | ❌ | ❌ |
| **Web UI** | ✅ | ✅ | ✅ |
| **Standalone Mode** | ✅ | ✅ | ✅ |
| **Cluster Mode** | ✅ | ✅ | ✅ |
+:::note
+"REST API" here refers to SeaTunnel's own job submission/monitoring API ([REST
API V2](zeta/rest-api-v2.md)). It is implemented by the SeaTunnel Engine (Zeta)
server only, so it is not available when a job runs on the Flink or Spark
engine. When using the Flink or Spark engine, submit and monitor jobs through
that engine's own tooling instead (e.g. Flink's CLI/REST API, Spark's
`spark-submit`/history server).
+:::
+
### Performance Comparison
| Metric | SeaTunnel Engine | Flink | Spark |
diff --git a/docs/en/engines/zeta/rest-api-v2.md
b/docs/en/engines/zeta/rest-api-v2.md
index 7afe0fc853..c0caceaf52 100644
--- a/docs/en/engines/zeta/rest-api-v2.md
+++ b/docs/en/engines/zeta/rest-api-v2.md
@@ -3,6 +3,12 @@
SeaTunnel has a monitoring API that can be used to query status and statistics
of running jobs, as well as recent
completed jobs. The monitoring API is a RESTful API that accepts HTTP requests
and responds with JSON data.
+:::tip
+This API is provided by the SeaTunnel Engine (Zeta) server, so it is only
available for jobs running on the Zeta
+engine. It is not available when a job runs on the Flink or Spark engine; use
that engine's own tooling to submit
+and monitor jobs in that case.
+:::
+
## Overview
The v2 API and the Web UI are both served by the embedded Jetty server. Jetty
starts only when
@@ -1588,3 +1594,18 @@ Ratio fields are in the range `0~1` and can be displayed
as percentages. Fields
```
</details>
+
+------------------------------------------------------------------------------------------
+
+### Pause, Resume Or Delete A Job
+
+There is no dedicated `pause`, `resume` or `delete` endpoint. Use the existing
job endpoints as follows:
+
+| Goal | How
|
+|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Pause a running job (stop now, resume later) | Call
[`/stop-job`](#stop-a-job) with `isStopWithSavePoint: true`. The job stops and
a savepoint of its current state is persisted.
|
+| Resume a paused job | Call
[`/submit-job`](#submit-a-job) again with `isStartWithSavePoint: true`, the
**same** `jobId` that was stopped, and the same job config. The job restores
from its latest savepoint for that `jobId`. |
+| Delete a job | There is no delete endpoint. Stop
the job with [`/stop-job`](#stop-a-job) if it is still running. Once a job
reaches a finished state, its record is removed automatically after
`history-job-expire-minutes` (default 1440 minutes) elapses -- see [History Job
Expiry
Configuration](separated-cluster-deployment.md#44-history-job-expiry-configuration).
|
+
+**Note:** `isStartWithSavePoint: true` requires `jobId` to be provided in the
request; submitting
+without a `jobId` in that case fails with `Please provide jobId when start
with save point.`
diff --git a/docs/zh/engines/overview.md b/docs/zh/engines/overview.md
index 63e59cd98b..472f520208 100644
--- a/docs/zh/engines/overview.md
+++ b/docs/zh/engines/overview.md
@@ -42,11 +42,15 @@ SeaTunnel 支持多种执行引擎，您可以根据实际场景选择最合适
| **精确一次** | ✅ | ✅ | ✅ |
| **多表同步** | ✅ | ✅ | ✅ |
| **Schema 演变** | ✅ | ✅ | ❌ |
-| **REST API** | ✅ | ✅ | ❌ |
+| **REST API** | ✅ | ❌ | ❌ |
| **Web UI** | ✅ | ✅ | ✅ |
| **单机模式** | ✅ | ✅ | ✅ |
| **集群模式** | ✅ | ✅ | ✅ |
+:::note
+此处的"REST API"指 SeaTunnel 自身的作业提交/监控接口（[REST API
V2](zeta/rest-api-v2.md)）。该接口仅由 SeaTunnel Engine（Zeta）的 server 实现，因此作业运行在 Flink
或 Spark 引擎上时不可用。使用 Flink 或 Spark 引擎时，请通过该引擎自身的工具提交和监控作业（例如 Flink 的 CLI/REST
API、Spark 的 `spark-submit`/history server）。
+:::
+
### 性能对比
| 指标 | SeaTunnel Engine | Flink | Spark |
diff --git a/docs/zh/engines/zeta/rest-api-v2.md
b/docs/zh/engines/zeta/rest-api-v2.md
index 9b9676de35..24c9e6a0aa 100644
--- a/docs/zh/engines/zeta/rest-api-v2.md
+++ b/docs/zh/engines/zeta/rest-api-v2.md
@@ -2,6 +2,10 @@
SeaTunnel有一个用于监控的API，可用于查询运行作业的状态和统计信息，以及最近完成的作业。监控API是RESTful风格的，它接受HTTP请求并使用JSON数据格式进行响应。
+:::tip
+该 API 由 SeaTunnel Engine（Zeta）的 server 提供，因此只在作业运行于 Zeta 引擎时可用；作业运行在 Flink 或
Spark 引擎上时不可用，此时请使用对应引擎自身的工具提交和监控作业。
+:::
+
## 概述
v2 版本的 API 和 Web UI 都由内嵌 Jetty 提供，与 v1 版本保持相同的接口规范。只有当
@@ -1571,3 +1575,18 @@ Checkpoint 信息字段：
```
</details>
+
+------------------------------------------------------------------------------------------
+
+### 暂停、恢复或删除作业
+
+目前没有专门的 `pause`（暂停）、`resume`（恢复）或 `delete`（删除）接口，可以通过已有的作业接口达到同样的效果：
+
+| 目标 | 方法
|
+|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 暂停一个正在运行的作业（先停止，之后再恢复） | 调用 [`/stop-job`](#停止作业)，并设置 `isStopWithSavePoint:
true`。作业会停止运行，同时会保存一个当前状态的 savepoint。
|
+| 恢复一个已暂停的作业 | 再次调用 [`/submit-job`](#提交作业)，设置
`isStartWithSavePoint: true`，并传入与之前停止时**相同**的 `jobId` 和相同的作业配置。作业会基于该 `jobId`
最近一次的 savepoint 恢复。 |
+| 删除一个作业 | 没有专门的删除接口。如果作业仍在运行，先通过 [`/stop-job`](#停止作业)
停止它；作业进入结束状态后，其记录会在 `history-job-expire-minutes`（默认 1440
分钟）到期后自动清理，参见[历史作业过期配置](separated-cluster-deployment.md#44-历史作业过期配置)。 |
+
+**注意：** 当 `isStartWithSavePoint: true` 时必须提供 `jobId`；不提供 `jobId` 会导致请求失败，报错信息为
+`Please provide jobId when start with save point.`
