GoRunner docs
Search or askSearch⌘K

List apps

GET/api/pieces

Lists the apps this installation’s workers can run, with every action and trigger.

Needs any API token. No permission is checked.

Parameters

Query

viewOptional · string

index: one short line per app. Left out: every app in full, a very large answer. Any other value is refused.

qOptional · string

With view=index: words to find, such as “send an email”. The best 25 apps, best first.

categoryOptional · string

With view=index: one category, ignoring case: Triggers, Logic, Data, HTTP, Communication.

What are the rarely used parameters?
If-None-MatchOptional · string

An ETag this call gave you for the same view. If nothing changed, you get 304 and no body.

Start with the index

The full list holds every field of every action and trigger, and is very large. The index has what you need to choose an app: its id, name, category, versions, and its action and trigger ids. Then fetch just the action you need with Get an action’s fields.

q and category work only with the index. On the full list they are ignored.

Caching

An answer without q or category has an ETag; send it back as If-None-Match for a 304. Filtered answers have none.

Every answer has an X-GoRunner-Catalog-Source header. fleet: workers are checked in and runs work. last-known or compiled: no worker is, so you can read apps and edit workflows, but nothing runs. See Catalog status.

Responses

  • 200OK

    The apps: in full, or one line each with view=index. A partner’s customer account limited to some apps gets only those.

  • 304

    Nothing changed since the ETag you sent. No body.

  • 400VALIDATION_ERROR

    view has a value other than index.

  • 403FORBIDDEN

    The token may not do this.

  • 500INTERNAL_ERROR

    The list couldn’t be made. Try again.

  • 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 · 429 RATE_LIMITED · 503 BUSY · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.

Request

GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs any API token

curl "$GORUNNER/api/pieces?view=index&q=send+an+email" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"

Response · 200 OK, shortened

json
{
  "data": [
    {
      "id": "email",
      "name": "Email (SMTP)",
      "description": "Send emails using SMTP",
      "category": "Communication",
      "version": "1.0.0",
      "versions": [
        "1.0.0"
      ],
      "actionIds": [
        "send_email",
        "send_and_wait"
      ],
      "needsConnection": true
    }
  ]
}
Every field

It takes no body.

Response · 200 OK, the whole app

dataarray of objects

Default view: every app with full action/trigger schemas.

idstring

The value a step stores in pieceId.

namestring
descriptionstring
logoUrlstring

Icon path. A /icons/ prefix is what classifies the app as core.

versionstring

The version a new step is pinned to (the default), not necessarily the newest in versions.

versionsarray of strings

Every version the fleet can run, oldest first. An unpinned step resolves to the OLDEST.

iconstring

Icon name for apps without a logo file.

categorystring
nodeTypestring

What kind of node this app produces on the canvas.

One of action, trigger, branch, loop.

kindstring

core = shipped and owned by this product; app = third-party connector.

One of core, app.

actionsarray of objects or null

Actions of the DEFAULT version only. null when the app has none.

idstring

The value a step stores in actionId.

namestring
descriptionstring
sideEffectsstring

What running this does to the world. An untagged action is treated as writes_external (fail-safe). Anything that can write must not be test-executed without the user’s consent.

One of pure, reads_external, writes_external.

inputSchemaobject

An operation’s full input or output schema, as served by the default catalog views.

typestring
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.

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.actions.inputSchema.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.actions.inputSchema.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.

requiredarray of strings
outputSchemaobject

An operation’s full input or output schema, as served by the default catalog views.

The same fields as data.actions.inputSchema above.

sampleDataobject

Structurally accurate example of this action’s output.

errorHandlingobject

Per-action retry defaults.

retryOnFailureboolean
maxRetriesinteger
continueOnFailureboolean
timeoutSecondsinteger

Budget this action needs when the step sets none. 0 means the engine default (30s).

triggersarray of objects or null

Triggers of the DEFAULT version only. null when the app has none.

idstring

The value a definition’s trigger stores in its actionId field.

namestring
descriptionstring
typestring

How this trigger fires. ALWAYS LOWERCASE — unlike a step’s type (PIECE / BRANCH / LOOP / CODE), which is uppercase.

One of manual, webhook, cron, poll, error, run_finished, callable.

inputSchemaobject

An operation’s full input or output schema, as served by the default catalog views.

The same fields as data.actions.inputSchema above.

outputSchemaobject

An operation’s full input or output schema, as served by the default catalog views.

The same fields as data.actions.inputSchema above.

sampleDataobject

Declared example of what {{trigger.*}} resolves to.

derivesSampleboolean

True when the real payload shape depends on this trigger’s configuration, so sampleData is generic and misleading. Call POST /api/pieces/{id}/triggers/{triggerId}/sample instead.

authobject

The credential an app needs. Present means a connection is required before the app can run.

typestring

Credential family.

One of none, api_key, bearer_token, basic_auth, oauth2, custom.

requiredboolean
descriptionstring
fieldsarray of objects
namestring
titlestring
typestring

One of string, password, boolean.

requiredboolean
descriptionstring
standaloneboolean

On an app that also signs in with OAuth2: the credential a person makes in the service (a personal access token, an API key, a bot or app token) that works on its own and lasts. A form that cannot offer the OAuth sign-in asks for it alone. Absent means false.

oauth2object

The OAuth2 endpoints an app declares. These are the trusted endpoints; a managed instance app is keyed off authorizationUrl.

authorizationUrlstring
tokenUrlstring
scopesarray of strings
scopeSepstring

Delimiter used to join scopes. Defaults to a single space; a few providers want a comma.

authParamsobject

Extra query parameters merged into the authorize URL.

{key}string

Each key’s value.

connectionPiecestring

The app whose connections this one uses (a poll trigger and its action sibling: gmailtrigger → gmail). A connection created for this app is created under that one, and serves both.

helpUrlURL

Where to make the credential at the service.

keywordsarray of strings

Words people search for the app by that its name and description do not say ("email" for Gmail). Absent for most apps.

actionsByVersionobject

Action ids each version declares, keyed by version. Validate a step pinned to an older pieceVersion against ITS entry, not against actions.

{key}array of strings

Each key’s value.

actionsAtobject

The FULL action definitions (input schemas included) of every version other than the default, keyed by version; actions is the default’s. A step pinned to an older pieceVersion is described by its entry here — GET /api/pieces/{id}/actions/{actionId}?version= answers one.

{key}array of objects

Each key’s value.

triggersByVersionobject

Trigger ids each version declares, keyed by version.

{key}array of strings

Each key’s value.

Response · 200 OK, `view=index`: one line per app

dataarray of objects

view=index: one line per app.

idstring

The value a step stores in pieceId.

namestring

Human-facing name.

descriptionstring

One-line description, truncated at 140 characters (the full text is on the app itself).

categorystring

Grouping label, e.g. Data, Logic, Triggers, Communication, HTTP.

versionstring

The version a NEW step is pinned to — the default, not necessarily the newest.

versionsarray of strings

Every version the fleet can run, oldest first.

actionIdsarray of strings

Action ids of the DEFAULT version — the values a step stores in actionId.

triggerIdsarray of strings

Trigger ids of the default version. A definition’s trigger stores its id in a field called actionId. Absent when it has none, as actionIds is.

needsConnectionboolean

True when the app declares auth: a step using it will fail at run time without a connection. Absent when false.