Connectors
The catalog, the workspace’s connections, HTTP API connectors, testing and disconnecting. Keys go in once and are never returned. 6 routes, from the API’s own OpenAPI document.
6 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| GET | /v1/connector-catalog | Every connector, its auth scheme, actions, regions and status |
| GET | /v1/workspaces/{ws}/connections | Connections with health and the apps that use them (members) |
| DELETE | /v1/workspaces/{ws}/connections/{id} | Disconnect: delete the sealed secret; apps that use it stop calling (admins) |
| PUT | /v1/workspaces/{ws}/connections/{id}/http | Change an HTTP API connection; a new host needs the secret again (admins) |
| POST | /v1/workspaces/{ws}/connections/{id}/test | Test a connection with one harmless call through the gate (admins) |
| POST | /v1/workspaces/{ws}/connectors/http | Add an HTTP API connection: base URL, auth style, write-only secret (admins) |
Reference#
GET /v1/connector-catalog#
Every connector, its auth scheme, actions, regions and status.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
readscope. - Who: signed in
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
entries | object[] | yes | |
entries[].id | string | yes | |
entries[].connectorId | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … or null | yes | |
entries[].name | string | yes | at least 1 characters |
entries[].monogram | string | yes | 1 to 3 characters |
entries[].category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
entries[].group | "messaging" · "email" · "crm" · "commerce" · "data" · "developer" | yes | |
entries[].summary | string | yes | at least 1 characters |
entries[].auth | "api_key" · "bot_token" · "oauth2" · "service_account" · "basic" · "webhook_url" · "none" | yes | |
entries[].fields | object[] | yes | |
entries[].actions | object[] | yes | |
entries[].triggers | object[] | yes | |
entries[].regions | "global" · "kz"[] | yes | |
entries[].status | "available" · "beta" · "preview" · "needs-oauth-app" · "planned" | yes | |
entries[].docsUrl | string (uri) | yes | |
entries[].guide | string or null | yes | |
entries[].httpPreset | object or null | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/workspaces/{ws}/connections#
Connections with health and the apps that use them (members).
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
readscope. - Who: member
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
ws | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
workspaceId | string | yes | at least 1 characters |
canManage | boolean | yes | |
allowed | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · …[] | yes | |
connections | object[] | yes | |
connections[].id | string | yes | at least 1 characters |
connections[].connectorId | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … | yes | |
connections[].displayName | string | yes | at least 1 characters |
connections[].status | "connected" · "expired" · "error" · "disconnected" | yes | |
connections[].connectedAt | string (date-time) or null | yes | |
connections[].secret | "write-only" · "none" | yes | |
connections[].keyId | string or null | yes | |
connections[].http | object or null | yes | |
connections[].serviceAccount | object or null | ||
connections[].usedBy | object[] | yes | |
connections[].health | object | yes | |
oauthReady | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · …[] | default |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
DELETE /v1/workspaces/{ws}/connections/{id}#
Disconnect: delete the sealed secret; apps that use it stop calling (admins).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: admin
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
ws | path | string | yes | 1 to 128 characters |
id | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
ok | true | yes | |
affectedApps | string[] | yes | |
connection | object | yes | |
connection.id | string | yes | at least 1 characters |
connection.connectorId | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … | yes | |
connection.displayName | string | yes | at least 1 characters |
connection.status | "connected" · "expired" · "error" · "disconnected" | yes | |
connection.connectedAt | string (date-time) or null | yes | |
connection.secret | "write-only" · "none" | yes | |
connection.keyId | string or null | yes | |
connection.http | object or null | yes | |
connection.serviceAccount | object or null | ||
connection.usedBy | object[] | yes | |
connection.health | object | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
PUT /v1/workspaces/{ws}/connections/{id}/http#
Change an HTTP API connection; a new host needs the secret again (admins).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: admin
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
ws | path | string | yes | 1 to 128 characters |
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
displayName | string | yes | 1 to 60 characters |
baseUrl | string | yes | 9 to 700 characters |
auth | object | yes | |
methods | "GET" · "POST" · "PUT" · "PATCH" · "DELETE"[] | yes | up to 5 items |
pathPrefix | string | up to 512 characters. default "/" | |
headers | object[] | up to 8 items. default | |
headers[].name | string | yes | |
headers[].value | string | yes | 1 to 512 characters |
testPath | string or null | up to 512 characters. default null | |
testable | boolean | default true | |
preset | string or null | default null | |
secret | string | 1 to 4096 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | at least 1 characters |
connectorId | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … | yes | |
displayName | string | yes | at least 1 characters |
status | "connected" · "expired" · "error" · "disconnected" | yes | |
connectedAt | string (date-time) or null | yes | |
secret | "write-only" · "none" | yes | |
keyId | string or null | yes | |
http | object or null | yes | |
http.baseUrl | string | yes | 9 to 700 characters |
http.host | string | yes | 3 to 100 characters |
http.auth | object | yes | |
http.methods | "GET" · "POST" · "PUT" · "PATCH" · "DELETE"[] | yes | up to 5 items |
http.pathPrefix | string | yes | up to 512 characters |
http.headers | object[] | yes | up to 8 items |
http.testPath | string or null | yes | up to 512 characters |
http.testable | boolean | ||
http.preset | string | ||
serviceAccount | object or null | ||
serviceAccount.email | string | yes | 3 to 254 characters |
usedBy | object[] | yes | |
usedBy[].appId | string | yes | at least 1 characters |
usedBy[].name | string | yes | at least 1 characters |
usedBy[].archetype | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes | |
usedBy[].category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
usedBy[].status | "draft" · "building" · "healthy" · "warning" · "failing" · "paused" | yes | |
health | object | yes | |
health.calls24h | integer | yes | at least 0 |
health.errors24h | integer | yes | at least 0 |
health.blocked24h | integer | yes | at least 0 |
health.lastCallAt | string (date-time) or null | yes |
…and 3 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/workspaces/{ws}/connections/{id}/test#
Test a connection with one harmless call through the gate (admins).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: admin
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
ws | path | string | yes | 1 to 128 characters |
id | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
ok | boolean or null | yes | |
checked | "gate" · "format" · "mock" | yes | |
status | integer or null | yes | 0 to 999 |
latencyMs | integer or null | yes | at least 0 |
reason | "auth_rejected" · "upstream_error" · "upstream_failed" · "dns_failed" · "private_address" · "secret_unavailable" · "not_connected" · "gate_unreachable" · … or null | yes | |
connection | object | yes | |
connection.id | string | yes | at least 1 characters |
connection.connectorId | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … | yes | |
connection.displayName | string | yes | at least 1 characters |
connection.status | "connected" · "expired" · "error" · "disconnected" | yes | |
connection.connectedAt | string (date-time) or null | yes | |
connection.secret | "write-only" · "none" | yes | |
connection.keyId | string or null | yes | |
connection.http | object or null | yes | |
connection.serviceAccount | object or null | ||
connection.usedBy | object[] | yes | |
connection.health | object | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/workspaces/{ws}/connectors/http#
Add an HTTP API connection: base URL, auth style, write-only secret (admins).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who: admin
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
ws | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
displayName | string | yes | 1 to 60 characters |
baseUrl | string | yes | 9 to 700 characters |
auth | object | yes | |
methods | "GET" · "POST" · "PUT" · "PATCH" · "DELETE"[] | yes | up to 5 items |
pathPrefix | string | up to 512 characters. default "/" | |
headers | object[] | up to 8 items. default | |
headers[].name | string | yes | |
headers[].value | string | yes | 1 to 512 characters |
testPath | string or null | up to 512 characters. default null | |
testable | boolean | default true | |
preset | string or null | default null | |
secret | string | 1 to 4096 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | at least 1 characters |
connectorId | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … | yes | |
displayName | string | yes | at least 1 characters |
status | "connected" · "expired" · "error" · "disconnected" | yes | |
connectedAt | string (date-time) or null | yes | |
secret | "write-only" · "none" | yes | |
keyId | string or null | yes | |
http | object or null | yes | |
http.baseUrl | string | yes | 9 to 700 characters |
http.host | string | yes | 3 to 100 characters |
http.auth | object | yes | |
http.methods | "GET" · "POST" · "PUT" · "PATCH" · "DELETE"[] | yes | up to 5 items |
http.pathPrefix | string | yes | up to 512 characters |
http.headers | object[] | yes | up to 8 items |
http.testPath | string or null | yes | up to 512 characters |
http.testable | boolean | ||
http.preset | string | ||
serviceAccount | object or null | ||
serviceAccount.email | string | yes | 3 to 254 characters |
usedBy | object[] | yes | |
usedBy[].appId | string | yes | at least 1 characters |
usedBy[].name | string | yes | at least 1 characters |
usedBy[].archetype | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes | |
usedBy[].category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
usedBy[].status | "draft" · "building" · "healthy" · "warning" · "failing" · "paused" | yes | |
health | object | yes | |
health.calls24h | integer | yes | at least 0 |
health.errors24h | integer | yes | at least 0 |
health.blocked24h | integer | yes | at least 0 |
health.lastCallAt | string (date-time) or null | yes |
…and 3 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).