Skip to main content
Use the Connector Manager API to create, configure, sign in, turn on and delete connectors, and to manage the OAuth apps that connectors sign in with. The Node.js API checks the caller, validates each request and forwards it to the Python connectors service, which does the work.

Base URLs

  • Connector endpoints are under /api/v1/connectors.
  • OAuth app endpoints are under /api/v1/oauth.
  • Health endpoints are under /api/v1/health.

Connector types and connector instances

A connector type is a kind of source PipesHub can sync from, such as Confluence, Drive or OneDrive. The registry lists the types and the setup form each one needs. A connector instance (usually just “connector”) is one configured copy of a type. An organization can have several instances of one type. Each instance has its own ID, the connectorId, which the instance endpoints take in the path. A connectorId is 1 to 64 letters, digits, underscores or hyphens; anything else is refused with 400. Each instance has a scope:
  • team: set up by an admin for the whole organization. Every member sees team connectors in the connector lists.
  • personal: set up by one person for their own data. Only that person sees it.
Responses report an instance’s state in these fields:

Authentication

Every endpoint except the health checks needs a bearer token:
The token can be a session token from signing in, an OAuth access token or a personal access token. OAuth and personal access tokens must also carry one of the scopes listed for the endpoint, such as connector:read, or the request is refused with 403. Session tokens aren’t checked for scopes.

Who can do what

Access depends on the caller’s role in the organization. A caller without permission gets 403. A connector the caller may not see at all is reported as 404, so the API doesn’t confirm that it exists. A personal connector’s configuration carries its creator’s credentials, so only the creator can read it. When beta connectors are turned off in the platform settings, the registry leaves out beta connector types and requests for a beta connector get 403. Enterprise and business accounts can’t create a team-scope beta connector either (403).

Locked connectors

A connector is locked while a sync or another operation runs. Until it finishes, requests that change the connector (configuration, name, filters, toggle, reindex, resync and delete) are refused with 409 Conflict. The message says what is running, for example “A sync is already in progress. Please wait and try again.” To end a sync early, call POST /api/v1/connectors/:connectorId/sync/stop. It works while the connector is locked, and it also clears a lock or syncing status left behind when no sync is running.

API Endpoints

Endpoint titles give paths relative to /api/v1/connectors, unless they start with /api/v1/.
List the connector types that can be set up. Beta types are left out when beta connectors are turned off.
Endpoint: GET /api/v1/connectors/registryScope: connector:readQuery Parameters:
Get the form definition for one connector type: its sign-in fields for each supported auth type, its sync settings and its filters.
Endpoint: GET /api/v1/connectors/registry/:connectorType/schemaScope: connector:readPath Parameters:
  • connectorType: Connector type name, for example Confluence (string, required)
Try the auth settings from a connector type’s setup form without creating or changing a connector. Only types whose schema has supportsConnectionCheck: true can be tested.
Endpoint: POST /api/v1/connectors/registry/:connectorType/test-connectionScope: connector:writePath Parameters:
  • connectorType: Connector type name, for example PostgreSQL (string, required)
Request Body Parameters:
With connectorId, the caller must be allowed to change that connector’s configuration. Every field you send is tested as sent, •••••••• included, so leave a stored secret out to test with its stored value.
Get the public IP addresses PipesHub’s connectors use to reach other systems, so you can allow them in a database’s or API’s firewall.
Endpoint: GET /api/v1/connectors/network/egress-ipsScope: connector:read
List the connectors the caller can see: their own personal connectors and the organization’s team connectors.
Endpoint: GET /api/v1/connectorsScope: connector:readQuery Parameters:
Create a connector instance. It starts out not authenticated and with sync off.
Endpoint: POST /api/v1/connectorsScope: connector:writeRequest Body Parameters:
OAuth connectors: an admin either picks an existing OAuth app with config.auth.oauthConfigId or passes OAuth credentials in config.auth, which creates an OAuth app. A member must pick an existing OAuth app: sending OAuth credentials is refused with 403, and picking no app with 400.
List the caller’s visible connectors that have sync turned on (/active) or off (/inactive). These two endpoints take no query parameters and don’t paginate.
Endpoints: GET /api/v1/connectors/active, GET /api/v1/connectors/inactiveScope: connector:read
List the caller’s visible connectors whose settings have been saved.
Endpoint: GET /api/v1/connectors/configuredScope: connector:readQuery Parameters: scope (defaults to team), page, limit and search, as for GET /.
List the caller’s visible connectors that have agent use turned on.
Endpoint: GET /api/v1/connectors/agents/activeScope: connector:readQuery Parameters: scope (defaults to team), page, limit and search, as for GET /.
Get one connector with its state and the type’s display metadata.
Endpoint: GET /api/v1/connectors/:connectorIdScope: connector:readPath Parameters:
  • connectorId: Connector instance ID (string, required)
Endpoint: PUT /api/v1/connectors/:connectorId/nameScope: connector:write
Permanently delete a connector and everything synced from it. The request returns once the deletion starts, and the deletion runs in the background. Deleting a connector lists what is removed.
Endpoint: DELETE /api/v1/connectors/:connectorIdScope: connector:deleteAccess Control: the connector’s creator or an admin, for either scope.
A connector’s configuration has three sections: auth (how it signs in), sync (when it syncs) and filters (what it syncs and indexes). It is stored encrypted. Reading it leaves out the credentials and oauth sections, which hold the sign-in tokens.Secrets in auth never come back in plain text. A secret is any field the connector type’s setup form marks secret, such as an API token, password or client secret, and the service-account private key of an older Google Workspace connector. A secret that is set comes back as ••••••••, on a read and in the answer to every save. A secret that isn’t set comes back empty.When you save, a secret sent as •••••••• or left out keeps the stored value, and a new value replaces it. So you can send back the configuration you read without retyping its secrets.
Endpoint: GET /api/v1/connectors/:connectorId/configScope: connector:readAccess Control: as for GET /:connectorId. For a personal connector, only its creator; anyone else, an admin included, gets 404.
Endpoint: PUT /api/v1/connectors/:connectorId/configScope: connector:writeRequest Body Parameters:
Turn sync off first: the connector must not be active. Changing the credentials in auth signs the connector out (isAuthenticated becomes false), and its auth type can’t be changed after creation. A secret sent back as •••••••• keeps the stored value and doesn’t count as a credential change, so sending the configuration back unchanged keeps the connector signed in. Choosing a different OAuth app with oauthConfigId does count, and signs the connector out.On an OAuth connector, a new client secret sent here changes only the connector’s own copy. Sign-in uses the linked OAuth app’s secret; to rotate that, update the OAuth app with PUT /api/v1/oauth/:connectorType/:configId.
Save only the auth section. The connector is then marked configured but not authenticated, and sync is turned off, so sign it in and turn it on again.
Endpoint: PUT /api/v1/connectors/:connectorId/config/authScope: connector:write
To keep a stored secret, send it as •••••••• or leave it out. A new token, password or other secret replaces the stored one. The mask itself is never written to the connector or to its OAuth app.On an OAuth connector (authType OAUTH), a new client secret sent here isn’t kept in the connector’s auth:
  • From an admin, it updates the OAuth app named in oauthConfigId, so every connector on that app signs in with the new secret. Without oauthConfigId, a new OAuth app is created and the connector is linked to it.
  • From anyone else, such as the creator of a personal OAuth connector, it is dropped. The call still answers 200 and signs the connector out, and the OAuth app’s secret stays as it was.
Save the sync section, the filters section, or both. Each filters.sync and filters.indexing object you send replaces the stored one. Changing the sync filters makes the next sync a full sync.
Endpoint: PUT /api/v1/connectors/:connectorId/config/filters-syncScope: connector:write
The filter names and operators depend on the connector type; read them from its schema.
Get the provider’s authorization URL for a connector that signs in with OAuth. Send the user’s browser there.
Endpoint: GET /api/v1/connectors/:connectorId/oauth/authorizeScope: connector:writeQuery Parameters:
Exchange the code the provider returned for tokens and mark the connector authenticated. The web app calls this from its callback page with the query parameters the provider added.
Endpoint: GET /api/v1/connectors/oauth/callbackScope: connector:writeQuery Parameters:A request without code or state is refused with 400 (“Code and state are required”) in the standard error shape. That includes a sign-in the user declined at the provider, which sends error and state but no code.
Get the filter options the connector type offers, read with the connector’s own credentials where needed.
Endpoint: GET /api/v1/connectors/:connectorId/filtersScope: connector:read
Page through the options for one filter field whose options are fetched from the source, such as the spaces of a Confluence site.
Endpoint: GET /api/v1/connectors/:connectorId/filters/:filterKey/optionsScope: connector:readQuery Parameters:
Saving selections here doesn’t change what the connector syncs or indexes. To change that, use PUT /:connectorId/config/filters-sync.
Endpoint: POST /api/v1/connectors/:connectorId/filtersScope: connector:write
The selections are stored under the connector’s filters.values, but syncs read filters.sync.values and filters.indexing.values.
Switch sync, or agent use, to the opposite of its current state. Turning sync on or off also updates the connector’s sync schedule.
Endpoint: POST /api/v1/connectors/:connectorId/toggleScope: connector:syncRequest Body Parameters:
Before sync is turned on, the connector must be configured, and an OAuth connector must be signed in. Before agent use is turned on, the type must support agents and the connector must be configured.
Start a sync of a connector that has sync turned on.
Endpoint: POST /api/v1/connectors/:connectorId/resyncScope: connector:write or kb:writeRequest Body Parameters:
Stop a connector’s running sync. The call returns at once and the sync halts shortly after. It works while the connector is locked.If no sync is running but the connector still shows a syncing status or is locked, for example after a crash, the call resets it to idle and unlocked, as long as PipesHub can tell that no sync is running anywhere.
Endpoint: POST /api/v1/connectors/:connectorId/sync/stopScope: connector:syncNo request body.
Reindex a connector’s records from their stored content. A knowledge base is also a connector instance, so this reindexes knowledge bases too.
Endpoint: POST /api/v1/connectors/:connectorId/reindexScope: connector:sync or kb:writeThe body is optional. Send statusFilters to reindex only the records with those indexing statuses:
For a knowledge base, the caller needs a role on it (owner, writer or reader).
Get record counts by indexing status for a connector.
Endpoint: GET /api/v1/connectors/:connectorId/statsScope: connector:read or kb:readAccess Control: for a personal connector, its creator only; for a team connector, an admin or its creator; for a knowledge base, its owners, writers and readers.
Admin-only jobs for the whole organization. cleanup drops and recreates the shared vector collection. reindex embeds every connector’s records again from stored content, without dropping the collection. Both work only when vector store rebuild is turned on in the platform settings.
Endpoints: POST /api/v1/connectors/vector-store/cleanup, POST /api/v1/connectors/vector-store/reindexScope: connector:syncAccess Control: admins only. A member is refused with 403 (“You need admin access to do this. Ask an admin in your organisation.”).
Agents and the web app use these read-only endpoints.
  • GET /api/v1/connectors/record/:recordId/content - A record’s full parsed content and metadata. Scope connector:read.
  • GET /api/v1/connectors/navigate - Walk the knowledge graph from a connector to its record groups, records and children. Query parameters: nodeId (a record ID, URL or issue key), page, limit (50 to 200), depth (1 to 3), nodeTypes, and createdAfter, createdBefore, modifiedAfter, modifiedBefore. Scope kb:read or connector:read.
  • GET /api/v1/connectors/record/lookup - Turn URLs, issue keys or external IDs into record IDs. Query parameters: identifiers (1 to 10, repeatable) and optionally connectorName. Scope kb:read or connector:read.
An OAuth app holds the client ID, client secret and other OAuth settings for one connector type, so that several connectors can sign in through the same app. Admins create and manage OAuth apps; members pick one when they create an OAuth connector. These endpoints are under /api/v1/oauth.
List the connector and action types that have an OAuth registration, with the fields an OAuth app for them needs.
Endpoint: GET /api/v1/oauth/registryScope: connector:readQuery Parameters: page (defaults to 1), limit (1 to 200, defaults to 20) and search.
Endpoint: GET /api/v1/oauth/registry/:connectorTypeScope: connector:read
List the organization’s OAuth apps across all types, newest first.
Endpoint: GET /api/v1/oauthScope: connector:readQuery Parameters: page, limit (1 to 200) and search (matches the app name, group, description, type and categories).
Endpoint: GET /api/v1/oauth/:connectorTypeScope: connector:readQuery Parameters: page, limit (1 to 200) and search. A scope parameter (team or personal) is accepted; the open-source edition ignores it.
Endpoint: POST /api/v1/oauth/:connectorTypeScope: connector:writeAccess Control: admins only (403 for members).Request Body Parameters:
Endpoint: GET /api/v1/oauth/:connectorType/:configIdScope: connector:read
Endpoint: PUT /api/v1/oauth/:connectorType/:configIdScope: connector:writeAccess Control: admins only (403 for members).Send oauthInstanceName, config, or both, and optionally baseUrl.
Endpoint: DELETE /api/v1/oauth/:connectorType/:configIdScope: connector:deleteAccess Control: admins only (403 for members).
These endpoints are deprecated and kept for backward compatibility. Don’t use them in new integrations.
  • POST /api/v1/connectors/getTokenFromCode - The old Google Workspace sign-in for individual accounts. Body: { "tempCode": "..." }. Admins only: a member is refused with 403. Answers 200 when the connector existed and 201 when it was created.
  • POST /api/v1/connectors/internal/refreshIndividualConnectorToken - Service-to-service only (a scoped token with FETCH_CONFIG). Refreshes the old Google Workspace individual token, trying up to three times. Answers { "message": "Access token updated successfully" }.
  • POST /api/v1/connectors/updateAppConfig - Service-to-service only (a scoped token with FETCH_CONFIG). Reloads the connector module’s settings after the configuration changes. Answers { "message": "Connectors configuration updated successfully" }.
Endpoint: GET /api/v1/healthAuthentication: none.
Endpoint: GET /api/v1/health/servicesAuthentication: none.

Deleting a connector

Deleting a connector is permanent. Its records don’t go to the trash, even when the trash is turned on, and they can’t be restored.
  1. The request is checked: the caller must be the creator or an admin, no deletion may already be running, no sync may be running, and no agent may use the connector as a knowledge source.
  2. The connector is marked DELETING.
  3. An appDisabled event stops any running sync, and a <type>.delete event (for example confluence.delete) starts the deletion. If that event can’t be published, the DELETING mark is cleared, nothing is deleted, and the request fails.
  4. The request answers 202 Accepted. In the background, the connectors service then:
    • deletes the connector and its records, record groups, permissions and relations from the graph database;
    • asks the indexing service to remove its embeddings;
    • deletes its stored configuration and credentials;
    • deletes its stored files, keeping any content another connector still uses.
  5. If the deletion fails, the DELETING mark is cleared and the connector’s sync setting is put back to what it was, so the connector can be deleted again.

Events

The connector endpoints publish these events on the message broker (Kafka or Redis Streams): <type> is the connector type in lowercase with spaces removed, for example confluence or onedrive.
An appDisabled event from the toggle has the same payload.

Where connector data is kept

  • Connector instances are nodes in the graph database (Neo4j or ArangoDB).
  • Configuration and credentials are in the key-value store (Redis or etcd) at /services/connectors/{connectorId}/config, encrypted with AES-256-GCM. OAuth apps are stored there too, per connector type.
  • Sync schedules are jobs in the crawling manager’s queue. See the Crawling Manager API.

Error Handling

Most errors have this shape:
Three answers differ:
  • Local FS refusals put code and details at the top level.
  • A failed OAuth callback answers 200 with success: false and a top-level error string.
  • A failed check from POST /api/v1/connectors/registry/:connectorType/test-connection answers 200 with { "success": false, "message": "..." }.
A request that fails validation answers 400 with the code VALIDATION_ERROR. A refusal from the connectors service keeps its own message and status: 400, 401, 403, 404, 409, 422 or 429. A server failure in the connectors service becomes 500, with a plain message that names what failed and no internal details. Common HTTP Status Codes:
  • 200 - Success
  • 202 - Accepted: a deletion or vector store job has started
  • 400 - Bad request: a missing or invalid field, or a change the connector’s state doesn’t allow
  • 401 - Missing or invalid token
  • 403 - Not allowed: permission, beta connectors turned off, or a missing token scope
  • 404 - The connector, type or OAuth app doesn’t exist, or the caller may not see it
  • 409 - Conflict: the connector is locked, already being deleted, or in use by an agent
  • 500 - Server failure
  • 503 - Service unavailable, with the code HTTP_SERVICE_UNAVAILABLE, in two cases:
    • PipesHub couldn’t reach the connectors service: “PipesHub is having trouble reaching one of its services. Try again in a minute; if it continues, ask your admin to check the services page.”
    • A resync couldn’t be queued: “We couldn’t start this sync because PipesHub couldn’t queue it. Nothing was synced. Try again in a minute; if it keeps happening, ask your admin to check the services page.”
When the connectors service can’t be reached, the request is tried up to three times, with a growing wait between tries, before it fails.

Local FS refusals

A Local FS connector syncs a folder on one desktop device. When a sync can’t start because of that device, the answer is 409 with a code to branch on:
  • DESKTOP_OFFLINE - The owner device isn’t connected.
  • DESKTOP_UNCLAIMED - No device owns the connector yet. Turn sync on from the PipesHub desktop app on the device that has the folder.
  • DESKTOP_OWNED_BY_OTHER_DEVICE - Another device owns the connector; ownerDeviceName names it.