Get an app

GET/api/pieces/{id}

Returns one app with its actions and triggers.

Needs any API token. No permission is checked.

Parameters

Path

idRequired · string: The app’s id, as a step’s pieceId holds it: http, webhook, schedule.

Query

viewOptional · string: summary: no field schemas, just what you need to choose an action. Any other value returns the full app.

Read it

In the summary, each action lists fields, how many inputs it has, and discriminators: the fields its other fields depend on, most important first. Pass them to Get an action’s fields to narrow it.

actions describe the default version; a list that is empty is null in the full answer and [] in the summary. actionsByVersion and triggersByVersion list each version’s ids, for a step pinned to an older version.

Each action’s sideEffects says what running it does: pure, reads_external or writes_external. In the summary, needsConnection: true marks an app that takes a connection.

It sends no ETag.

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.

The connection it needs

The full answer has auth when the app takes a connection. auth.fields lists what to send as a connection’s config, by name; password fields are secrets. auth.required is true when a step can’t run without one.

An app whose auth has oauth2 signs in, such as Gmail. It holds the service’s authorizationUrl, tokenUrl and scopes. For those, start a sign-in rather than saving a secret. auth.type alone doesn’t say it: Gmail’s is custom.

Responses

200OK
The app, in full or as a summary.
403FORBIDDEN
The token may not do this.
404NOT_FOUND
No app with this id among those the workers run. An app this workspace may not use answers 404 too.
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
APP_ID="http"

curl "$GORUNNER/api/pieces/$APP_ID?view=summary" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"

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

const res = await fetch(
  `${GORUNNER}/api/pieces/` +
    `${APP_ID}?view=summary`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();

import os, requests

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

res = requests.get(
    f"{GORUNNER}/api/pieces/{APP_ID}",
    params={"view": "summary"},
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

Response · 200 OK, shortened

json

{
  "data": {
    "id": "http",
    "name": "HTTP Request",
    "description": "Send HTTP requests to any URL",
    "category": "HTTP",
    "version": "1.0.0",
    "versions": [
      "1.0.0"
    ],
    "actions": [
      {
        "id": "send_request",
        "name": "Send HTTP request",
        "description": "Send HTTP request",
        "sideEffects": "writes_external",
        "fields": 34,
        "discriminators": [
          {
            "field": "body_type",
            "type": "string",
            "values": [
              "none",
              "json",
              "raw",
              "form_data",
              "form_urlencoded"
            ]
          },
          {
            "field": "auth_type",
            "type": "string",
            "values": [
              "NONE",
              "BASIC",
              "BEARER_TOKEN",
              "…"
            ]
          },
          "…"
        ]
      }
    ],
    "triggers": []
  }
}

Every field

It takes no body.

Response · 200 OK, the whole app

dataobject

An app as the full catalog serves it, with every action and trigger schema inlined.

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, with view=summary

dataobject

GET /api/pieces/{id}?view=summary — every operation of one app with no schemas at all.

idstring

namestring

descriptionstring

categorystring

versionstring

versionsarray of strings

needsConnectionboolean

True when the app declares auth.

actionsarray of objects

idstring

namestring

descriptionstring

sideEffectsstring

Actions only; always absent for triggers.

One of pure, reads_external, writes_external.

fieldsinteger

How many input properties this operation declares — a one-field action versus a forty-field one, before fetching either.

discriminatorsarray of objects

The gate fields this operation’s inputs depend on, MOST FAR-REACHING FIRST. These are exactly the query parameters worth supplying to the operation-detail endpoint.

fieldstring

Property name — send it verbatim as a query parameter, e.g. ?auth_type=BASIC.

typestring

The field’s declared type (string, boolean, number). Query values are text and are coerced to this type.

valuesarray of strings

The field’s enum, when it declares one — the legal values for the query parameter.

triggersarray of objects

The same fields as data.actions above.

Get an app

Parameters

Path

Query

Read it

The connection it needs

Responses

Response · 200 OK, the whole app

Response · 200 OK, with view=summary

Panel