Test a connection
POST/
Tests a saved connection against its service and records the result.
Needs an API token with the Write permission for connections (connection:write).
Parameters
Path
idRequired · UUIDThe connection’s ID.
Read it
success: true- The service accepted it.
statusbecomesactive. success: true,unverified: true- The app can’t be tested without a real step. Nothing was proven.
statusbecomesunverified. success: false- The service refused it (
error,cause).statusbecomeserror, orpendingbefore a first sign-in. success: false,noVerdict: true- No answer came back: no worker, the time ran out, or this installation doesn’t run the app (
reason). Nothing was learned.statusstays as it was.
unavailable: true means this installation doesn’t run the app. A test waits up to 30 seconds. It takes no body and no Idempotency-Key.
Responses
- 200OK
The result, even a failed one. Read
successandnoVerdict. idisn’t a UUID.- 403
FORBIDDENThe token lacks the Write permission for connections.
- 404
NOT_FOUNDNo connection with this ID in the token’s workspace.
The worker’s answer couldn’t be read.
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
CONNECTION_ID="your-connection-id"
URL="$GORUNNER/api/connections/$CONNECTION_ID/test"
curl -X POST "$URL" \
-H "Authorization: Bearer $GORUNNER_TOKEN"const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const CONNECTION_ID = process.env.CONNECTION_ID;
const res = await fetch(
`${GORUNNER}/api/connections/` +
`${CONNECTION_ID}/test`,
{
method: "POST",
headers: { Authorization: `Bearer ${TOKEN}` },
},
);
const { data } = await res.json();import os, requests
GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
CONNECTION_ID = os.environ["CONNECTION_ID"]
res = requests.post(
f"{GORUNNER}/api/connections/{CONNECTION_ID}/"
f"test",
headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]Response · 200 OK
{
"data": {
"success": true,
"message": "Connected as gorunner-bot",
"account": "gorunner-bot",
"status": "active"
}
}Every field
It takes no body.
Response · 200 OK
dataobjectThe verdict from a connection test. Delivered inside an HTTP 200 in every case, INCLUDING failure and "no worker available" — branch on
success/unverified, never on the status code.successbooleanTrue when the test did not fail. Note that
success: truetogether withunverified: truemeans nothing was actually proven.unverifiedbooleanPresent and true when the app cannot verify credentials without running a real step. The connection row is set to
unverifiedand the credentials are checked on first real use. Deliberately not reported as a pass.messagestringThe app’s own words on success, or the explanation of an unverified result.
errorstringPresent when
successis false. Either the provider’s refusal (the row becomeserror, orpendingfor an unauthorized OAuth2 connection), or the fixed text "No worker is available to run this right now..." — in which case NOTHING was learned about the credentials and the stored status is deliberately left unchanged.causestringWhy a failed test failed.
expired: the refresh was refused during the test and the connection staysexpired.One of
refused,expired,server,forbidden,other.noVerdictbooleanPresent and true when no verdict came back (no worker, the time ran out, an app this build does not serve): nothing was learned about the credentials and the stored status is unchanged.
reasonstringWhy, with
noVerdict.One of
no_worker,timeout,not_served.accountstringWho the credential signs in as, when the test learned it.
statusstringThe status recorded.
unavailablebooleanThis installation does not serve the app: nothing could test it, and nothing was recorded.