Get a field’s sub-fields

POST/api/pieces/{id}/actions/{actionId}/properties/{propertyName}

Asks an app for the fields of a field whose shape depends on other values, such as a sub-flow’s inputs.

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

Parameters

Path

idRequired · string: The app’s id.
actionIdRequired · string: The action the field belongs to.
propertyNameRequired · string: The field to describe.

Body

Send at least {}: no body at all is a 400.

valuesOptional · object: The step’s settings so far, as in its config. For a sub-flow, the workflow to call in workflow_id.
connectionIdOptional · UUID: A connection the app may sign in with. A worker reads it; the API never does. Sending one also needs the Write permission for workflows and the Read permission for connections.

The sub-flow case

The Sub-flow step’s input is answered by the API itself: the inputs the called workflow expects, filled from its trigger’s sample. Without workflow_id you get a placeholder.

Other apps are asked on a worker, which may sign in to the service with the connection. That’s why it needs the Read permission for workflows: it can return your workspace’s data. See Run another workflow.

Responses

200OK
The fields in properties, by name, in the same shape as an action’s own.
400INVALID_BODY
The body is missing or isn’t JSON.
400NOT_SUPPORTED
This app has no fields of this kind. Most don’t.
403FORBIDDEN
The token lacks the Read permission for workflows. With connectionId, it also needs the Write permission for workflows and the Read permission for connections, because the call uses that connection’s sign-in. details.permission names the one missing.
403PIECE_NOT_ALLOWED
This workspace may not use the app.
404NOT_FOUND
No worker has this app.
500RESOLVE_FAILED
The sub-flow’s inputs couldn’t be read.
500INTERNAL_ERROR
The worker failed or answered something unreadable.
503WORKER_UNAVAILABLE
No worker is checked in, so the app couldn’t be asked. Workflows are unaffected.
503PIECES_UNAVAILABLE
GoRunner couldn’t check which apps this workspace may use. 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 · 413 PAYLOAD_TOO_LARGE · 415 INVALID_CONTENT_TYPE · 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
APP_ID="subflow"
ACTION_ID="execute"
FIELD="input"

URL="$GORUNNER/api/pieces/$APP_ID/actions/"
URL="${URL}$ACTION_ID/properties/$FIELD"
curl -X POST "$URL" \
  -H "Authorization: Bearer $GORUNNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "workflow_id": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31"
    }
  }'

const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const APP_ID = process.env.APP_ID;
const ACTION_ID = process.env.ACTION_ID;
const FIELD = process.env.FIELD;

const res = await fetch(
  `${GORUNNER}/api/pieces/${APP_ID}/actions/` +
    `${ACTION_ID}/properties/${FIELD}`,
  {
    method: "POST",
    headers: {
        Authorization: `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
    body: JSON.stringify({
        values: {
          workflow_id: "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
        },
      }),
  },
);
const { data } = await res.json();

import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
APP_ID = os.environ["APP_ID"]
ACTION_ID = os.environ["ACTION_ID"]
FIELD = os.environ["FIELD"]

res = requests.post(
    f"{GORUNNER}/api/pieces/{APP_ID}/actions/"
    f"{ACTION_ID}/properties/{FIELD}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
      "values": {
        "workflow_id": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
      },
    },
)
data = res.json()["data"]

Response · 200 OK

json

{
  "data": {
    "properties": {
      "input": {
        "type": "object",
        "title": "Input",
        "description": "\"Order intake\" declares the input it expects; this field is pre-filled from that declaration.",
        "propertyType": "JSON",
        "order": 2,
        "default": {
          "orderId": ""
        }
      }
    }
  }
}

Every field

The step configuration so far, plus the connection to resolve credentials with. Send at least {}: no body at all is a 400 INVALID_BODY.

Body

valuesOptional · object: The step’s configuration so far, keyed by property name — the same object that becomes the step’s config. For the sub-flow case put the target workflow’s UUID in values.workflow_id.
connectionIdOptional · UUID: Connection whose credentials the app should use. Only the id travels; the worker decrypts it.

Response · 200 OK

dataobject

The resolved sub-schema.

propertiesobject

Resolved properties keyed by property name, in the full (unprojected) property shape.

{key}object

One property of a full (unprojected) schema. Recursive through properties and items. Carries presentation fields (title, order, placeholder, group) that the projected views drop.

Each key’s value.

typestring

JSON type: string, number, boolean, object, array.

titlestring

descriptionstring

The field’s help as the step panel shows it.

default

Default value, of any JSON type.

enumarray of strings

Closed set of legal values.

enumLabelsobject

Display labels for the enum values.

{key}string

Each key’s value.

formatstring

propertiesobject

{key}object

One property of a full (unprojected) schema. Recursive through properties and items. Carries presentation fields (title, order, placeholder, group) that the projected views drop.

The same fields as data.properties.{key} above.

itemsobject

One property of a full (unprojected) schema. Recursive through properties and items. Carries presentation fields (title, order, placeholder, group) that the projected views drop.

The same fields as data.properties.{key} above.

propertyTypestring

How the value is chosen: SHORT_TEXT, LONG_TEXT, STATIC_DROPDOWN, DROPDOWN, MULTI_SELECT, DYNAMIC, JSON, CODE, CHECKBOX, NUMBER, SECRET_TEXT and similar. DROPDOWN / MULTI_SELECT / DYNAMIC mean the legal values come from POST .../options/{propertyName} at run time, not from this schema.

placeholderstring

groupstring

orderinteger

requiredboolean

minLengthinteger

maxLengthinteger

minnumber

maxnumber

patternstring

refreshersarray of strings

Other property names whose change invalidates this property’s resolved options.

refreshOnSearchboolean

expressionEnabledboolean

languagestring

For CODE properties: the language of the editor, e.g. javascript.

displayConditionsarray of objects

ANDed conditions deciding whether this property applies. The fields they name are this operation’s gate fields — the ones you can pass as query parameters to narrow the operation detail.

fieldstring

The sibling property whose value decides this one. Every gate field is itself a property of the same schema, so its declared type and enum are the legal values.

operatorstring

An unrecognized operator is treated permissively (the property is kept).

One of eq, neq, in, notIn, contains_any, exists, notExists.

value

Comparison value for eq/neq, of any scalar JSON type.

valuesarray

Candidate list for in / notIn / contains_any.

boundboolean

The value, though typed as text, points into the connected account (a spreadsheet, a calendar, a folder, a label): it means nothing to another account, so a template used outside the workspace it was saved in arrives with it blank. Absent when false.

noExpressionsboolean

True when {{ }} is NOT replaced in this field: the value is used exactly as written (Code 2.0.0’s code, where values come from inputs, steps and trigger instead). Never write an expression into such a field.

agentNotesstring

What an agent writing this field must know beyond description; the step panel does not show it. The projected views append it to description. Absent when there is none.

Get a field’s sub-fields

Parameters

Path

Body

The sub-flow case

Responses

Body

Response · 200 OK

Panel