---
title: "Create connector instance"
method: POST
path: "/connectors"
tags: ["Connector Instances"]
---

# Create connector instance

`POST /connectors`

## Request

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

Create a connector instance from a registry type.<br><br>
<b>Body:</b><br>
Put the auth fields the registry schema lists for <code>authType</code> in <code>config.auth</code>,
flat, and the connector's own sync settings in <code>config.sync</code>. A connector that needs no
OAuth sign-in is configured on creation.<br><br>
<b>OAuth:</b><br>
An admin may send the OAuth app's credentials in <code>config.auth</code>: the app is saved and
linked. Anyone may send <code>config.auth.oauthConfigId</code> to use a saved app; non-admins must.
Send <code>baseUrl</code>: the provider redirects to <code>{baseUrl}/{redirectUri}</code>.<br><br>
<b>Scope Permissions:</b><br>
<ul>
<li><code>team</code> scope requires admin privileges</li>
<li><code>personal</code> scope available to all users</li>
</ul>
<b>Next Steps After Creation:</b><br>
<ol>
<li>OAuth only: <code>GET /{id}/oauth/authorize</code>, then <code>GET /oauth/callback</code></li>
<li>Optionally set sync and filters via <code>PUT /{id}/config/filters-sync</code></li>
<li>Turn sync on via <code>POST /{id}/toggle</code></li>
</ol>

## Request body

- CreateConnectorRequest
  - `connectorType` string, required: `type` from the registry
  - `instanceName` string, required
  - `scope` 'team' | 'personal', required: 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>
  - `authType` 'OAUTH' | 'OAUTH_ADMIN_CONSENT' | 'API_TOKEN' | 'BEARER_TOKEN' | 'BASIC_AUTH' | 'ACCESS_KEY' | 'IAM_ROLE' | 'ACCOUNT_KEY' | 'CONNECTION_STRING' | 'ENTRA_ID' | 'CUSTOM' | 'NONE': How a connector instance signs in to its source. Each connector type supports a subset; see `supportedAuthTypes` in the registry.
  - `config` object
    - `auth` ConnectorAuthConfig: Auth settings, flat: send each field listed under `auth.schemas.<authType>.fields` in GET /connectors/registry/{connectorType}/schema by its `name`. For OAuth, an admin may send the OAuth app's credentials here (the app is saved and linked), or anyone may send `oauthConfigId` to use a saved app.
      - `oauthConfigId` string: A saved OAuth app (GET /oauth/{connectorType})
      - `oauthInstanceName` string: Name for the OAuth app saved from inline credentials
      - `connectorScope` string: Scope of the instance, as the frontend sends it; the server fills it in when absent
      - `authType` string: On `PUT /connectors/{connectorId}/config` only: must equal the instance's `authType`, which cannot be changed (`400` otherwise).
    - `sync` ConnectorSyncConfig: Sync strategy plus connector-specific sync settings, flat: send each field listed under `sync.customFields` in the registry schema by its `name`.
      - `selectedStrategy` 'MANUAL' | 'SCHEDULED' | 'WEBHOOK'
      - `scheduledConfig` object
        - `intervalMinutes` integer
        - `timezone` string
        - `startTime` integer: Epoch milliseconds
        - `startDateTime` unknown
      - `webhookConfig` object
        - `webhookUrl` string
        - `events` string[]
    - `filters` ConnectorFiltersConfig
      - `sync` object
        - `values` object
      - `indexing` object
        - `values` object
  - `baseUrl` string: Origin of the page the OAuth provider redirects back to. The redirect URI is `{baseUrl}/{redirectUri}`; defaults to the PipesHub frontend URL.

## Response `200`

Connector instance created. It is not syncing yet.

- object
  - `success` boolean, required
  - `connector` ConnectorCreated, required: Summary of a connector instance that was just created
    - `connectorId` string, required: ID of the new instance
    - `connectorType` string, required: Connector type the instance was created from
    - `instanceName` string, required: Instance name, trimmed
    - `created` boolean
    - `scope` 'team' | 'personal', required: 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>
    - `createdBy` string: User ID who created the instance
    - `isAuthenticated` boolean: Always `false` on creation
    - `isConfigured` boolean: Whether initial configuration was saved with the request
  - `message` string

## Other responses

- `400`: Invalid request: a parameter or the body failed validation, or `config.auth` is present but neither an object nor null ("Auth configuration must be an object.")
- `401`: Missing or invalid credentials
- `403`: Team scope needs an admin; non-admins cannot send OAuth app credentials; or a missing scope
- `404`: Unknown connector type or OAuth app
- `409`: An OAuth app with that name already exists
- `500`: Internal error, for example when the JSON body is not an object 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`: 1 breaking, 4 info
  - added the pattern `\S` to the request property `instanceName`
  - added the new optional request property `config/auth/authType`
  - added the new optional request property `config/auth/connectorScope`
  - added the new optional request property `config/sync/scheduledConfig/startDateTime`
  - …1 more
- **2026-10-26** `fc76aa045994`: 2 info
  - added the new `ENTRA_ID` enum value to the request property `authType/allOf[#/components/schemas/ConnectorAuthType]/`
  - added the new `IAM_ROLE` enum value to the request property `authType/allOf[#/components/schemas/ConnectorAuthType]/`
- **2026-10-15** `a44792e4f0e6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/changes/connectors/post.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)