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 asConfluence, 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.
Authentication
Every endpoint except the health checks needs a bearer token: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 gets403. A connector the caller may not see at all is reported as 404, so the API doesn’t confirm that it exists.
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 with409 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/.
Registry
Registry
GET /registry - List connector types
GET /registry - List connector types
- Request
- Response
GET /api/v1/connectors/registryScope: connector:readQuery Parameters:GET /registry/:connectorType/schema - Get a connector type's setup form
GET /registry/:connectorType/schema - Get a connector type's setup form
- Request
- Response
GET /api/v1/connectors/registry/:connectorType/schemaScope: connector:readPath Parameters:connectorType: Connector type name, for exampleConfluence(string, required)
POST /registry/:connectorType/test-connection - Test sign-in settings before saving
POST /registry/:connectorType/test-connection - Test sign-in settings before saving
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.- Request
- Response
POST /api/v1/connectors/registry/:connectorType/test-connectionScope: connector:writePath Parameters:connectorType: Connector type name, for examplePostgreSQL(string, required)
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 /network/egress-ips - Get the IP addresses connectors connect from
GET /network/egress-ips - Get the IP addresses connectors connect from
- Request
- Response
GET /api/v1/connectors/network/egress-ipsScope: connector:readConnector instances
Connector instances
GET / - List connectors
GET / - List connectors
- Request
- Response
GET /api/v1/connectorsScope: connector:readQuery Parameters:POST / - Create a connector
POST / - Create a connector
- Request
- Response
POST /api/v1/connectorsScope: connector:writeRequest Body Parameters: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.GET /active and GET /inactive - List connectors by sync state
GET /active and GET /inactive - List connectors by sync state
/active) or off (/inactive). These two endpoints take no query parameters and don’t paginate.- Request
- Response
GET /api/v1/connectors/active, GET /api/v1/connectors/inactiveScope: connector:readGET /configured - List configured connectors
GET /configured - List configured connectors
- Request
- Response
GET /api/v1/connectors/configuredScope: connector:readQuery Parameters: scope (defaults to team), page, limit and search, as for GET /.GET /agents/active - List connectors available to agents
GET /agents/active - List connectors available to agents
- Request
- Response
GET /api/v1/connectors/agents/activeScope: connector:readQuery Parameters: scope (defaults to team), page, limit and search, as for GET /.GET /:connectorId - Get a connector
GET /:connectorId - Get a connector
- Request
- Response
GET /api/v1/connectors/:connectorIdScope: connector:readPath Parameters:connectorId: Connector instance ID (string, required)
PUT /:connectorId/name - Rename a connector
PUT /:connectorId/name - Rename a connector
- Request
- Response
PUT /api/v1/connectors/:connectorId/nameScope: connector:writeDELETE /:connectorId - Delete a connector
DELETE /:connectorId - Delete a connector
- Request
- Response
DELETE /api/v1/connectors/:connectorIdScope: connector:deleteAccess Control: the connector’s creator or an admin, for either scope.Configuration
Configuration
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.GET /:connectorId/config - Get a connector's configuration
GET /:connectorId/config - Get a connector's configuration
- Request
- Response
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.PUT /:connectorId/config - Update the whole configuration
PUT /:connectorId/config - Update the whole configuration
- Request
- Response
PUT /api/v1/connectors/:connectorId/configScope: connector:writeRequest Body Parameters: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.PUT /:connectorId/config/auth - Update sign-in settings
PUT /:connectorId/config/auth - Update sign-in settings
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.- Request
- Response
PUT /api/v1/connectors/:connectorId/config/authScope: connector:write•••••••• 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. WithoutoauthConfigId, 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
200and signs the connector out, and the OAuth app’s secret stays as it was.
PUT /:connectorId/config/filters-sync - Update sync and filter settings
PUT /:connectorId/config/filters-sync - Update sync and filter settings
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.- Request
- Response
PUT /api/v1/connectors/:connectorId/config/filters-syncScope: connector:writeOAuth sign-in
OAuth sign-in
GET /oauth/callback - Finish OAuth sign-in
GET /oauth/callback - Finish OAuth sign-in
- Request
- Response
GET /api/v1/connectors/oauth/callbackScope: connector:writeQuery Parameters: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.Filters
Filters
GET /:connectorId/filters - Get filter options
GET /:connectorId/filters - Get filter options
- Request
- Response
GET /api/v1/connectors/:connectorId/filtersScope: connector:readGET /:connectorId/filters/:filterKey/options - Search one filter's options
GET /:connectorId/filters/:filterKey/options - Search one filter's options
- Request
- Response
GET /api/v1/connectors/:connectorId/filters/:filterKey/optionsScope: connector:readQuery Parameters:POST /:connectorId/filters - Save filter selections
POST /:connectorId/filters - Save filter selections
PUT /:connectorId/config/filters-sync.- Request
- Response
POST /api/v1/connectors/:connectorId/filtersScope: connector:writefilters.values, but syncs read filters.sync.values and filters.indexing.values.Sync and indexing
Sync and indexing
POST /:connectorId/toggle - Turn sync or agent use on or off
POST /:connectorId/toggle - Turn sync or agent use on or off
- Request
- Response
POST /api/v1/connectors/:connectorId/toggleScope: connector:syncRequest Body Parameters:POST /:connectorId/resync - Sync again now
POST /:connectorId/resync - Sync again now
- Request
- Response
POST /api/v1/connectors/:connectorId/resyncScope: connector:write or kb:writeRequest Body Parameters:POST /:connectorId/sync/stop - Stop a running sync
POST /:connectorId/sync/stop - Stop a running sync
- Request
- Response
POST /api/v1/connectors/:connectorId/sync/stopScope: connector:syncNo request body.POST /:connectorId/reindex - Reindex a connector's records
POST /:connectorId/reindex - Reindex a connector's records
- Request
- Response
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:GET /:connectorId/stats - Get indexing stats
GET /:connectorId/stats - Get indexing stats
- Request
- Response
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.POST /vector-store/cleanup and POST /vector-store/reindex - Rebuild the vector store
POST /vector-store/cleanup and POST /vector-store/reindex - Rebuild the vector store
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.- Request
- Response
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.”).Records and the knowledge graph
Records and the knowledge graph
GET /api/v1/connectors/record/:recordId/content- A record’s full parsed content and metadata. Scopeconnector: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, andcreatedAfter,createdBefore,modifiedAfter,modifiedBefore. Scopekb:readorconnector: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 optionallyconnectorName. Scopekb:readorconnector:read.
OAuth apps
OAuth apps
/api/v1/oauth.GET /api/v1/oauth/registry - List types that sign in with OAuth
GET /api/v1/oauth/registry - List types that sign in with OAuth
- Request
- Response
GET /api/v1/oauth/registryScope: connector:readQuery Parameters: page (defaults to 1), limit (1 to 200, defaults to 20) and search.GET /api/v1/oauth/registry/:connectorType - Get one type's OAuth registration
GET /api/v1/oauth/registry/:connectorType - Get one type's OAuth registration
- Request
- Response
GET /api/v1/oauth/registry/:connectorTypeScope: connector:readGET /api/v1/oauth - List all OAuth apps
GET /api/v1/oauth - List all OAuth apps
- Request
- Response
GET /api/v1/oauthScope: connector:readQuery Parameters: page, limit (1 to 200) and search (matches the app name, group, description, type and categories).GET /api/v1/oauth/:connectorType - List one type's OAuth apps
GET /api/v1/oauth/:connectorType - List one type's OAuth apps
- Request
- Response
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.POST /api/v1/oauth/:connectorType - Create an OAuth app
POST /api/v1/oauth/:connectorType - Create an OAuth app
- Request
- Response
POST /api/v1/oauth/:connectorTypeScope: connector:writeAccess Control: admins only (403 for members).Request Body Parameters:GET /api/v1/oauth/:connectorType/:configId - Get an OAuth app
GET /api/v1/oauth/:connectorType/:configId - Get an OAuth app
- Request
- Response
GET /api/v1/oauth/:connectorType/:configIdScope: connector:readPUT /api/v1/oauth/:connectorType/:configId - Update an OAuth app
PUT /api/v1/oauth/:connectorType/:configId - Update an OAuth app
- Request
- Response
PUT /api/v1/oauth/:connectorType/:configIdScope: connector:writeAccess Control: admins only (403 for members).Send oauthInstanceName, config, or both, and optionally baseUrl.DELETE /api/v1/oauth/:connectorType/:configId - Delete an OAuth app
DELETE /api/v1/oauth/:connectorType/:configId - Delete an OAuth app
- Request
- Response
DELETE /api/v1/oauth/:connectorType/:configIdScope: connector:deleteAccess Control: admins only (403 for members).Legacy endpoints
Legacy endpoints
POST /api/v1/connectors/getTokenFromCode- The old Google Workspace sign-in for individual accounts. Body:{ "tempCode": "..." }. Admins only: a member is refused with403. Answers200when the connector existed and201when it was created.POST /api/v1/connectors/internal/refreshIndividualConnectorToken- Service-to-service only (a scoped token withFETCH_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 withFETCH_CONFIG). Reloads the connector module’s settings after the configuration changes. Answers{ "message": "Connectors configuration updated successfully" }.
Health
Health
GET /api/v1/health - Check the stores PipesHub depends on
GET /api/v1/health - Check the stores PipesHub depends on
- Request
- Response
GET /api/v1/healthAuthentication: none.GET /api/v1/health/services - Check the PipesHub services
GET /api/v1/health/services - Check the PipesHub services
- Request
- Response
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.- 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.
- The connector is marked
DELETING. - An
appDisabledevent stops any running sync, and a<type>.deleteevent (for exampleconfluence.delete) starts the deletion. If that event can’t be published, theDELETINGmark is cleared, nothing is deleted, and the request fails. - 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.
- If the deletion fails, the
DELETINGmark 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.
appEnabled event
appEnabled event
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:- Local FS refusals put
codeanddetailsat the top level. - A failed OAuth callback answers
200withsuccess: falseand a top-levelerrorstring. - A failed check from
POST /api/v1/connectors/registry/:connectorType/test-connectionanswers200with{ "success": false, "message": "..." }.
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- Success202- Accepted: a deletion or vector store job has started400- Bad request: a missing or invalid field, or a change the connector’s state doesn’t allow401- Missing or invalid token403- Not allowed: permission, beta connectors turned off, or a missing token scope404- The connector, type or OAuth app doesn’t exist, or the caller may not see it409- Conflict: the connector is locked, already being deleted, or in use by an agent500- Server failure503- Service unavailable, with the codeHTTP_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.”
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 is409 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;ownerDeviceNamenames it.