### install_connector response example

Source: https://docs.subscriby.net/mcp/v1/tools/connectors

Example response from install_connector. The installation is pending with no credentials yet; the creator connects it from the dashboard. Installing an already-installed connector changes nothing and returns the existing installation.

```json
{
  "data": {
    "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
    "connector": "discord",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "scope": "project",
    "role": "live",
    "state": "pending",
    "state_reason": null,
    "state_detail": null,
    "creator_actionable": false,
    "operational": false,
    "external_id": null,
    "display_name": null,
    "handle": null,
    "avatar_url": null,
    "health_checked_at": null,
    "connected_at": null,
    "verified_at": null,
    "revoked_at": null,
    "disconnected_at": null,
    "uninstalled_at": null,
    "created_at": "2026-09-12T10:05:00+00:00"
  },
  "meta": {}
}
```

--------------------------------

### Connector installation response example

Source: https://docs.subscriby.net/api/v1/reference/connectors

Example response body for the connector installations endpoint. Shows a connected connector with messaging and access control capabilities, health check timestamps, and null fields for optional values.

```json
{
  "data": [
    {
      "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
      "connector": "example",
      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
      "scope": "project",
      "role": "live",
      "state": "connected",
      "state_reason": null,
      "state_detail": null,
      "creator_actionable": false,
      "operational": true,
      "external_id": "7123456789",
      "display_name": "Research Bot",
      "handle": "research_bot",
      "avatar_url": null,
      "health_checked_at": "2026-09-12T06:00:00Z",
      "doctor_ran_at": "2026-09-12T06:00:00Z",
      "doctor_healthy": true,
      "connected_at": "2026-04-21T09:15:00Z",
      "verified_at": "2026-09-12T06:00:00Z",
      "revoked_at": null,
      "disconnected_at": null,
      "uninstalled_at": null,
      "created_at": "2026-04-21T09:15:00Z",
      "capabilities": {
        "messaging": {
          "enabled": true,
          "toggleable": true
        },
        "access_control": {
          "enabled": true,
          "toggleable": false
        }
      },
      "sales_paused": false,
      "outage": null
    }
  ]
}
```

--------------------------------

### begin(InstallationRequest)

Source: https://docs.subscriby.net/sdk/v1/ports/installation-lifecycle

Called when the creator submits the install form. Returns an InstallationDraft to start the connection conversation.

```APIDOC
## begin(InstallationRequest)

### Description
Called when the creator submits the install form (dashboard, `POST …/installation` for first-party clients). Returns an `InstallationDraft` to start the connection conversation.

### Method
begin

### Parameters
- **request** (InstallationRequest) - Required - The installation request submitted by the creator.

### Returns
- **InstallationDraft** - The draft installation object.
```

--------------------------------

### Uninstall preview response example

Source: https://docs.subscriby.net/api/v1/reference/connectors

Example response body for the uninstall preview endpoint. Shows the structure with installation details, resources, live grants, emptied plans, subscription counts, and options.

```json
{
  "data": {
    "installation": {
      "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
      "connector": "example",
      "state": "connected",
      "operational": true
    },
    "connector": "example",
    "resources": [
      {
        "id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6",
        "title": "Members Lounge",
        "kind": "example:role",
        "active": true
      }
    ],
    "live_grants": 41,
    "emptied_plans": [
      {
        "id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
        "name": "Lounge Monthly",
        "active": true,
        "recurring": true
      }
    ],
    "recurring_subscriptions": 17,
    "one_time_subscriptions": 3,
    "affected_subscription_ids": [
      "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4"
    ],
    "upcoming_windows": 0,
    "open_support_threads": 2,
    "member_identities": 44,
    "empties_plans": true,
    "options": {
      "unpublish_emptied_plans": true,
      "cancel_recurring_subscriptions": true
    }
  }
}
```

--------------------------------

### restore_connector_access response example

Source: https://docs.subscriby.net/mcp/v1/tools/connectors

Example response from the restore_connector_access tool. Shows the installation state, the list of resources with their restored flags, and counts of reactivated resources, still-detached resources, and reissued subscriptions.

```json
{
  "data": {
    "installation": {
      "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
      "connector": "telegram",
      "state": "connected"
    },
    "connector": "telegram",
    "resources": [
      {
        "resource_id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6",
        "title": "Premium Channel",
        "restored": true
      },
      {
        "resource_id": "0d4a7e19-5c2b-4f83-9a61-2e8b7c3d5f10",
        "title": "Archive Group",
        "restored": false
      }
    ],
    "resources_reactivated": 1,
    "resources_still_detached": 1,
    "subscriptions_reissued": 14
  },
  "meta": {}
}
```

--------------------------------

### list_connector_installations response example

Source: https://docs.subscriby.net/mcp/v1/tools/connectors

Example response from list_connector_installations. Shows a single live Telegram connector installation with state 'connected' and operational true. Rows come oldest first.

```json
{
  "data": [
    {
      "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
      "connector": "telegram",
      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
      "scope": "project",
      "role": "live",
      "state": "connected",
      "state_reason": null,
      "state_detail": null,
      "creator_actionable": false,
      "operational": true,
      "external_id": "7123456789",
      "display_name": "Research Bot",
      "handle": "research_bot",
      "avatar_url": null,
      "health_checked_at": "2026-09-12T06:00:00Z",
      "connected_at": "2026-04-21T09:15:00Z",
      "verified_at": "2026-09-12T06:00:00Z",
      "revoked_at": null,
      "disconnected_at": null,
      "uninstalled_at": null,
      "created_at": "2026-04-21T09:15:00Z"
    }
  ],
  "meta": { "total": 1 }
}
```

--------------------------------

### uninstall_connector response example

Source: https://docs.subscriby.net/mcp/v1/tools/connectors

Example response from the uninstall_connector tool. Shows the installation state set to disconnected with uninstalled_at, plus counts of revoked grants, detached resources, unpublished plans, cancelled subscriptions, and notified members.

```json
{
  "data": {
    "installation": {
      "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
      "connector": "discord",
      "state": "disconnected",
      "operational": false,
      "uninstalled_at": "2026-09-12T11:30:00+00:00"
    },
    "connector": "discord",
    "grants_revoked": 41,
    "resources_detached": 2,
    "plans_unpublished": 1,
    "subscriptions_cancelled": 17,
    "members_notified": 17
  },
  "meta": {}
}
```

--------------------------------

### GET /v1/projects/{project}/connectors/{key}/installation

Source: https://docs.subscriby.net/api/v1/reference

Gets a project's installation of a specific connector. This endpoint provides details about the installation of a connector in a project.

```APIDOC
## GET /v1/projects/{project}/connectors/{key}/installation

### Description
Get a project's installation of a connector.

### Method
GET

### Endpoint
/v1/projects/{project}/connectors/{key}/installation
```

--------------------------------

### InstallationSummary and startLink, publicUrl, platformInstallation methods

Source: https://docs.subscriby.net/sdk/v1/tutorial/03-installation

Returns an InstallationSummary with the bot user's id and name from the /me response, falling back to 'Agora bot'. startLink builds a 'new message' URL with an optional draft payload. publicUrl returns the forum URL. platformInstallation returns null.

```php
return new InstallationSummary(
    externalId: (string) $me->json('data.id', $installation->externalId),
    displayName: (string) $me->json('data.name', 'Agora bot'),
    handle: $installation->handle,
    storageRef: $installation->storageRef,
);
}
```

```php
public function startLink(InstallationRef $installation, ?string $payload = null): ?string
{
    $forum = Forum::query()->find($installation->storageRef);

    if ($forum === null) {
        return null;
    }

    return rtrim($forum->forum_url, '/').'/messages/new?to='.$installation->externalId.($payload === null ? '' : '&draft='.rawurlencode($payload));
}
```

```php
public function publicUrl(InstallationRef $installation): ?string
{
    return Forum::query()->find($installation->storageRef)?->forum_url;
}
```

```php
public function platformInstallation(): ?InstallationRef
{
    return null;
}
```

--------------------------------

### GET /v1/connectors

Source: https://docs.subscriby.net/api/v1/errors

Lists available connectors. Only connectors with `installable` set to `true` can be installed.

```APIDOC
## GET /v1/connectors

### Description
Lists available connectors. Only connectors with `installable` set to `true` can be installed.

### Method
GET

### Endpoint
/v1/connectors

### Response
#### Success Response (200)
- **connectors** (array) - List of connector objects.
  - **key** (string) - Connector key.
  - **installable** (boolean) - Whether the connector can be installed.

#### Response Example
{
  "connectors": [
    {
      "key": "slack",
      "installable": true
    }
  ]
}
```

--------------------------------

### run_connector_doctor response example

Source: https://docs.subscriby.net/mcp/v1/tools/connectors

Example response from run_connector_doctor. Shows the installation check and per-resource findings with severity, state, message, and fix URL. The report is kept on the installation and raises connector.doctor_completed only when findings differ from the previous run.

```json
{
  "data": {
    "installation_id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
    "connector": "telegram",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "ran_at": "2026-09-12T10:07:00Z",
    "healthy": false,
    "critical": 1,
    "warnings": 0,
    "findings": [
      {
        "key": "installation",
        "kind": "installation",
        "severity": "ok",
        "severity_label": "OK",
        "subject": "Research Bot",
        "state": "connected",
        "message": "The connector still answers for this installation.",
        "creator_actionable": false,
        "fix_url": null,
        "resource_id": null
      },
      {
        "key": "resource:b73c5f21-9d80-4a6e-8215-4f70ce13a9d6",
        "kind": "resource",
        "severity": "critical",
        "severity_label": "Critical",
        "subject": "Premium Channel",
        "state": "not_member",
        "message": "The bot was removed from this channel.",
        "creator_actionable": true,
        "fix_url": "https://app.subscriby.net/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/resources",
        "resource_id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6"
      }
    ]
  },
  "meta": {}
}
```

--------------------------------

### Example 200 response for get role

Source: https://docs.subscriby.net/api/v1/reference/roles

Example JSON response for a successful request. Contains the role resource with its permissions array.

```json
{
  "data": {
    "id": "d05e1a7c-7c46-4f29-b613-8ae407c9d251",
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "code": "manager",
    "name": "Manager",
    "description": "Manage plans, resources, and subscribers",
    "owner_user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "permissions": [
      "project:view",
      "project:update",
      "project-user:view-any",
      "project-user:update"
    ],
    "created_at": "2026-05-18T10:05:00Z"
  }
}
```

--------------------------------

### get_connector_uninstall_preview response example

Source: https://docs.subscriby.net/mcp/v1/tools/connectors

Example response from get_connector_uninstall_preview. It lists the connector's resources, counts live_grants, recurring_subscriptions, one_time_subscriptions, upcoming_windows, open_support_threads, and member_identities, names emptied_plans, and includes affected_subscription_ids and the two opt-in options with their defaults.

```json
{
  "data": {
    "installation": {
      "id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
      "connector": "discord",
      "state": "connected",
      "operational": true
    },
    "connector": "discord",
    "resources": [
      {
        "id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6",
        "title": "Members Lounge",
        "type": null,
        "kind": "discord:role",
        "active": true
      }
    ],
    "live_grants": 41,
    "emptied_plans": [
      {
        "id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
        "name": "Lounge Monthly",
        "active": true,
        "recurring": true
      }
    ],
    "recurring_subscriptions": 17,
    "one_time_subscriptions": 3,
    "affected_subscription_ids": ["5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4"],
    "upcoming_windows": 0,
    "open_support_threads": 2,
    "member_identities": 44,
    "empties_plans": true,
    "options": {
      "unpublish_emptied_plans": true,
      "cancel_recurring_subscriptions": true
    }
  },
  "meta": {}
}
```

--------------------------------

### get_deep_link response example

Source: https://docs.subscriby.net/mcp/v1/tools/connectors

Example response from the get_deep_link tool. Shows the project_id, bot_url, start_payload, and the resulting deep_link with the start parameter.

```json
{
  "data": {
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "bot_url": "https://t.me/research_bot",
    "start_payload": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "deep_link": "https://t.me/research_bot?start=a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  }
}
```

--------------------------------

### cURL: Get connector installation (sample request)

Source: https://docs.subscriby.net/api/v1/reference/connectors

Sample request from the 'Call it from your code' section, using a placeholder project ID and connector key. Requires a bearer token.

```bash
curl -X GET "https://api.subscriby.net/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/connectors/string/installation" \
  -H "Authorization: Bearer "
```

--------------------------------

### cURL: Get caller's account (explicit GET)

Source: https://docs.subscriby.net/api/v1/reference/me

Alternative cURL example using an explicit GET method and an empty bearer token placeholder. Replace the token with a valid personal access token.

```bash
curl -X GET "https://api.subscriby.net/v1/me" \
  -H "Authorization: Bearer "
```

--------------------------------

### platformInstallation()

Source: https://docs.subscriby.net/sdk/v1/ports/installation-lifecycle

Called for creator handshakes and sign-up on a `platform`-scope connector, and recovery facets that act as Subscriby. Returns an optional InstallationRef.

```APIDOC
## platformInstallation()

### Description
Called for creator handshakes and sign-up on a `platform`-scope connector, and recovery facets that act as Subscriby. Returns an optional `InstallationRef`.

### Method
platformInstallation

### Parameters
None.

### Returns
- **?InstallationRef** - The installation reference, or null if not applicable.
```

--------------------------------

### GET /v1/projects/{project}/connectors

Source: https://docs.subscriby.net/api/v1/errors

Lists connectors installed on a project.

```APIDOC
## GET /v1/projects/{project}/connectors

### Description
Lists connectors installed on a project.

### Method
GET

### Endpoint
/v1/projects/{project}/connectors

### Parameters
#### Path Parameters
- **project** (string) - Required - The project identifier.

### Response
#### Success Response (200)
- **connectors** (array) - List of installed connector keys.

#### Response Example
{
  "connectors": ["slack"]
}
```

--------------------------------

### signupEntry method signature

Source: https://docs.subscriby.net/sdk/v1/ports/registers-creators

Returns the link that starts the sign-up conversation for the given platform installation. Usually uses InstallationLifecycle::startLink($platform). An empty string leaves the connector out of the sign-up options.

```php
public function signupEntry(InstallationRef $platform): string;
```

--------------------------------

### cURL: Get connector installation

Source: https://docs.subscriby.net/api/v1/reference/connectors

Fetches the installation of a connector for a project using a bearer token. Requires the project-connector:view ability; otherwise returns 403.

```bash
curl https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/connectors/example/installation \
  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"
```

--------------------------------

### get_connector return example

Source: https://docs.subscriby.net/mcp/v1/tools/connectors

Example JSON response from get_connector for the Telegram connector, showing the full card structure including manifest, capabilities, and install fields.

```json
{
  "data": {
    "key": "telegram",
    "name": "Telegram",
    "vendor": "Subscriby",
    "version": "1.0.0",
    "status": "available",
    "status_label": "Available Now",
    "installable": true,
    "official": true,
    "badges": [{ "key": "official", "label": "Official" }],
    "category": "messaging",
    "tagline": "Sell access to Telegram channels, groups and supergroups through your own bot.",
    "links": {
      "documentation": "https://docs.subscriby.net/connectors/telegram",
      "support": "mailto:support@subscriby.net",
      "privacy": "https://telegram.org/privacy",
      "terms": "https://telegram.org/tos",
      "homepage": "https://telegram.org"
    },
    "added_at": "2025-04-21",
    "install_mode": "paste_credential",
    "scopes": ["project", "platform"],
    "resource_kinds": [
      {
        "kind": "channel",
        "label": "Channel",
        "portal_label": "Channel",
        "icon": "megaphone",
        "grant_mode": "bearer_link",
        "supports_early_admission_hold": true
      }
    ],
    "capabilities": [
      "messaging",
      "access_control",
      "management_surface",
      "recovery_probes"
    ],
    "messaging": {
      "max_length": 4096,
      "buttons_per_row": 8,
      "max_buttons": 100,
      "callback_data_bytes": 64,
      "supports_underline": true,
      "supports_spoiler": true,
      "supports_files": true
    },
    "pacing": {
      "min_interval_microseconds": 35000,
      "burst": 30,
      "per_recipient_interval_microseconds": 1000000
    },
    "management_commands": ["project_create", "plan_manage"],
    "missing_commands": ["creator_tasks"],
    "recovery": {
      "probes": true,
      "standby_installations": true,
      "resource_standby": false,
      "mirror": false,
      "identity_relink": false
    },
    "install_fields": [
      {
        "name": "token",
        "type": "secret",
        "label": "Bot token",
        "help": "Paste the token @BotFather gave you.",
        "required": true,
        "rules": ["string"],
        "options": [],
        "value": null,
        "steps": [],
        "links": {}
      }
    ],
    "settings_fields": []
  },
  "meta": {}
}
```

--------------------------------

### 200 response body for Get an incident

Source: https://docs.subscriby.net/api/v1/reference/disaster-recovery

Example 200 response body for the Get an incident endpoint. Shows a resources incident with reason chat_not_found and a null resolved_at.

```json
{
  "data": {
    "id": "6f1e9b27-4c3a-4d58-9e02-b7a1c5d38f64",
    "kind": "resources",
    "kind_label": "Channels and Groups",
    "status": "open",
    "status_label": "Open",
    "connector": "telegram",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "project_name": "Research Premium",
    "resource_id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6",
    "resource_title": "Signals",
    "reason": "chat_not_found",
    "reason_label": "Channel not found",
    "reason_explanation": "**Most likely cause:** the platform deleted or banned the channel. Replace it with a new one.",
    "detected_at": "2026-09-12T03:19:04Z",
    "resolved_at": null,
    "resolved_by_operation_id": null
  }
}
```

--------------------------------

### describe(installation, credentials)

Source: https://docs.subscriby.net/sdk/v1/ports/installation-lifecycle

Called when the core refreshes the installation's name, handle, and picture (after connect, on the doctor). Returns an InstallationSummary.

```APIDOC
## describe(installation, credentials)

### Description
Called when the core refreshes the installation's name, handle, and picture (after connect, on the doctor). Returns an `InstallationSummary`.

### Method
describe

### Parameters
- **installation** (Installation) - Required - The installation to describe.
- **credentials** (Credentials) - Required - The credentials for the installation.

### Returns
- **InstallationSummary** - The summary with updated name, handle, and picture.
```

--------------------------------

### Example payload for connector.status_changed

Source: https://docs.subscriby.net/webhooks/v1/events/connector

Example JSON body posted to your endpoint for the connector.status_changed event. The body is a JSON envelope with the event data, including the previous and current state of the installation.

```json
{
  "id": "evt_01HX...",
  "type": "connector.status_changed",
  "created_at": "2026-09-12T06:00:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "connector": "telegram",
    "installation_id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "previous_state": "connected",
    "state": "degraded",
    "reason": "connector_api_unauthorized"
  }
}
```

--------------------------------

### get_project response example

Source: https://docs.subscriby.net/mcp/v1/tools/project

Example response from the get_project tool, showing a project object with its counts (plans, resources, subscribers, payment_methods) and timestamps.

```json
{
  "data": {
    "id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "name": "Research Premium",
    "handle": "research-premium",
    "description": "Weekly deep-dive research notes.",
    "banner_url": "https://static.subscriby.net/...",
    "photo_url": "https://static.subscriby.net/...",
    "active": true,
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "counts": {
      "plans": 3,
      "resources": 2,
      "subscribers": 241,
      "payment_methods": 2
    },
    "created_at": "2026-05-18T10:05:00Z",
    "updated_at": "2026-05-18T10:05:00Z"
  }
}
```