Skip to main content

The Circus Machine API from Your Workflow

The Circus nodes call the platform's machine API for you, so you rarely invoke it by hand. But it helps to know the surface — what the nodes are actually doing under the hood, and what to reach for if you ever build a callback yourself. This is the workflow's-eye view; for the full, authoritative contract, see the Plugin Developer package's Core API Reference ("when in doubt, go there").

The endpoints your workflow uses​

All of them live under /api/machine/ and authenticate with your Circus API key (as a Bearer token):

  • POST /api/machine/health — a simple health check. This is what the circusApi credential test calls when you save it.
  • POST /api/machine/workflow-executions/:id/logs — record a step. This is the workhorse: Init, Agent, and Log all call it. Its response carries the cost/time tally and the abort flag (see Handling the Abort Flag).
  • POST /api/machine/workflow-executions/:id/complete — mark the run successful and hand back the result payload (the Complete node).
  • POST /api/machine/workflow-executions/:id/terminate — mark the run failed (the Terminate node, and the self-terminating Agent/Log nodes).

Every one of these callbacks carries the external_execution_id, and responses follow the platform's standard { "data": ... } (or { "error": ... }) envelope.

Rules worth knowing​

A few behaviours explain what you'll see:

  • Logs are only accepted while the run is running. Once an execution is completed, terminated, or otherwise finished, further log calls are rejected — which is part of why calling Complete early is a problem (see The Complete Node & Result Payload).
  • Callbacks require the external_execution_id, and a mismatched one is rejected with a 409 conflict (see Staying in Sync).
  • Endpoint names can change; purposes don't. When you integrate, anchor on what an endpoint is for and confirm the exact path against the Core API Reference rather than hardcoding assumptions.

You usually don't call these directly​

For ordinary workflows, the five nodes cover all of this — you place them and the API calls happen correctly. The reason to know the surface is for debugging (reading what a node did in the execution log) and for the occasional advanced case where you build a custom call. For anything beyond the tour above, the Core API Reference is the source of truth.