GoRunner docs
Search or askSearch⌘K

List versions

GET/api/workflows/{id}/versions

Returns a workflow’s published versions, newest first, without their definitions.

Needs an API token with the Read permission for workflows (workflow:read).

Parameters

Path

idRequired · UUID

The workflow’s ID.

Query

pageOptional · integer

The page, from 1.

limitOptional · integer

Versions a page, 1 to 100. The default is 20; anything else reads as 20.

Read a row

Each publish that changed something makes one version. Publishing the same tree again makes none.

change says what changed since the version before, by step name; its summary is one line: “Added Log it · Edited Fetch customers”. changeMessage is empty: nothing writes it. publishedBy is missing when a token, not a person, published it.

onCanvas marks the one version, if any, that matches the draft. The live one is the workflow’s latestVersionId. For a version’s tree, get the version.

Responses

  • 200OK

    A page of versions. None answers [].

  • id isn’t a UUID.

  • The token lacks the Read permission for workflows.

  • No workflow with this ID in the token’s workspace.

  • The versions couldn’t be read. Try again.

Any call can also answer: 401 UNAUTHORIZED · 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 403 FEATURE_OFF · 403 EMBED_NOT_ALLOWED · 403 EMBED_NOT_AVAILABLE · 403 ACCOUNT_SUSPENDED · 429 RATE_LIMITED · 503 BUSY · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.

Request

GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs Read for workflows
WORKFLOW_ID="your-workflow-id"

URL="$GORUNNER/api/workflows/$WORKFLOW_ID/"
URL="${URL}versions?limit=20"
curl "$URL" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"

Response · 200 OK

json
{
  "data": [
    {
      "id": "f20f671a-2c8e-4b9d-a7f1-6e3b0d5c9a12",
      "workflowId": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
      "versionNumber": 3,
      "publishedBy": "5d8e1f3a-0b6c-4e2d-9f7a-1c3b5e8d2a40",
      "changeMessage": "",
      "createdAt": "2026-10-24T16:41:00Z",
      "onCanvas": true,
      "change": {
        "changed": [
          "Forward to fulfilment"
        ],
        "summary": "Edited Forward to fulfilment"
      }
    },
    {
      "id": "1d7f3b9e-2c4a-4e6b-8d0f-5a3c9e1b7d26",
      "workflowId": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
      "versionNumber": 2,
      "publishedBy": "5d8e1f3a-0b6c-4e2d-9f7a-1c3b5e8d2a40",
      "changeMessage": "",
      "createdAt": "2026-10-22T10:05:00Z",
      "onCanvas": false,
      "change": {
        "changed": [
          "Order received"
        ],
        "summary": "Edited Order received"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}
Every field

It takes no body.

Response · 200 OK

dataarray of objects
idUUID
workflowIdUUID
versionNumberinteger

1-based, increasing.

definitionobject

OMITTED from the versions LIST; present on the single-version read.

A workflow definition: its fields are in Workflow definition.

publishedByUUID

Who published it (a user id). Absent — never null — when a machine principal or the dev principal published it: a version names a person or nobody.

changeMessagestring

Kept for old clients: nothing writes it, so it is empty. change.summary (on the list) says what changed.

createdAttime
onCanvasboolean

Marks the AT MOST ONE version whose snapshot equals the current DRAFT. Computed only by the LIST (false on a single read). Distinct from LIVE, which is the workflow’s latestVersionId.

changeobject

LIST only: what this version changed against the one before it, keyed on step name, as the list shows it. Absent on the single-version read, and on the last row of a page when the version before it is not in hand.

firstboolean

The first version: nothing to compare with.

addedarray of strings

Steps added, by display name, in canvas order.

removedarray of strings

Steps removed, by display name.

changedarray of strings

Steps changed, by display name.

triggerstring

How the way it starts changed, in words ("Webhook replaced Schedule", "Webhook reconfigured"); absent when it did not.

settingsboolean

The workflow-level settings changed (timeout, concurrency, error workflow).

summarystring

The one-line form the row shows.

paginationobject

Paging envelope returned alongside data on list endpoints.

pageinteger

The 1-based page that was returned.

limitinteger

Rows per page actually applied (not necessarily what you asked for — out-of-range values fall back to 20).

totalinteger

Total matching rows across all pages.

totalPagesinteger