> ## Documentation Index > Fetch the complete documentation index at: https://pipedream.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create connector > Add a connector Requires the `connectors:write` scope. ## OpenAPI ````yaml /conduit/openapi/api.yaml post /conduit.v1.ConduitService/CreateConnector openapi: 3.1.0 info: title: Conduit API version: v1 description: | Machine-to-machine API for Conduit workspaces. Authenticate a workspace API client with OAuth 2.0 client credentials at `/oauth/token`, then call these methods with the resulting bearer token. Read-only methods are documented as `GET`, with their JSON request encoded in the `message` query parameter. Mutating methods use `POST` with a JSON body. The server also accepts `POST` for reads. See the API guide for auth, scopes, and error handling. servers: - url: https://conduit.example.com description: Your Conduit instance — replace with your CONDUIT_BASE_URL security: - bearerAuth: [] tags: - name: connectors x-group: Connectors description: Create and manage connectors and the workspace's Pipedream configuration. - name: policies-and-groups x-group: Policies & groups description: Allow policies, groups, group membership, and effective-access debugging. - name: members x-group: Members description: Read the workspace's member roster. - name: single-sign-on x-group: Single sign-on description: Read sanitized workspace identity-provider configuration. - name: provisioning x-group: Provisioning description: Read sanitized SCIM metadata, provisioning rules, and resource mappings. - name: workspace-settings x-group: Workspace settings description: Change general workspace settings. - name: audit-log x-group: Audit log description: Read the workspace audit log. paths: /conduit.v1.ConduitService/CreateConnector: post: tags: - connectors summary: Create connector description: |- Add a connector Requires the `connectors:write` scope. operationId: CreateConnector parameters: - name: Connect-Protocol-Version in: header required: true schema: $ref: '#/components/schemas/connect-protocol-version' - name: Connect-Timeout-Ms in: header schema: $ref: '#/components/schemas/connect-timeout-header' requestBody: content: application/json: schema: $ref: '#/components/schemas/conduit.v1.CreateConnectorRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/conduit.v1.CreateConnectorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/connect.error' components: schemas: connect-protocol-version: type: number title: Connect-Protocol-Version enum: - 1 description: Define the version of the Connect protocol const: 1 connect-timeout-header: type: number title: Connect-Timeout-Ms description: Define the timeout, in ms conduit.v1.CreateConnectorRequest: type: object properties: connector: $ref: '#/components/schemas/conduit.v1.ConnectorConfig' title: connector organizationId: type: string title: organization_id description: empty = caller's active org title: CreateConnectorRequest additionalProperties: false conduit.v1.CreateConnectorResponse: type: object properties: connector: $ref: '#/components/schemas/conduit.v1.ConnectorConfig' title: connector title: CreateConnectorResponse additionalProperties: false connect.error: type: object properties: code: type: string examples: - not_found enum: - canceled - unknown - invalid_argument - deadline_exceeded - not_found - already_exists - permission_denied - resource_exhausted - failed_precondition - aborted - out_of_range - unimplemented - internal - unavailable - data_loss - unauthenticated description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: $ref: '#/components/schemas/connect.error_details.Any' description: >- A list of messages that carry the error details. There is no limit on the number of messages. title: Connect Error additionalProperties: true description: >- Error type returned by Connect: https://connectrpc.com/docs/go/errors/#http-representation conduit.v1.ConnectorConfig: type: object properties: name: type: string title: name type: type: string title: type enabled: type: boolean title: enabled url: type: string title: url auth: $ref: '#/components/schemas/conduit.v1.McpAuthConfig' title: auth stdio: $ref: '#/components/schemas/conduit.v1.StdioConfig' title: stdio description: type: string title: description description: >- Human-readable description. For custom servers added from a server.json this is extracted from the manifest; empty otherwise. serverJson: type: string title: server_json description: >- The raw server.json (modelcontextprotocol.io manifest) this server was registered from, stored verbatim. Empty for catalog/bare-URL servers. authMethod: type: string title: auth_method description: |- How the upstream is authenticated, independent of credential scope: "none" — no auth header "token" — a static bearer/header credential (shaped per auth.type) "oauth" — OAuth against the upstream's own AS; the grant is auth.type: authorization-code by default, or the client-credentials grant (a workspace machine credential, no per-user connect) when auth.type = "client-credentials" Credential *scope* is not stored: a workspace credential exists when the row carries one (auth.token/headers for token, a sentinel OAuth grant for oauth); otherwise each member supplies their own. See allow_user_override. allowUserOverride: type: - boolean - 'null' title: allow_user_override description: >- When a workspace-wide credential is set, may a member instead connect/supply their own? false = everyone uses the workspace credential (locked). Applies to both methods that can hold one: a member's own API token over the shared one (token), or their own connected account over the workspace grant (the authorization-code OAuth grant). Meaningless — and cleared server-side — for "none" and the client-credentials grant, which have no per-member credential. Presence-aware: omitting it on UpdateConnector leaves the stored value alone. No connector form carries a control for it, so an edit that isn't about credential scope (a metadata change, the enable toggle, an update_connector call) must not clobber it. kind: type: string title: kind description: |- Connector kind — what kind of tool source this row resolves to: "" / "mcp" — an upstream MCP server, tools proxied 1:1 (type carries the transport: url/sse/stdio) "graphql" — a GraphQL endpoint exposed as a single .execute tool "openapi" — an OpenAPI spec exposed as one tool per operation graphql/openapi rows use type="url"; kind is what the registry branches on. iconUrl: type: string title: icon_url description: |- Display icon URL for the connector. Auto-detected at registration (favicon / manifest / spec info) and admin-editable; empty falls back to a generic icon in the UI. spec: type: string title: spec description: >- Generic spec blob for non-MCP kinds: GraphQL introspection JSON or the OpenAPI document (YAML normalized to JSON). Empty for MCP rows (which use server_json instead). specFetchedAt: type: string title: spec_fetched_at description: >- RFC3339 timestamp of the last successful introspection / spec fetch (empty = never). Server-stamped on fetch; the UI shows freshness and offers a refresh. Read-mostly — clients don't set it on create/update. displayName: type: string title: display_name description: >- Human-friendly display name shown in the connectors UI (e.g. "Pipedream API"). `name` stays the slug used to prefix tools; display_name is purely presentational. Empty falls back to `name` in the UI. configFields: type: array items: $ref: '#/components/schemas/conduit.v1.ConnectorConfigField' title: config_fields description: >- Admin-declared config fields the connector injects, additive to whatever auth_method provides (auth wins on a key collision). One concept, keyed on `type`: a remote connector injects each field as an HTTP request header, a local (stdio) connector as an environment variable for the spawned process. Declarations are rendering metadata (not secret) and are echoed on read; VALUES are write-only everywhere: workspace-scoped values ride auth.headers (per-key merge, see McpAuthConfig), user-scoped values are supplied by each member via SetUpstreamToken. id: type: string title: id description: |- Response-only canonical id used by policies and connector APIs: "local:" for stdio connectors, "mcp:" for every remote kind. oauthRedirectUri: type: string title: oauth_redirect_uri description: >- Response-only: the redirect URI to register with the connector's OAuth authorization server, `/upstream/callback/{key}`. Conduit registers it itself for a client it registers dynamically; an admin-supplied client must have it registered. oauthCallbackKey: type: string title: oauth_callback_key description: |- Request-only: the key naming the connector's redirect URI (`/upstream/callback/{key}`) — 32 lowercase hex characters, chosen at random by the caller — so the URI can be registered with an authorization server before the connector is saved. Used when a connector is created; ignored otherwise. Optional: the server picks one when omitted. A key already in use is refused. title: ConnectorConfig additionalProperties: false description: |- ConnectorConfig is a workspace tool source of some kind (MCP / GraphQL / OpenAPI), keyed by `kind`. Despite the historical field set (type, stdio, server_json — MCP-specific), this describes any connector; non-MCP kinds leave the MCP-only fields empty. connect.error_details.Any: type: object properties: type: type: string description: >- A URL that acts as a globally unique identifier for the type of the serialized message. For example: `type.googleapis.com/google.rpc.ErrorInfo`. This is used to determine the schema of the data in the `value` field and is the discriminator for the `debug` field. value: type: string format: binary description: >- The Protobuf message, serialized as bytes and base64-encoded. The specific message type is identified by the `type` field. debug: oneOf: - type: object title: Any additionalProperties: true description: Detailed error information. discriminator: propertyName: type title: Debug description: >- Deserialized error detail payload. The 'type' field indicates the schema. This field is for easier debugging and should not be relied upon for application logic. additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message, with an additional debug field for ConnectRPC error details. conduit.v1.McpAuthConfig: type: object properties: type: type: string title: type description: >- type: "" (none) | "bearer" | "header" | "token-exchange" (ID-JAG via the workspace SSO IdP) | "oauth" (per-user authorization-code flow against the upstream's own authorization server) | "client-credentials" (workspace-wide machine credential: Conduit exchanges the client id + secret at the token endpoint itself; no authorization endpoint, no per-user connect flow). token: type: string title: token description: >- token, headers, and oauth_client_secret are write-only: requests set them, responses never include them (the *_set booleans report presence). On update, leaving them empty keeps the stored values; set clear_credentials to drop the stored token/headers instead (e.g. switching a token connector to per-member credentials). headers: type: object title: headers additionalProperties: type: string title: value audience: type: string title: audience scopes: type: string title: scopes idpId: type: string title: idp_id description: identity provider used for token-exchange auth oauthClientId: type: string title: oauth_client_id description: >- For type="oauth": an admin-supplied OAuth client when the upstream doesn't support dynamic client registration. Left empty to use DCR. oauthClientSecret: type: string title: oauth_client_secret oauthAuthorizeEndpoint: type: string title: oauth_authorize_endpoint description: >- For type="oauth" on connectors that can't be discovered via .well-known (GraphQL/OpenAPI and any non-MCP HTTP API): the OAuth provider's authorization + token endpoints, supplied manually. For MCP connectors these are discovered automatically and left empty here. Echoed back on read so the form shows what's configured. type="client-credentials" needs only the token endpoint (there is no authorization leg), on any connector kind. oauthTokenEndpoint: type: string title: oauth_token_endpoint tokenSet: type: boolean title: token_set description: Response-only presence indicators for the write-only fields above. headersSet: type: boolean title: headers_set oauthClientSecretSet: type: boolean title: oauth_client_secret_set clearCredentials: type: boolean title: clear_credentials description: 'Request-only: delete the stored workspace token/headers.' headerKeys: type: array items: type: string title: header_keys description: >- Response-only: the stored workspace header names (values stay hidden), so forms can prefill key rows without re-entering values. clearHeaders: type: boolean title: clear_headers description: |- Request-only: delete all stored workspace headers, leaving the token alone. When config_fields are declared, `headers` merges per key on update: submitted keys replace stored ones, an empty submitted value means "keep the stored value for this key", and omitting headers entirely keeps the stored map (OTelExporter semantics). title: McpAuthConfig additionalProperties: false conduit.v1.StdioConfig: type: object properties: command: type: string title: command args: type: array items: type: string title: args title: StdioConfig additionalProperties: false conduit.v1.ConnectorConfigField: type: object properties: key: type: string title: key description: >- The field name: an HTTP header name (RFC 9110 token, case-insensitive) for a remote connector, or an environment variable name (case-sensitive) for a stdio connector. Unique per connector. Also the storage key for the field's value — renaming a key orphans stored values (they are never migrated). label: type: string title: label description: human-friendly name shown in forms description: type: string title: description description: optional help text (rendered as plain text) required: type: boolean title: required description: >- required: user-scoped — the member cannot use the connector's tools until they supply a value (drives the connect prompt); workspace-scoped — the connector cannot be saved without a stored or submitted value. secret: type: boolean title: secret description: >- secret controls input masking in the UI only. Values are write-only in the API regardless — a flag flip never discloses a stored value. scope: type: string title: scope description: >- "workspace" — the admin supplies one shared value in the connector editor; "user" — each member supplies their own on the connect page. title: ConnectorConfigField additionalProperties: false description: >- One declared config field for a connector — an HTTP header (remote) or an environment variable (stdio), per the connector's type. The declaration describes the field; where its value comes from is `scope`. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: opaque ````