Percona ClusterSync for MongoDB HTTP API documentation

Quick start guide

To get started with Percona ClusterSync for MongoDB API:

1. Ensure the service is running on http://localhost:2242
2. Use the /start endpoint to begin replication
3. Monitor progress using the /status endpoint
4. Use /pause and /resume to control the replication process
5. Call /finalize when replication is complete

Authentication

Currently, the API does not require authentication. However, it’s recommended to run the service behind a reverse proxy with proper authentication in production environments.

API endpoints

POST /start

Starts the replication process.

Request

Parameter	Type	Required	Description
includeNamespaces	string[]	No	List of namespaces to include in replication (for example, [“db.*”, “db.collection”])
excludeNamespaces	string[]	No	List of namespaces to exclude from replication
replNumWorkers	int	No	Controls how many concurrent replication worker goroutines PCSM uses to apply DML (insert/update/replace/delete) events to the target cluster.
replChangeStreamBatchSize	int	No	Sets the maximum number of change stream events PCSM will request and read from MongoDB per batch while streaming changes from the source cluster.
replEventQueueSize	int	No	Controls the size of the internal event queue used by the replication subsystem.
replWorkerQueueSize	int	No	Defines the maximum number of replication events that each replication worker thread can queue before processing.
replBulkOpsSize	int	No	Defines the maximum number of operations that can be grouped together into a single bulk apply batch during replication.
cloneSegmentSize	string	No	Defines the byte size of each clone segment processed during the initial clone phase. Specify either a plain integer number of bytes (for example, 1048576) or a human-readable size string accepted by the server, for example 500MB or 1GiB.

Examples:

curl -X POST http://localhost:2242/start -d '{
    "includeNamespaces": ["dbName.*", "anotherDB.collName1", "anotherDB.collName2"],
    "excludeNamespaces": ["dbName.collName"],
    "replWorkerFlushInterval": "1s",
    "replWorkerBulkQueueSize": 3
}'

curl -X POST "http://localhost:2242/start" \
  -H "Content-Type: application/json" \
  --data '{
    "replChangeStreamBatchSize": 10000,
    "replEventQueueSize": 5000,
    "replWorkerQueueSize": 5000,
    "replBulkOpsSize": 5000
  }'

Response

• ok: Boolean indicating if the operation was successful.
• error (optional): Error message if the operation failed.

Example:

{ "ok": true }

POST /finalize

Finalizes the replication process.

Request

Example:

curl -X POST http://localhost:2242/finalize

Response

• ok: Boolean indicating if the operation was successful.
• error (optional): Error message if the operation failed.

Example:

{ "ok": true }

POST /pause

Pauses the replication process.

Request

Example:

curl -X POST http://localhost:2242/pause

Response

• ok: Boolean indicating if the operation was successful.
• error (optional): Error message if the operation failed.

Example:

{ "ok": true }

POST /resume

Resumes the replication process.

Request

Example:

curl -X POST http://localhost:2242/resume

Resume from failure:

curl -X POST http://localhost:2242/resume -d '{
  "fromFailure": true
}'

Response

• ok: Boolean indicating if the operation was successful.
• error (optional): Error message if the operation failed.

Example:

{ "ok": true }

GET /status

The /status endpoint provides the current state of the Percona ClusterSync for MongoDB replication process, including its progress, lag, and event processing details.

Request

Example:

curl -X GET http://localhost:2242/status

Response

The following are response fields:

Field	Type	Description
ok	boolean	Operation success status
state	string	Current replication state
info	string	Additional information about the current state
error	string	(optional): The error message if the operation failed.
lagTimeSeconds	number	Current lag time in logical seconds between source and target clusters.
eventsRead	number	Total number of events read from the source
eventsApplied	number	Total number of events applied to the target
lastReplicatedOpTime.ts	string	The timestamp of the last replicated operation time.
lastReplicatedOpTime.isoDate	date.Time	The human-readable representation of the last replicated operation time.
initialSync.completed	boolean	Initial sync completion status
initialSync.lagTime	number	The lag time in logical seconds until the initial sync completed
initialSync.cloneCompleted	boolean	Clone process completion status
initialSync.estimatedCloneSizeBytes	number	Estimated total size to clone (bytes)
initialSync.clonedSizeBytes	number	Current cloned size (bytes)
finalization.completed	boolean	Finalization completion status
finalization.startedAt	string	RFC3339 timestamp when finalization started (omitted when status restored from a recovered checkpoint)
finalization.completedAt	string	RFC3339 timestamp when finalization completed (omitted while finalization in progress)
finalization.unsuccessfulIndexes	array	List of indexes that were not finalized successfully (omitted when empty)
finalization.unsuccessfulIndexes[].namespace	string	MongoDB namespace in database.collection format
finalization.unsuccessfulIndexes[].indexName	string	Index name
finalization.unsuccessfulIndexes[].keys	object	Index key specification
finalization.unsuccessfulIndexes[].type	string	Machine-readable failure category (failed, incomplete, inconsistent)
finalization.unsuccessfulIndexes[].reason	string	Human-readable reason why finalization failed for this index

Example:

{
  "ok": true,
  "state": "finalized",
  "info": "Finalized",
  "lagTimeSeconds": 0,
  "eventsRead": 0,
  "eventsApplied": 0,
  "lastReplicatedOpTime": {
    "ts": "1779199363.1",
    "isoDate": "2026-05-19T14:02:43Z"
  },
  "initialSync": {
    "estimatedCloneSizeBytes": 328116,
    "clonedSizeBytes": 328116,
    "completed": true,
    "cloneCompleted": true
  },
  "finalization": {
    "completed": true,
    "startedAt": "2026-05-07T10:30:00Z",
    "completedAt": "2026-05-07T10:30:42Z",
    "unsuccessfulIndexes": [
      {
        "namespace": "mydb.users",
        "indexName": "email_unique_idx",
        "type": "failed",
        "reason": "recreate index mydb.users.email_unique_idx: duplicate key error",
        "keys": {
          "email": 1
        }
      }
    ]
  }
}

Error handling

The API uses standard HTTP status codes and returns error messages in the following format:

{
    "ok": false,
    "error": "Detailed error message"
}

Common error scenarios:

• 400 Bad Request: Invalid request parameters
• 404 Not Found: Endpoint not found
• 500 Internal Server Error: Server-side issues

---

Last update: June 6, 2026
Created: June 6, 2026