genroc

    docs / Reference / REST API

    Instances

    The 10 HTTP endpoints under Instances.

    POST /api/instances

    Start a new process instance (omit version to use latest)

    Requires the operate permission (or admin).

    Request

    {
      "process": "order_pipeline",
      "version": 1,
      "input": {
        "order_id": 42
      }
    }

    Response

    {
      "id": "5fy765kh",
      "process": "order_pipeline",
      "version": 1,
      "status": "running"
    }

    Fails with 400, 404, 500.

    GET /api/instances

    List process instances - roots only unless children=true, so one row per tree

    Requires the read permission (or admin).

    ParameterInDescription
    statusqueryFilter by status, or several comma-separated (running,paused) -- the grammar genctl upgrade --status takes. The enum is the vocabulary; a comma-separated list of those values is accepted. One of running, pausing, paused, failing, cancelling, completed, failed, raised, cancelled.
    phasequeryFilter by why a running instance is not executing a task. The three are not one kind of thing: children (blocked until its children settle), collecting (children terminal, their outputs still to merge — runnable now), external (parked until someone answers, or until its timeout). Orthogonal to status — all three are still running, and survive a pause
    taskqueryFilter by the exact task id the instance sits on — where it is running, parked, or where it stopped. A task id is unique only within its definition, so pair it with process to mean one task
    error_codequeryFilter by exact error code. Authored codes (from a raise or panic clause) are lower_snake_case; engine-produced codes contain a dot, e.g. http.500, pre.timeout, engine.spawn.
    processqueryFilter by exact process name, across every version
    versionqueryFilter by exact process version (0 = any)
    childrenqueryInclude child instances. Omitted, the listing is ROOTS ONLY - one row per tree, which is the unit an upgrade or a pause acts on; a child_list fan-out would otherwise bury the roots it belongs to. Every row carries parent_id, so the two are still told apart when children are included
    created_afterqueryOnly instances created at/after this unix-millis timestamp
    created_beforequeryOnly instances created strictly before this unix-millis timestamp
    updated_afterqueryOnly instances updated at/after this unix-millis timestamp
    updated_beforequeryOnly instances updated strictly before this unix-millis timestamp
    sortquerySort key (per-endpoint whitelist; omit for the default)
    orderquerySort direction (omit for the endpoint default). One of asc, desc.
    limitqueryPage size (default 20, cap 100)
    afterqueryCursor from a previous page's page.next_cursor — fetch the next page
    beforequeryCursor from a previous page's page.previous_cursor — fetch the previous page

    Response

    {
      "items": null,
      "page": {
        "size": 0,
        "items_before": 0,
        "items_after": 0,
        "sort": "",
        "order": ""
      }
    }

    Fails with 400, 500.

    GET /api/instances/{id}/detail

    Get everything stored on a process instance: its state verbatim, plus the columns around it

    Requires the read permission (or admin).

    ParameterInDescription
    idpathThe instance id

    Response

    {
      "id": "5fy765kh",
      "process": "order_pipeline",
      "version": 1,
      "status": "running",
      "task": "charge_card",
      "retry_count": 0,
      "created_at": "",
      "updated_at": "",
      "children": {
        "charge_card": "3k1nz7pq"
      },
      "state": {
        "input": {
          "order_id": 42
        },
        "last_error": null,
        "outputs": {
          "render": null,
          "reserve": {
            "ok": true
          }
        }
      },
      "lease_epoch": 0,
      "task_epoch": 3,
      "parent_task_epoch": 0,
      "next_replayable": false,
      "external_claim_epoch": 0,
      "objects": [
        {
          "path": [
            "state",
            "outputs",
            "render"
          ],
          "ref": "9f2ac1b4e7d05f38a61c0d2e4b7f9a13",
          "size": 221110
        }
      ]
    }

    Fails with 400, 404, 500.

    GET /api/instances/{id}

    Get status of a process instance

    Requires the read permission (or admin).

    ParameterInDescription
    idpathThe instance id

    Response

    {
      "id": "5fy765kh",
      "process": "order_pipeline",
      "version": 1,
      "status": "failed",
      "task": "charge_card",
      "retry_count": 0,
      "error_code": "only_once.interrupted",
      "error_message": "the task may have already run",
      "output": {
        "shipped": true
      },
      "created_at": "",
      "updated_at": ""
    }

    Fails with 400, 404, 500.

    GET /api/instances/{id}/logs

    Get the execution audit trail for a process instance (newest first) - the whole tree when the id names a root, unless flat=true

    Requires the read permission (or admin).

    ParameterInDescription
    levelqueryLowest level to return: this level and everything above it (warn keeps errors). One of debug, info, warn, error.
    created_afterqueryOnly logs at/after this unix-millis timestamp
    created_beforequeryOnly logs strictly before this unix-millis timestamp
    flatqueryThis instance's own rows only. Without it a ROOT id answers with every row in its tree, which is one indexed read rather than a walk; a child id answers with its own rows either way, since a tree is addressed by its root
    sortquerySort key (per-endpoint whitelist; omit for the default)
    orderquerySort direction (omit for the endpoint default). One of asc, desc.
    limitqueryPage size (default 20, cap 100)
    afterqueryCursor from a previous page's page.next_cursor — fetch the next page
    beforequeryCursor from a previous page's page.previous_cursor — fetch the previous page
    idpathThe instance id

    Response

    {
      "items": null,
      "page": {
        "size": 0,
        "items_before": 0,
        "items_after": 0,
        "sort": "",
        "order": ""
      }
    }

    Fails with 400, 404, 500.

    POST /api/instances/{id}/pause

    Pause a running root process instance and its entire descendant tree; takes effect at the next task boundary, so a task already executing runs to completion. An assertion: 200 if the tree stopped, 202 if a task already in flight is still draining, 204 if it was not running anyway

    Requires the operate permission (or admin).

    ParameterInDescription
    idpathThe root instance's id; the call acts on its whole tree and refuses a child

    Response

    {
      "outcome": "",
      "status": "",
      "instances": 0
    }

    Fails with 400, 404, 500.

    POST /api/instances/{id}/resume

    Resume a paused root process instance and its tree, continuing exactly where it stopped (timers kept running while paused). An assertion: 200 if it was resumed, 204 if the tree was already advancing; 409 only if it has settled and cannot advance again

    Requires the operate permission (or admin).

    ParameterInDescription
    idpathThe root instance's id; the call acts on its whole tree and refuses a child

    Response

    {
      "outcome": "",
      "status": "",
      "instances": 0
    }

    Fails with 400, 404, 409, 500.

    POST /api/instances/{id}/cancel

    Stop a root process instance and its entire descendant tree for good. Terminal and irreversible — unlike pause there is no way back, and a cancelled instance is not retryable. Takes effect at the next task boundary, so a task already executing runs to completion; a claimed external task is told to stop on its next renewal. An assertion: 200 if the tree stopped, 202 if a task already in flight is still draining, 204 if there was nothing live to stop

    Requires the operate permission (or admin).

    ParameterInDescription
    idpathThe root instance's id; the call acts on its whole tree and refuses a child

    Response

    {
      "outcome": "",
      "status": "",
      "instances": 0
    }

    Fails with 400, 404, 500.

    POST /api/instances/{id}/retry

    Retry a failed root process instance, reviving its tree where it died and granting the failing task another attempt beyond its on_error budget

    Requires the operate permission (or admin).

    ParameterInDescription
    forcequeryOverride only_once retry protection
    idpathThe root instance's id; the call acts on its whole tree and refuses a child

    Response

    {
      "outcome": "",
      "status": "",
      "instances": 0
    }

    Fails with 400, 404, 409, 500.

    POST /api/instances/{id}/upgrade

    Move a process instance and every live descendant to another version of their definitions

    Requires the deploy permission (or admin).

    ParameterInDescription
    idpathThe root instance's id; the call acts on its whole tree and refuses a child

    Request

    {
      "from_version": 0,
      "to_version": 0
    }

    Response

    {
      "upgraded": false,
      "moves": null
    }

    Fails with 400, 404, 409, 500.