HTTP API

REST API reference for programmatic pipeline and connection management in Nanosync.

The Nanosync server exposes a REST API on :7600 (default). All endpoints are under the /v1/ prefix.

Base URL: http://localhost:7600

---

Pipeline management

List pipelines

GET /v1/pipelines

Response:

[
  {
    "name": "orders-to-bigquery",
    "state": "running",
    "events_per_second": 4231.5,
    "replication_lag_ms": 12,
    "last_checkpoint_at": "2026-03-11T09:14:02Z"
  }
]

Create a pipeline

POST /v1/pipelines
Content-Type: application/json

Request body:

{
  "name": "orders-pipeline",
  "source": {
    "connection": "prod-postgres",
    "tables": ["public.orders", "public.order_items"]
  },
  "sink": {
    "connection": "prod-bigquery",
    "properties": { "table_id": "orders" }
  }
}

Response: 201 Created with the created pipeline object.

Get a pipeline

GET /v1/pipelines/{name}

Update a pipeline

PUT /v1/pipelines/{name}
Content-Type: application/json

Updates the pipeline definition and hot-reloads it.

Delete a pipeline

DELETE /v1/pipelines/{name}

Returns 204 No Content.

Get pipeline metrics

GET /v1/pipelines/{name}/metrics

{
  "name": "orders-to-bigquery",
  "state": "running",
  "events_per_second": 4231.5,
  "replication_lag_seconds": 0.012,
  "last_checkpoint_at": "2026-03-11T09:14:02Z",
  "events_total": 1482931,
  "sink_errors_total": 0
}

Get snapshot progress

GET /v1/pipelines/{name}/progress

{
  "phase": "snapshot",
  "tables": [
    {
      "table": "public.orders",
      "partitions_total": 20,
      "partitions_done": 14,
      "rows_total": 5000000,
      "rows_done": 3500000,
      "percent": 70.0
    }
  ]
}

Get run history

GET /v1/pipelines/{name}/runs

Returns run history with start time, duration, and event count per run.

Change pipeline state

PUT /v1/pipelines/{name}/state
Content-Type: application/json

{ "state": "start" }

Action	From state	To state
start	stopped	starting → running
stop	running	stopping → stopped
pause	running	paused
resume	paused	running

Schema review and approval

GET  /v1/pipelines/{name}/schema/proposed
POST /v1/pipelines/{name}/schema/approve

Used when a pipeline is paused in pending_schema_approval state.

Apply config

POST /v1/apply
Content-Type: application/json

{
  "connections": [...],
  "pipelines": [...]
}

---

Connection management

List connections

GET /v1/connections

Create a connection

POST /v1/connections
Content-Type: application/json

{
  "name": "prod-postgres",
  "type": "postgres",
  "dsn": "postgres://user:pass@host:5432/db?sslmode=require"
}

Get / Update / Delete a connection

GET    /v1/connections/{name}
PUT    /v1/connections/{name}
DELETE /v1/connections/{name}

DELETE returns 409 Conflict if a running pipeline references the connection. Use ?force=true to delete anyway.

---

System

Health check

GET /v1/health

{
  "status": "ok",
  "version": "v0.1.0",
  "workers": 3,
  "pipelines_running": 2
}

Worker fleet

GET /v1/workers

Prometheus metrics

GET /metrics

See Observability for the full metrics reference.

Web UI

GET /app/

The embedded management dashboard served directly from the binary.

---

Error responses

{
  "error": "pipeline not found",
  "code": "NOT_FOUND"
}

HTTP status	Meaning
400 Bad Request	Invalid request body or parameters
404 Not Found	Pipeline or connection does not exist
409 Conflict	State transition not allowed, or resource in use
422 Unprocessable Entity	Config validation failed
500 Internal Server Error	Unexpected server error