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

URL: https://docs.qaldy.com/reference/api/connectors/

6 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[GET]] | [`/​v1/​connector-catalog`](#get-v1-connector-catalog) | Every connector, its auth scheme, actions, regions and status |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​connections`](#get-v1-workspaces-ws-connections) | Connections with health and the apps that use them (members) |
| [[DELETE]] | [`/​v1/​workspaces/​{ws}/​connections/​{id}`](#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`](#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`](#post-v1-workspaces-ws-connections-id-test) | Test a connection with one harmless call through the gate (admins) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​connectors/​http`](#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 `read` scope.
- **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](https://docs.qaldy.com/reference/api/#errors)).

### [[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 `read` scope.
- **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](https://docs.qaldy.com/reference/api/#errors)).

### [[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_only` for 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](https://docs.qaldy.com/reference/api/#errors)).

### [[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_only` for 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](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[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_only` for 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](https://docs.qaldy.com/reference/api/#errors)).

### [[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_only` for 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](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).