ACE HTTP API

ACE exposes a REST-style HTTP API that mirrors a subset of CLI commands. All operations are asynchronous: requests enqueue a task and return a task ID for polling.

Base URL and authentication

• Base path: /api/v1
• Transport: HTTPS only.
• Mutual TLS is required. The server requires a client certificate signed by cert_auth.ca_cert_file.
• Optional allowlist: server.allowed_common_names. If set, the client certificate CN must be in this list.
• Optional revocation: server.client_crl_file is checked and must be valid.
• The client certificate common name (CN) becomes the DB role used by API-initiated tasks that require a role (for example, table-repair uses SET ROLE).

Server-side settings used by the API:

• server.listen_address (default 0.0.0.0)
• server.listen_port (default 5000)
• server.tls_cert_file, server.tls_key_file (required)
• server.client_crl_file (optional)
• server.allowed_common_names (optional)
• server.taskstore_path (optional; defaults to ACE_TASKS_DB or ./ace_tasks.db)

For certificate generation, PostgreSQL SSL setup, and role mapping examples, see Certificate setup.

Common request/response behavior

• All write endpoints are POST and accept application/json.
• Successful submissions return 202 Accepted:

{
  "task_id": "uuid",
  "status": "QUEUED"
}

• Errors return a JSON body:

{
  "error": "message"
}

Typical error codes: 400, 401, 404, 405, 500.

Task status

GET /api/v1/tasks/{task_id}

Returns the current task status. Status values are: PENDING, RUNNING, COMPLETED, FAILED.

{
  "task_id": "uuid",
  "task_type": "TABLE_DIFF",
  "status": "COMPLETED",
  "cluster": "my-cluster",
  "schema": "public",
  "table": "customers",
  "repset": "",
  "started_at": "2025-01-01T10:00:00Z",
  "finished_at": "2025-01-01T10:02:12Z",
  "time_taken": 132.5,
  "task_context": {
    "diff_summary": {
      "...": "..."
    }
  }
}

Notes:

• task_context is task-specific and may include summaries, counts, or error details.
• Diff and report files are written on the server filesystem; the HTTP API does not expose file download endpoints.

Endpoints

POST /api/v1/table-diff

Compares a table between nodes and generates a JSON diff report.

Request body:

Notes:

• API forces output=json; HTML output is not exposed via HTTP.
• --against-origin and --until are not available via HTTP.

Example:

curl --cert client.crt --key client.key --cacert ca.crt \
  https://ace-host:5000/api/v1/table-diff \
  -H 'Content-Type: application/json' \
  -d '{
    "cluster": "my-cluster",
    "table": "public.customers",
    "nodes": ["n2","n3"],
    "table_filter": "region = '\''us-east'\''"
  }'

POST /api/v1/table-rerun

Re-runs a diff from an existing diff file.

Request body:

POST /api/v1/table-repair

Repairs table inconsistencies using a diff file.

Request body:

Notes:

• Recovery-mode is not exposed via HTTP; origin-only diff files will be rejected.
• The client certificate CN must map to a DB role that can run SET ROLE and perform required DML.

POST /api/v1/spock-diff

Diffs Spock metadata across nodes.

Request body:

POST /api/v1/schema-diff

Diffs all tables in a schema or compares schema DDL only.

Request body:

POST /api/v1/repset-diff

Diffs all tables in a replication set.

Request body:

POST /api/v1/mtree/init

Initializes Merkle tree metadata for the cluster.

Request body:

POST /api/v1/mtree/teardown

Removes Merkle tree metadata for the cluster.

Request body: same as /mtree/init.

POST /api/v1/mtree/teardown-table

Removes Merkle tree metadata for a specific table.

Request body:

POST /api/v1/mtree/build

Builds Merkle tree blocks for a table.

Request body:

POST /api/v1/mtree/update

Updates Merkle tree blocks for a table.

Request body:

POST /api/v1/mtree/diff

Diffs Merkle tree blocks for a table.

Request body: