--- title: "Get a project's installation of a connector" method: GET path: "/v1/projects/{project}/connectors/{key}/installation" tags: ["Connectors"] --- # Get a project's installation of a connector `GET /v1/projects/{project}/connectors/{key}/installation` ## Request - Base URL: `https://api.subscriby.net` - URL: `https://api.subscriby.net/v1/projects/{project}/connectors/{key}/installation` - Auth: HTTP bearer The project's installation of that connector in the live role, in whatever state, in the shape the installations list describes. ```bash curl https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/connectors/example/installation \ -H "Authorization: Bearer $SUBSCRIBY_TOKEN" ``` ## Path parameters - `project` string, uuid, required - `key` string, required ## Response `200` 200 with the installation. - object - `data` ConnectorInstallationResource, required: One connector installation of a project: its state and health, the platform's own account for it, and the timestamps of its life. Credentials and settings are never serialised. - `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. On this endpoint: `RESOURCE_NOT_FOUND`: with `reason: unknown_connector` when the key names no connector at all, so a client can tell a typo from a connector that is not set up here. `CONNECTOR_NOT_INSTALLED`: when the connector exists but the project does not run it. - `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)