--- title: "List a project's installations" method: GET path: "/v1/projects/{project}/connectors" tags: ["Connectors"] --- # List a project's installations `GET /v1/projects/{project}/connectors` ## Request - Base URL: `https://api.subscriby.net` - URL: `https://api.subscriby.net/v1/projects/{project}/connectors` - Auth: HTTP bearer Every installation the project holds, live and standby, oldest first. ```bash curl https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/connectors \ -H "Authorization: Bearer $SUBSCRIBY_TOKEN" ``` `role` is `live` for the one that acts and `standby` for the spare the Disaster Recovery Program keeps; `state` is `pending`, `connected`, `degraded` (the health probe found something wrong, `state_reason` and `state_detail` say what, `creator_actionable` whether the creator can fix it), `revoked` (the platform withdrew it) or `disconnected` (the creator did); `operational` is the one-word answer to "can it act right now?". `external_id`, `display_name`, `handle` and `avatar_url` are the platform's own account for the installation. Credentials and settings are never serialised. `sales_paused` and `outage` describe a connector outage: the platform refused this live installation outright (token revoked or regenerated, bot deleted). While `sales_paused` is `true`, `outage` carries the outage's `id`, the connector's `reason` code and `started_at`, and every plan that unlocks a place on this connector is refused at checkout with `422 VALIDATION_FAILED`; both go back to `false` and `null` when the installation answers again, is replaced or is uninstalled. [Connector outages](https://docs.subscriby.net/disaster-recovery/connector-outages) describes what members see and how they are compensated; [`connector.outage_opened`](https://docs.subscriby.net/webhooks/v1/events/connector/connector-outage-opened) and [`connector.outage_closed`](https://docs.subscriby.net/webhooks/v1/events/connector/connector-outage-closed) announce both ends. ## Path parameters - `project` string, uuid, required ## Response `200` Array of `ConnectorInstallationResource` - object - `data` ConnectorInstallationResource[], required: The items. - `id` string, required: The installation's id. - `connector` string, required: The connector's key. - `project_id` string, nullable, required: The project the installation belongs to; null for a platform-scope presence. - `scope` string, required: `project` for an installation a creator set up, `platform` for a presence Subscriby runs. - `role` string, required: `live` for the installation that acts, `standby` for the spare the Disaster Recovery Program keeps. - `state` string, required: `pending` (installed, nothing connected yet), `connected`, `degraded` (the health probe found something wrong), `revoked` (the platform withdrew it) or `disconnected` (the creator did). - `state_reason` string, nullable, required: The connector's reason code for a `degraded` or `revoked` state; null otherwise. - `state_detail` string, nullable, required: The connector's sentence about the state, in the creator's language; null when there is nothing to say. - `creator_actionable` boolean, required: Whether the creator can fix the current state themselves. - `operational` boolean, required: The one-word answer to "can it act right now?". - `external_id` string, nullable, required: The platform's own id for the installation's account, such as a bot id; null while pending. - `display_name` string, nullable, required: The platform's display name for the account; null while pending. - `handle` string, nullable, required: The platform's handle for the account, without a prefix; null while pending or where the platform has none. - `avatar_url` string, nullable, required: The account's avatar; null where none is known. - `health_checked_at` string, nullable, required: When the connector was last asked whether the installation still answers, ISO 8601. - `doctor_ran_at` string, nullable, required: When the doctor last ran on the installation, ISO 8601; null before the first run. - `doctor_healthy` boolean, nullable, required: Whether the last doctor report found every finding `ok`; null before the first run. - `connected_at` string, nullable, required: When the creator's credentials were bound, ISO 8601; null while pending. - `verified_at` string, nullable, required: When the installation last answered a probe, ISO 8601. - `revoked_at` string, nullable, required: When the platform withdrew the installation, ISO 8601; null unless revoked. - `disconnected_at` string, nullable, required: When the creator disconnected it, ISO 8601; null unless disconnected. - `uninstalled_at` string, nullable, required: When the connector was uninstalled from the project, ISO 8601; null while installed. - `created_at` string, nullable, required: When the installation was opened, ISO 8601. - `capabilities` object, required: Every capability the connector declares, keyed by capability, each with `enabled` (the project's switch for this installation) and `toggleable` (whether the switch can be turned off at all; `access_control`, `early_admission_hold`, `management_surface`, `portal_login` and `creator_registration` cannot). - `sales_paused` boolean, required: Whether a connector outage is open on this installation, refusing every checkout of a plan that unlocks a place on it. - `outage` object, nullable, required: The open outage while `sales_paused` is true, null otherwise. - `id` string, required: The outage's id. - `reason` string, required: The connector's reason code for the outage, such as a revoked or regenerated token. - `started_at` string, required: When the outage opened, ISO 8601. ## Other responses - `401`: `AUTHENTICATION_REQUIRED`: the request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an `sbt_test_` token on production). - `403`: `TOKEN_MISSING_ABILITY`: the token is valid but does not carry the ability this endpoint requires; `error.context.required_ability` names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers `FORBIDDEN`, `TEAM_TIER_REQUIRED` or `CONNECTOR_TIER_REQUIRED` with the same status, and says so in its own description. - `404`: `RESOURCE_NOT_FOUND`: an id in the path names nothing the token can see. `TENANT_MISMATCH`: the project sits outside the token's `scope:project:` allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred. - `429`: `RATE_LIMITED`: the token has spent its 300 requests a minute or 10,000 an hour; `Retry-After` says when the next one is accepted. --- [API](https://skmtc.dev/memberpass/apis/subscriby-rest-api.md) · [All operations](https://skmtc.dev/memberpass/apis/subscriby-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/memberpass/apis/subscriby-rest-api/revisions/59c4df91d764?raw)