---
title: "Get connector instance"
method: GET
path: "/connectors/{connectorId}"
tags: ["Connector Instances"]
---

# Get connector instance

`GET /connectors/{connectorId}`

## Request

- Base URL: `https://app.pipeshub.com/api/v1`
- URL: `https://app.pipeshub.com/api/v1/connectors/{connectorId}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `/api/v1/oauth2/authorize`
    - Client credentials
    - Token URL: `/api/v1/oauth2/token` scopes: `connector:read`

Retrieve a specific connector instance by ID, together with the setup
form of its connector type (<code>config</code>).<br><br>
<b>Who can read an instance:</b><br>
<ul>
<li>Team scope: the creator and org admins. Other members get
<code>404</code>, although the lists show them the instance.</li>
<li>Personal scope: the creator only. An admin gets <code>404</code>.</li>
</ul>
The ID of a knowledge base is accepted too: a knowledge base is stored
as a connector instance of type <code>KB</code>.

## Path parameters

- `connectorId` string, required

## Response `200`

Connector instance

- object
  - `success` boolean, required
  - `connector` ConnectorInstance, required: A connector instance: its type's registry entry plus the instance's own state.
    - `_key` string: Connector instance ID
    - `name` string: Instance name
    - `type` string: Connector type
    - `appGroup` string: Product family the connector belongs to
    - `supportedAuthTypes` ConnectorAuthType[]: Authentication methods the connector type supports
    - `appDescription` string
    - `appCategories` string[]
    - `iconPath` string: Path of the connector icon
    - `supportsRealtime` boolean
    - `supportsSync` boolean
    - `supportsAgent` boolean
    - `documentationLinks` ConnectorDocumentationLink[]
      - `title` string: Link text
      - `url` string: Link target
      - `type` string: Free-form link category set by the connector, for example `setup`, `pipeshub`, `api` or `docs`.
    - `isAdminAccessRequired` boolean
    - `personalConnectorType` string, nullable: For a team connector type, its personal counterpart, if any
    - `connectorInfo` string, nullable: Guidance shown before setup
    - `authType` string, nullable: Authentication method chosen when the instance was created, one of the type's `supportedAuthTypes`.
    - `scope` 'team' | 'personal': Scope determines visibility and access control for connectors:<br> <ul> <li><code>team</code> - Available to all users in the organization (admin-only creation)</li> <li><code>personal</code> - Private to the creating user only</li> </ul>
    - `isActive` boolean: Sync is on
    - `isAgentActive` boolean: Agents may use this connector
    - `isConfigured` boolean: Sync settings are saved; sync can be enabled
    - `isAuthenticated` boolean: OAuth sign-in has completed
    - `isLocked` boolean: A sync or deletion holds the connector
    - `status` string, nullable: Lifecycle status, for example SYNCING or DELETING
    - `pendingFullSync` boolean
    - `desktopOnline` boolean
    - `ownerDeviceId` string, nullable: Local FS only. The desktop device that owns this connector
    - `ownerDeviceName` string, nullable: Local FS only. Display name of the desktop device that owns this connector
    - `createdBy` string, nullable
    - `updatedBy` string, nullable: Null for an instance nobody has updated, for example the personal KB connector
    - `createdAtTimestamp` integer, nullable: Epoch milliseconds
    - `updatedAtTimestamp` integer, nullable: Epoch milliseconds
    - `lastSyncStartedAtTimestamp` integer, nullable: Epoch ms when the last sync run started; absent before the first run
    - `lastSyncFinishedAtTimestamp` integer, nullable: Epoch ms when the last sync run ended, however it ended; absent until a run ends
    - `lastSyncOutcome` 'succeeded' | 'failed' | 'stopped' | 'skipped', nullable: How the last sync run ended
    - `lastSyncSummary` object, nullable: What the last run did, in the connector's own terms. For a Web connector: pagesSaved (written this run), pagesStored (kept after it, which Maximum pages caps), pagesVisited, failed, failedByStatus, robotsSkipped, noindexSkipped, skippedMaxPages, deferred, pruned, sitemapUrls, stopReason (max_pages, time_limit, stalled, rate_limited or null) and resumed.
    - `actionItems` object[]: What the connector's admin has to do, shown as an action-needed badge on the instance card. Written by the connector at the end of each sync and when its auth settings are saved; empty when nothing is needed.
      - `code` string, required: Identifies the item for the connector, e.g. certificate_sign_in
      - `severity` 'warning' | 'error', required
      - `title` string, required
      - `message` string, required
      - `action` 'authenticate', nullable: Where in the connector panel it is done; authenticate opens the Authenticate tab
      - `docsUrl` string, uri, nullable: The setup steps for it, on the docs site
    - `config` ConnectorSchema: Configuration form for a connector type: the auth fields per auth type, the sync strategies and settings, and the sync and indexing filters.
      - `iconPath` string
      - `supportsRealtime` boolean
      - `supportsSync` boolean
      - `supportsAgent` boolean
      - `hideConnector` boolean: Whether the type is hidden from the registry listing
      - `permissionModel` 'RECORD_LEVEL' | 'APP_LEVEL': How records of this connector get their per-user visibility: `RECORD_LEVEL` (per-record permissions from the source) or `APP_LEVEL` (everyone who can reach the connector sees every record).
      - `isAdminAccessRequired` boolean
      - `personalConnectorType` string, nullable
      - `supportsConnectionCheck` boolean: Whether POST /connectors/registry/{connectorType}/test-connection works for this type
      - `documentationLinks` ConnectorDocumentationLink[]
        - `title` string: Link text
        - `url` string: Link target
        - `type` string: Free-form link category set by the connector, for example `setup`, `pipeshub`, `api` or `docs`.
      - `auth` object: Authentication form
        - `supportedAuthTypes` ConnectorAuthType[]
        - `schemas` object: Auth form per auth type, keyed by ConnectorAuthType
        - `values` object: Default values, keyed by field name
        - `customFields` unknown[]
          - unknown
        - `customValues` object
        - `conditionalDisplay` object: Rules that show a field only when another field has a given value, keyed by the field they apply to
        - `authorizeUrl` string: Instance reads only
        - `tokenUrl` string: Instance reads only
        - `oauthConfigs` object: Instance reads only: provider endpoints per auth type
      - `sync` object: Sync options
        - `supportedStrategies` string[]
        - `selectedStrategy` 'MANUAL' | 'SCHEDULED' | 'WEBHOOK': Strategy preselected in the form
        - `webhookConfig` object
          - `supported` boolean
          - `webhookUrl` string
          - `events` string[]
          - `verificationToken` string
          - `secretKey` string
        - `scheduledConfig` object
          - `intervalMinutes` integer
          - `cronExpression` string
          - `timezone` string
          - `startTime` integer
          - `nextTime` integer
          - `endTime` integer
          - `maxRepetitions` integer
          - `repetitionCount` integer
        - `realtimeConfig` object
          - `supported` boolean
          - `connectionType` string
        - `customFields` ConnectorSyncCustomField[]
          - `name` string
          - `displayName` string
          - `description` string
          - `fieldType` string
          - `required` boolean
          - `defaultValue` unknown
          - `validation` object
          - `isSecret` boolean
          - `nonEditable` boolean
          - `options` string[]
        - `customValues` object
        - `values` object
      - `filters` object: Filters the connector offers
        - `sync` ConnectorFilterSection
          - `schema` object
            - `fields` ConnectorFilterField[]
              - …
          - `values` object
        - `indexing` ConnectorFilterSection
          - `schema` object
            - `fields` ConnectorFilterField[]
              - …
          - `values` object

## Other responses

- `400`: Invalid request: `connectorId` is not 1 to 64 letters, digits, underscores or hyphens (`VALIDATION_ERROR`, "Connector ID must be 1-64 chars of letters, digits, underscore, or hyphen"). Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
- `401`: Missing or invalid credentials
- `403`: The token lacks a required scope, or the caller may not use this connector
- `404`: Not found, or the caller has no access
- `500`: Internal server error. A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.

## Changes

- **2026-10-28** `dbb5e203b445`: 4 breaking, 2 warning, 16 info
  - the response property `connector/authType` became nullable for the status `200`
  - the response property `connector/createdAtTimestamp` became nullable for the status `200`
  - the response property `connector/createdBy` became nullable for the status `200`
  - the response property `connector/updatedAtTimestamp` became nullable for the status `200`
  - …18 more
- **2026-10-26** `fc76aa045994`: 6 warning
  - added the new `ENTRA_ID` enum value to the `connector/authType` response property for the response status `200`
  - added the new `ENTRA_ID` enum value to the `connector/config/auth/supportedAuthTypes/items/` response property for the response status `200`
  - added the new `ENTRA_ID` enum value to the `connector/supportedAuthTypes/items/` response property for the response status `200`
  - added the new `IAM_ROLE` enum value to the `connector/authType` response property for the response status `200`
  - …2 more
- **2026-10-21** `a90ab79f26a1`: 4 info
  - added the optional property `connector/lastSyncFinishedAtTimestamp` to the response with the `200` status
  - added the optional property `connector/lastSyncOutcome` to the response with the `200` status
  - added the optional property `connector/lastSyncStartedAtTimestamp` to the response with the `200` status
  - added the optional property `connector/lastSyncSummary` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/changes/connectors/:connectorId/get.md)

---

[API](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api.md) - [All operations](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/revisions/dbb5e203b445?raw)