install_connector

Install a connector on a project — a pending installation with no credentials yet, which the creator connects from the dashboard.

Purpose

Mark a project as running a connector. Installing opens a pending installation, the row the Connectors tab shows until the creator connects it; connecting needs a credential typed by a person, so no tool does it. Installing a connector that is already installed changes nothing and returns the existing installation. The REST twin is POST /v1/projects/{project}/connectors/{key}.

Required ability

project-connector:create

Input schema

{
  "type": "object",
  "required": ["project_id", "connector"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "UUID of the project."
    },
    "connector": {
      "type": "string",
      "description": "The connector key, as list_connectors returns it; only an installable card can be installed."
    }
  }
}

Output shape

{
  "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": {}
}

Events emitted

connector.installed when a row is opened (or an uninstalled one brought back).

Example prompts

"Add Discord to Research Premium so I can connect it later."

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-connector:create.
RESOURCE_NOT_FOUND — the project is not visible to this token.
CONNECTOR_UNAVAILABLE — the key names no connector creators may install today (its card is not installable).
CONNECTOR_TIER_REQUIRED — a second distinct connector on the project, and the project owner's plan lacks multi_connector (Growth).

list_connectors — which cards are installable.
get_connector_installation — the row afterwards.
disconnect_connector — the reverse of connecting.
Connectors API

install_connector

On this page