GoRunner docs
Search or askSearch⌘K

Test sign-in details before saving

Since v2026.10.8

POST/api/connections/test

Tests sign-in details before you save them. Nothing is stored.

Needs an API token with the Write permission for connections (connection:write).

Parameters

Body

pieceIdOptional · string

The app, for a new connection. Needed without connectionId.

connectionIdOptional · UUID

For a change: a saved connection of the same app. Fields you leave blank keep its saved values.

configOptional · object

The details to test.

Read it

success: true with account, who it signed in as. Or success: false with error, in the service’s words, and cause: refused, expired, server, forbidden or other.

noVerdict: true means no answer came back: no worker, the time ran out, or this installation doesn’t run the app (reason). Only then should a form offer to save untested.

Responses

  • 200OK

    The result, whatever it was. Read success and noVerdict.

  • No app, an unknown app, an app other than the connection’s, or details that aren’t valid.

  • The token lacks the Write permission for connections.

  • The partner manages this connection through its own API, so it can’t be changed here.

  • connectionId isn’t in this workspace.

  • The change moves where the connection points (a host, server, port, database, address or connection string) and left a saved secret blank. details.fields names the secrets to send again. Nothing changed.

  • The saved connection 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 · 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 Write for connections

curl -X POST "$GORUNNER/api/connections/test" \
  -H "Authorization: Bearer $GORUNNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceId": "email",
    "config": {
      "host": "smtp.office365.com",
      "port": "587",
      "email": "warehouse@bakery.example",
      "password": "…"
    }
  }'

Response · 200 OK, refused

json
{
  "data": {
    "success": false,
    "error": "smtp auth: 535 5.7.3 Authentication unsuccessful",
    "cause": "refused"
  }
}
Every field

Body

pieceIdOptional · string

The app, for an add. Required without connectionId.

connectionIdOptional · UUID

For a change: the draft is laid over this connection’s stored config (a blank field keeps the saved value). Same app, same workspace.

configOptional · object

Response · 200 OK

dataobject
successboolean
messagestring
accountstring
errorstring
causestring

One of refused, expired, server, forbidden, other.

noVerdictboolean

No verdict came back (no worker, the time ran out, an app this build does not serve): the only case a form offers to save without a test.

reasonstring

One of no_worker, timeout, not_served.