Search docs.molo17.com

    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.

    How-to guide

    For a step-by-step walkthrough tested on a running Gluesync, see the how-to guide Automate Gluesync with the REST API, MCP and webhooks.

    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 Prometheus metrics, or read the metrics of one pipeline

    REST API

    /metrics is a single Prometheus text endpoint for every pipeline, easily wired into an existing scrape config. /pipelines/{pipelineId}/metrics answers JSON for one pipeline.

    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 Prometheus endpoint, or reading the JSON metrics of one pipeline

    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.

    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 in apiToken and whether the account must change its password before it can do anything else:

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

    Read the token with jq -r .apiToken. Core Hub also sets it in the gs-auth cookie for the browser. 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 apiToken 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 that takes an entity ID (not the entity name) to scope the command; omit it to target the whole pipeline. Read the IDs with GET /pipelines/{pipelineId}/entities-status or copy them from the Control Plane. All four return 202 Accepted as soon as the command reaches the agents, even for an ID that does not exist, so check the effect afterwards.

    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, by entity ID
    curl -X POST "https://your-gluesync.com/pipelines/$PIPELINE_ID/commands/sync/one-time-snapshot?entity=3198138e&entity=8f2edc67" \
      -H "Authorization: Bearer $TOKEN"

    Metrics

    Method Path Description

    GET

    /pipelines/{pipelineId}/metrics

    The metrics of one pipeline as JSON.

    GET

    /metrics

    Prometheus exposition format as text/plain, for every pipeline. Each series carries a pipelineId label; filter on it to keep 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 or invalid. The message 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

    The message says which operation failed, and exceptionMessage gives the underlying error.

    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 JSON, with message as the field to show or log:

    {"notificationId": -1, "exceptionMessage": null, "message": "User not authorized, please verify your username and password"}

    notificationId points to the Control Plane notification raised for the error (-1 when there is none), and some errors add a code. The success confirmations of the command endpoints, such as Start command received and dispatched to agents, are plain text, and so are a 408 and a few input checks. Parse the body as JSON and fall back to the raw text when it is not JSON.

    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