Core Hub REST API

Core Hub exposes the same low-level REST API that the Control Plane itself uses to provision pipelines, attach agents, push credentials, define entities, introspect sources, and drive sync. It is powerful, and it is an advanced tool. If your goal is to fire an action, or a chain of actions, use Chronos webhooks instead — they are part of every deployment, they authenticate with a single token, they log every run, and they can wait for an action to actually finish.

Start with webhooks. Reach for the REST API only when you have already tried webhooks and your use case genuinely goes beyond what they can express.

Choose the right tool

What you want to do Use Why

Start, stop, redo, or snapshot a pipeline, group, or entity from an external system

Chronos webhook

One POST with a secret token. Runs the action, records the outcome, and can block until the chain completes.

Run a chain of actions in order (stop → snapshot → start)

Chronos webhook

Chained events run sequentially and, in sync mode, wait for Core Hub to confirm each step before moving on.

React to something that happened inside Gluesync (snapshot completed, CDC started, pipeline entered maintenance)

Chronos platform event

Core Hub pushes the event to Chronos. No polling, no external caller.

Run SQL or start a published AI agent on a schedule or on demand

Chronos webhook

The query_studio and ai_agent_run actions are available to schedules, platform events, and webhook triggers alike.

Let an AI assistant read and operate your deployment conversationally

Core Hub MCP server

Purpose-built tool surface with the same authorization model as the Control Plane.

Create a pipeline, attach agents, push credentials, or upsert entity definitions from code

REST API

No webhook covers deployment provisioning. This is what the API is for.

Discover schemas, tables, and columns on a connected source

REST API

Discovery endpoints are read-only introspection, not actions.

Scrape per-pipeline Prometheus metrics

REST API

A single text endpoint, easily wired into an existing scrape config.

Fire actions with webhooks

Chronos ships and runs in every Gluesync deployment. You do not install or configure anything to get its webhook surface — it is there by default, and it is reachable through the same origin as the Control Plane.

Create a webhook-triggered event in Scheduler → Events → New → Webhook trigger. On save, Chronos shows a secret token and a stable trigger URL once. Fire it from anywhere:

curl -X POST "https://your-gluesync.com/chronos/api/triggers/42/fire" \
  -H "X-Trigger-Token: sk_Jd8fkQ29Xm5..."

Add ?wait=true&wait_timeout_seconds=300 when a CI/CD job needs the outcome before it continues.

What you get without writing any of it yourself:

  • Authentication scoped to one flow, rotatable with Regenerate token, verified in constant time

  • Execution logs per run, expandable from the events table, plus last_triggered and last_error_message

  • Ordered chains with async or sync execution, where sync waits on real Core Hub completion events rather than guessing

  • An off switch — disable a flow instead of deleting it, and every fire request is rejected while it is off

  • A UI your operators can use without a shell

To go the other way and react to Gluesync activity, choose the Platform event tab instead and pick a Core Hub event type. Chronos registers the Core Hub callback for you.

Full detail lives in Events, Chained events, and Chronos webhooks.

When the REST API is the right tool

The REST API is for experienced users automating, executing, or retrieving specific and complex Core Hub behaviors that no webhook action expresses. Typical cases:

  • Provisioning — creating pipelines, attaching and detaching agents, dispatching host credentials, and upserting entity definitions as part of infrastructure-as-code

  • Introspection — reading a pipeline’s full configuration, or walking a source’s schemas, tables, and columns to generate entity definitions programmatically

  • Bulk or generated configuration — applying agent-specific settings that have no Control Plane form

  • Metrics collection — scraping the per-pipeline Prometheus endpoint

Before you commit to it, be aware of what you take on:

The API is fire-and-forget. Command and configuration endpoints answer 202 Accepted once the instruction has been dispatched to the agents — not once the work is done. There is no completion callback, no run history, and no retry. If you need to know that a snapshot finished, you have to build that yourself, or use a Chronos sync chained event, which already waits on ENTITY_SNAPSHOT_COMPLETED.

The API also has no per-integration credential: callers authenticate as a Gluesync user, with that user’s full role permissions.

The OpenAPI document

The complete specification for the endpoints below ships with this documentation.

Download the Core Hub OpenAPI 3.0.3 document (openapi.yaml)

Load it into Postman, Insomnia, or an OpenAPI code generator to produce a typed client. The OpenAPI explorer covers the ways to open and use it.

Every running deployment serves its own live, interactive Swagger UI:

Resource Access

Swagger UI (live deployment)

https://COREHUBADDRESS/swagger — replace COREHUBADDRESS with your server address. Authentication is required; log in to the Control Plane first in the same browser session so Swagger UI can load the protected definitions, then click Authorize and paste your JWT.

OpenAPI document

openapi.yaml

Postman collection

MOLO17 Gluesync Workspace
Property Value

Protocol

JSON over HTTP. Use HTTPS in production.

Default port

:443 when the reverse proxy is enabled, :1717 when it is disabled

Authentication

JWT Bearer token obtained from /authentication/login

Base path

Endpoints sit at the server root — there is no /api prefix

Authentication

Get a token

curl -X POST https://your-gluesync.com/authentication/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'

The response carries the token and whether the account must change its password before it can do anything else:

{
  "token": "eyJhbGciOi...",
  "changeRequired": false
}

A 401 means the username or password is wrong. A 408 means the request timed out waiting for a response.

Use the token

curl -X GET https://your-gluesync.com/pipelines \
  -H "Authorization: Bearer <your-token>"

The Control Plane uses the gs-auth HttpOnly cookie automatically in the browser. Scripts and CLI tools must send the Authorization: Bearer header themselves.

Tokens expire with the session. The default session lasts 72 hours; a SUPER ADMIN can change it in the server configuration.

Change a password

curl -X POST https://your-gluesync.com/authentication/reset-password \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"oldPassword": "current", "newPassword": "new"}'

Returns 202 Accepted on success.

Service accounts

Create a dedicated local account for every automation, with the narrowest role that still works.

Do not embed or reuse admin credentials in scripts.

OIDC users cannot authenticate programmatically: there is no machine-to-machine OIDC login flow. API automation must use a local account. This is another reason to prefer webhooks — a Chronos trigger token is not tied to a human identity at all.

Endpoint reference

{pipelineId} and {agentId} are the IDs shown in the Control Plane. See Finding IDs for how to copy them.

Authentication endpoints

Method Path Description

POST

/authentication/login

Exchange username and password for a JWT. Returns the token and changeRequired.

POST

/authentication/reset-password

Change the current user’s password. Body: oldPassword, newPassword.

Pipelines

Method Path Description

GET

/pipelines

List every pipeline. Each item carries id, name, and an optional description.

POST

/pipelines

Create a pipeline from name and optional description. Returns the new pipelineId.

GET

/pipelines/{pipelineId}

Fetch one pipeline. 404 if the ID does not exist.

PUT

/pipelines/{pipelineId}

Rename or re-describe a pipeline.

Agents

Method Path Description

GET

/unassigned-agents

List agents that have connected to Core Hub but are not attached to any pipeline yet.

GET

/pipelines/{pipelineId}/agents

List the agents attached to a pipeline. Each carries id, agentName, agentTag, and agentType (SOURCE or TARGET).

GET

/pipelines/{pipelineId}/agents/{agentId}

Fetch one attached agent.

PUT

/pipelines/{pipelineId}/agents/{agentId}

Attach an agent to the pipeline. Returns 409 Conflict when the agent is already attached elsewhere.

DELETE

/pipelines/{pipelineId}/agents/{agentId}

Detach an agent. Returns 202 Accepted.

Agent configuration

Every endpoint in this group dispatches configuration to the running agents asynchronously.

Method Path Description

PUT

/pipelines/{pipelineId}/agents/{agentId}/config/credentials

Send host credentials to the agent. Body is a HostCredentials object — connectionName, host, databaseName, and additionalHosts are required; port, username, password, connectionString, maxConnectionsCount, disableAuth, and the TLS fields (enableTls, tlsName, trustStorePath, trustStorePassword, keyStorePath, keyStorePassword, certificatePath, certificatePassword) are optional. Returns 202 with Credentials sent to agents.

PUT

/pipelines/{pipelineId}/agents/{agentId}/config/entities

Create or update entity definitions. Body: {"entities": […​]}. Returns 200 with Entity upsert success.

DELETE

/pipelines/{pipelineId}/agents/{agentId}/config/entities/{entityName}

Remove one entity definition by name.

PUT

/pipelines/{pipelineId}/agents/{agentId}/config/specific

Apply free-form, agent-specific settings. Body is an arbitrary JSON object whose accepted keys depend on the agent — read them from discovery/node-info first. Returns 202 with Specific configuration sent to agents.

Pipeline configuration

Method Path Description

GET

/pipelines/{pipelineId}/config

Read the full configuration of a pipeline and its agents.

PUT

/pipelines/{pipelineId}/config

Push the stored configuration out to the agents. Returns 202 with Configuration dispatched to agents.

Discovery

Read-only introspection against the live source or target. Use these to build entity definitions instead of hand-writing them.

Method Path Description

GET

/pipelines/{pipelineId}/agents/{agentId}/discovery/node-info

Describe what the agent supports: implementedEntityTypes, plus the property descriptors (name, type, default) for host credentials, custom properties, entity properties, and table properties. Call this before writing to config/specific.

GET

/pipelines/{pipelineId}/agents/{agentId}/discovery/schemas

List the schemas visible to the agent.

GET

/pipelines/{pipelineId}/agents/{agentId}/discovery/tables?schema=<schema>

List tables in a schema. 400 if schema is missing.

GET

/pipelines/{pipelineId}/agents/{agentId}/discovery/columns?tableschema=<schema>&tablename=<table>

List a table’s columns with their types. 400 if either query parameter is missing.

Sync commands

These four endpoints are the ones Chronos already wraps. If you are calling them from a script, a webhook-triggered event does the same work with a token, an audit trail, and the option to wait for completion. See Events.

All four accept a repeatable entity query parameter to scope the command; omit it to target the whole pipeline. All four return 202 Accepted as soon as the command reaches the agents.

Method Path Description

POST

/pipelines/{pipelineId}/commands/sync/start

Start syncing. Start command received and dispatched to agents.

POST

/pipelines/{pipelineId}/commands/sync/stop

Stop syncing. Stop command received and dispatched to agents.

POST

/pipelines/{pipelineId}/commands/sync/redo

Restart the sync. Restart sync command received and dispatched to agents.

POST

/pipelines/{pipelineId}/commands/sync/one-time-snapshot

Run a single snapshot. One time snapshot command received and dispatched to agents.
Scope a command to two entities
curl -X POST "https://your-gluesync.com/pipelines/$PIPELINE_ID/commands/sync/one-time-snapshot?entity=customers&entity=orders" \
  -H "Authorization: Bearer $TOKEN"

Metrics

Method Path Description

GET

/pipelines/{pipelineId}/metrics

Prometheus exposition format as text/plain, scoped to one pipeline.

See Prometheus integration for scrape configuration.

Response conventions

The same few status codes recur across the whole surface. Handle them once, in your client.

Status Meaning

200 OK

The request completed and the body holds the result.

202 Accepted

Core Hub accepted the instruction and dispatched it to the agents. It does not mean the work finished. Poll /pipelines/{pipelineId}/config or the pipeline metrics if you need to confirm the effect, or use a Chronos sync chained event.

400 Bad Request

A required query parameter or body field is missing. The plain-text body names it.

401 Unauthorized

Bad credentials on login, or a missing, expired, or malformed Bearer token.

404 Not Found

The pipeline, agent, or entity ID does not exist.

409 Conflict

The agent is already attached to a pipeline.

500 Internal Server Error

A plain-text message describing which operation failed.

408 Request Timeout

Timed out waiting for response — Core Hub could not reach the agents in time. The command may still land. Retries are not idempotent for command endpoints, so verify state before re-sending.

Error bodies are plain text, not JSON. Do not parse them as structured errors.

Finding IDs

The Control Plane exposes every ID you need for a request path.

Control plane - pipeline ID

Click the ID field to copy it to the clipboard, then paste it straight into your API call. Agent IDs appear the same way on the agent card, and GET /pipelines and GET /pipelines/{pipelineId}/agents return them if you would rather discover them programmatically.

Best practices

Security

  • Use HTTPS in production

  • Keep Bearer tokens out of client-side code, CI logs, and public repositories

  • Give every automation its own local account with the narrowest role that works

  • Rotate service-account credentials on a schedule

  • Monitor API usage

Reliability

  • Treat 202 as "dispatched", never as "done"

  • Do not blindly retry a 408 on a command endpoint — verify state first

  • Read discovery/node-info before writing to config/specific, so you send keys the agent actually understands

  • Push credentials and entities before dispatching configuration, not after

Performance

  • Cache discovery responses; schemas and tables change rarely

  • Batch entity upserts into a single config/entities call instead of one call per entity

  • Scrape metrics on an interval that matches your Prometheus configuration, not in a tight loop

See also