Seata API Documentation

1. API Overview

1.1 namingserver open-api

API	Method	Path	Description	Detail
Health Check	GET	/naming/v1/health	namingserver health check	View
Register Instance	POST	/naming/v1/register /api/v1/naming/register	register a single node	View
Batch Register	POST	/naming/v1/batchRegister /api/v1/naming/batchRegister	register nodes in batch	View
Unregister Instance	POST	/naming/v1/unregister /api/v1/naming/unregister	unregister a single node	View
Cluster Monitor	GET	/naming/v1/clusters /api/v1/naming/clusters	query cluster monitoring view	View
Cluster Data	GET	/naming/v1/clusterData /api/v1/naming/clusterData	query raw data of one cluster	View
Discovery	GET	/naming/v1/discovery /api/v1/naming/discovery	discover clusters by vGroup	View
Add Group	POST	/naming/v1/addGroup /api/v1/naming/addGroup	add vGroup mapping	View
Change Group	POST	/naming/v1/changeGroup /api/v1/naming/changeGroup	switch vGroup mapping	View
Namespace (v1)	GET	/naming/v1/namespace /api/v1/naming/namespace	namespace overview (v1)	View
Watch	POST	/naming/v1/watch /api/v1/naming/watch	long-poll subscribe to vGroup changes	View
Watch List	GET	/naming/v1/watchList /api/v1/naming/watchList	current watch list	View
Namespace (v2)	GET	/naming/v2/namespace /api/v2/naming/namespace	namespace overview (v2)	View

1.2 server admin-api

API	Method	Path	Description	Detail
Delete Branch Session	DELETE	/api/v1/console/branchSession/deleteBranchSession	delete branch session	View
Force Delete Branch Session	DELETE	/api/v1/console/branchSession/forceDeleteBranchSession	force delete branch session	View
Stop Branch Session	PUT	/api/v1/console/branchSession/stopBranchSession	stop branch retries	View
Start Branch Session	PUT	/api/v1/console/branchSession/startBranchSession	start branch retries	View
Query Global Session	GET	/api/v1/console/globalSession/query	page query global sessions	View
Delete Global Session	DELETE	/api/v1/console/globalSession/deleteGlobalSession	delete global session	View
Force Delete Global Session	DELETE	/api/v1/console/globalSession/forceDeleteGlobalSession	force delete global session	View
Stop Global Session	PUT	/api/v1/console/globalSession/stopGlobalSession	stop global retries	View
Start Global Session	PUT	/api/v1/console/globalSession/startGlobalSession	start global retries	View
Send Commit/Rollback	PUT	/api/v1/console/globalSession/sendCommitOrRollback	manually trigger commit or rollback dispatch	View
Change Global Status	PUT	/api/v1/console/globalSession/changeGlobalStatus	change global status	View
Query Global Lock	GET	/api/v1/console/globalLock/query	page query global locks	View
Delete Global Lock	DELETE	/api/v1/console/globalLock/delete	delete global lock	View
Check Global Lock	GET	/api/v1/console/globalLock/check	check whether lock exists for a branch	View

1.3 server open-api

API	Method	Path	Description	Detail
Server Health Check	GET (recommended)	/health	server health check	View
Change Cluster	POST	/metadata/v1/changeCluster	change raft peers	View
Query Cluster Metadata	GET	/metadata/v1/cluster	query leader/term/nodes/storeMode	View
Watch Metadata	POST	/metadata/v1/watch	long-poll subscribe to group changes	View
Add VGroup	GET	/vgroup/v1/addVGroup	add vGroup mapping	View
Remove VGroup	GET	/vgroup/v1/removeVGroup	remove vGroup mapping	View

---

2. namingserver open-api

2.1 Health Check

• Purpose: return namingserver availability status.
• Request: GET /naming/v1/health
• Parameters: none
• Response: Result<?>
• Notes: response body defaults to code="200" and message="success".

2.2 Register Instance

• Purpose: register a single NamingServerNode under namespace + clusterName + unit.
• Request: POST /naming/v1/register or POST /api/v1/naming/register
• Query parameters:

Name	Type	Required	Source	Note
namespace	string	Y	query (@RequestParam)	namespace
clusterName	string	Y	query (@RequestParam)	cluster name
unit	string	Y	query (@RequestParam)	unit name

• Body: NamingServerNode

Field	Type	Required	Note
control	object	N	control endpoint
transaction	object	N	transaction endpoint
internal	object	N	internal endpoint
role	string	N	node role
version	string	N	version
metadata	object	N	extended metadata
weight	number	N	weight
healthy	boolean	N	health status
term	long	N	node term
unit	string	N	node unit

• Response: Result<String>
• Notes: failures are usually represented by code=500, while HTTP status may still be 200.

2.3 Batch Register

• Purpose: register nodes in batch.
• Request: POST /naming/v1/batchRegister or POST /api/v1/naming/batchRegister
• Query parameters: namespace, clusterName (both required, @RequestParam)
• Body: List<NamingServerNode>
• Response: Result<String>

2.4 Unregister Instance

• Purpose: unregister a single node.
• Request: POST /naming/v1/unregister or POST /api/v1/naming/unregister
• Query parameters: namespace, clusterName, unit (all required)
• Body: NamingServerNode
• Response: Result<String>

2.5 Cluster Monitor

• Purpose: query cluster monitoring view under a namespace.
• Request: GET /naming/v1/clusters or GET /api/v1/naming/clusters
• Parameters:

Name	Type	Required	Source	Note
namespace	string	Y (recommended)	query (default binding)	method argument is not explicitly annotated with @RequestParam

• Response: List<ClusterVO> (clusterName, clusterType, vGroupMapping, unitData)

2.6 Cluster Data

• Purpose: query raw data for one cluster.
• Request: GET /naming/v1/clusterData or GET /api/v1/naming/clusterData
• Parameters: namespace, clusterName (both required, @RequestParam)
• Response: SingleResult<ClusterData>
• Notes: when cluster is not found, it returns SingleResult.failure("Cluster not found").

2.7 Discovery

• Purpose: discover cluster list by vGroup + namespace.
• Request: GET /naming/v1/discovery or GET /api/v1/naming/discovery
• Parameters: vGroup, namespace (both required)
• Response: MetaResponse

Field	Type	Note
clusterList	list	matched cluster list
term	long	current vGroup term

2.8 Add Group

• Purpose: create vGroup-to-cluster mapping.
• Request: POST /naming/v1/addGroup or POST /api/v1/naming/addGroup
• Parameters:

Name	Type	Required	Source	Note
namespace	string	Y	query (@RequestParam)	namespace
clusterName	string	Y	query (@RequestParam)	target cluster
unitName	string	N	query (default binding)	no explicit annotation, nullable
vGroup	string	Y	query (@RequestParam)	transaction group

• Response: Result<String>

2.9 Change Group

• Purpose: switch a vGroup to a new cluster.
• Request: POST /naming/v1/changeGroup or POST /api/v1/naming/changeGroup
• Parameters: namespace, clusterName, vGroup (required) + unitName (optional, default "")
• Response: Result<String>

2.10 Namespace (v1)

• Purpose: return aggregated namespace information.
• Request: GET /naming/v1/namespace or GET /api/v1/naming/namespace
• Parameters: none
• Response: SingleResult<Map<String, NamespaceVO>>

NamespaceVO Field	Type
clusters	List<String>
vgroups	List<String>

2.11 Watch

• Purpose: subscribe to specified vGroup changes (long polling).
• Request: POST /naming/v1/watch or POST /api/v1/naming/watch
• Parameters:

Name	Type	Required	Source	Note
clientTerm	string	Y	query (@RequestParam)	must be convertible to long
vGroup	string	Y	query (@RequestParam)	transaction group
timeout	string	Y	query (@RequestParam)	must be convertible to int

• Response: void (asynchronous)
• Key behaviors:
  • Uses request.startAsync() to enable async processing.
  • AsyncContext timeout is set to 0 (container-level infinite timeout).
  • Actual waiting window is controlled by the timeout parameter passed to watcher.

2.12 Watch List

• Purpose: view registered watchers.
• Request: GET /naming/v1/watchList or GET /api/v1/naming/watchList
• Parameters: none
• Response: List<WatcherVO> (vGroup, watcherIp)

2.13 Namespace (v2)

• Purpose: return namespace aggregate information in v2 structure.
• Request: GET /naming/v2/namespace or GET /api/v2/naming/namespace
• Parameters: none
• Response: SingleResult<Map<String, org.apache.seata.namingserver.entity.vo.v2.NamespaceVO>>

v2 NamespaceVO Field	Type
clusters	Map<String, ClusterVO>

v2 ClusterVO Field	Type
vgroups	List<String>
units	List<String>
type	String

---

3. server admin-api

3.1 Delete Branch Session

• Request: DELETE /api/v1/console/branchSession/deleteBranchSession
• Purpose: delete branch session.
• Parameters: xid, branchId (default binding, recommended via query/form)
• Response: SingleResult<Void>

3.2 Force Delete Branch Session

• Request: DELETE /api/v1/console/branchSession/forceDeleteBranchSession
• Purpose: force delete branch session.
• Parameters: xid, branchId
• Response: SingleResult<Void>

3.3 Stop Branch Session

• Request: PUT /api/v1/console/branchSession/stopBranchSession
• Purpose: stop branch retries.
• Parameters: xid, branchId
• Response: SingleResult<Void>

3.4 Start Branch Session

• Request: PUT /api/v1/console/branchSession/startBranchSession
• Purpose: start branch retries.
• Parameters: xid, branchId
• Response: SingleResult<Void>

3.5 Query Global Session

• Request: GET /api/v1/console/globalSession/query
• Purpose: page query global sessions.
• Parameter source: @ModelAttribute GlobalSessionParam (query binding)

Field	Type	Note
pageNum	int	pagination parameter
pageSize	int	pagination parameter
timeStart	long	start of time range
timeEnd	long	end of time range
xid	string	filter condition
applicationId	string	filter condition
status	int	filter condition
transactionName	string	filter condition
vgroup	string	filter condition
withBranch	boolean	include branch details

• Response: PageResult<GlobalSessionVO>

3.6 Delete Global Session

• Request: DELETE /api/v1/console/globalSession/deleteGlobalSession
• Purpose: delete global session.
• Parameters: xid
• Response: SingleResult<Void>

3.7 Force Delete Global Session

• Request: DELETE /api/v1/console/globalSession/forceDeleteGlobalSession
• Purpose: force delete global session.
• Parameters: xid
• Response: SingleResult<Void>

3.8 Stop Global Session

• Request: PUT /api/v1/console/globalSession/stopGlobalSession
• Purpose: stop global retries.
• Parameters: xid
• Response: SingleResult<Void>

3.9 Start Global Session

• Request: PUT /api/v1/console/globalSession/startGlobalSession
• Purpose: start global retries.
• Parameters: xid
• Response: SingleResult<Void>

3.10 Send Commit/Rollback

• Request: PUT /api/v1/console/globalSession/sendCommitOrRollback
• Purpose: manually trigger commit/rollback dispatch.
• Parameters: xid
• Response: SingleResult<Void>

3.11 Change Global Status

• Request: PUT /api/v1/console/globalSession/changeGlobalStatus
• Purpose: change global transaction status.
• Parameters: xid
• Response: SingleResult<Void>

3.12 Query Global Lock

• Request: GET /api/v1/console/globalLock/query
• Purpose: page query global locks.
• Parameter source: @ModelAttribute GlobalLockParam

Field	Type	Note
pageNum	int	pagination parameter
pageSize	int	pagination parameter
timeStart	long	start of time range
timeEnd	long	end of time range
xid	string	filter condition
tableName	string	filter condition
transactionId	string	filter condition
branchId	string	filter condition
pk	string	filter condition
resourceId	string	filter condition

• Response: PageResult<GlobalLockVO>

3.13 Delete Global Lock

• Request: DELETE /api/v1/console/globalLock/delete
• Purpose: delete global lock.
• Parameter source: @ModelAttribute GlobalLockParam
• Response: SingleResult<Void>

3.14 Check Global Lock

• Request: GET /api/v1/console/globalLock/check
• Purpose: check whether a specified branch has a lock.
• Parameters: xid, branchId (default binding)
• Response: SingleResult<Boolean>

---

4. server open-api

4.1 Health Check

• Request: /health (@RequestMapping, recommended to call with GET)
• Purpose: return server startup status.
• Parameters: none
• Response: String, value is ok or not_ok

4.2 Change Cluster

• Request: POST /metadata/v1/changeCluster
• Purpose: change raft peers configuration.
• Parameters:

Name	Type	Required	Source	Note
raftClusterStr	string	Y	query (@RequestParam)	jraft Configuration#parse format

• Response: Result<?>
• Notes: when parsing fails, only message is set, and code may still remain the default 200.

4.3 Query Cluster Metadata

• Request: GET /metadata/v1/cluster
• Purpose: fetch storeMode/term/nodes for a group.
• Parameters:

Name	Type	Required	Source	Note
group	string	N	query (default binding)	if empty, fallback to server.raft.group, default default

• Response: MetadataResponse

Field	Type
storeMode	string
term	long
nodes	List<Node>

4.4 Watch Metadata

• Request: POST /metadata/v1/watch
• Purpose: subscribe to changes by group+term.
• Parameters:

Name	Type	Required	Source	Note
groupTerms	map	Y	body (@RequestBody)	key=group, value=term
timeout	int	N	query (@RequestParam)	default 28000
context	HttpContext	framework-injected	method arg	not user input

• Response: void (asynchronous)
• Notes: term is converted using Long.parseLong(String.valueOf(term)).

4.5 Add VGroup

• Request: GET /vgroup/v1/addVGroup
• Purpose: add vGroup mapping (side effect).
• Parameters: vGroup, unit (@RequestParam)
• Response: Result<?>
• Notes: in non-raft mode, local term is refreshed using System.currentTimeMillis().

4.6 Remove VGroup

• Request: GET /vgroup/v1/removeVGroup
• Purpose: remove vGroup mapping (side effect).
• Parameters: vGroup (@RequestParam)
• Response: Result<?>
• Notes: in non-raft mode, local term is refreshed.

---

5. Common Response Structures

5.1 Result

Field	Type	Note
code	string	default 200
message	string	default success

5.2 SingleResult

Field	Type	Note
code	string	inherits from Result
message	string	inherits from Result
data	any	business payload

5.3 PageResult

Field	Type	Note
code	string	inherits from Result
message	string	inherits from Result
data	list	current page data
total	int	total records
pages	int	total pages
pageNum	int	current page
pageSize	int	page size

---