---
title: "Toggle connector sync or agent"
method: POST
path: "/connectors/{connectorId}/toggle"
tags: ["Connector Control"]
---

# Toggle connector sync or agent

`POST /connectors/{connectorId}/toggle`

## Request

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

Flip a connector's sync or agent use: each call turns it on when it is off and
off when it is on. Read <code>isActive</code> / <code>isAgentActive</code> first. Turning sync on
starts the first sync.<br><br>
<b>Toggle Types:</b><br>
<ul>
<li><code>sync</code> - data synchronization</li>
<li><code>agent</code> - use by AI agents</li>
</ul>
<b>Before Sync Can Be Turned On:</b><br>
<ul>
<li>The connector is configured (<code>isConfigured: true</code>)</li>
<li>OAuth connectors: sign-in has completed</li>
<li>The connection test against the source passes</li>
<li>For agent: the connector supports agents (<code>supportsAgent: true</code>)</li>
<li>Local FS: must be enabled from the owner device via the desktop app, which sends <code>deviceId</code> and <code>deviceName</code>. The first enable claims that device as owner.</li>
</ul>
<b>Permissions:</b><br>
<ul>
<li>Team scope: Requires admin</li>
<li>Personal scope: Only creator can toggle</li>
</ul>

## Path parameters

- `connectorId` string, required

## Request body

- ConnectorToggleRequest
  - `type` 'sync' | 'agent', required: 'sync' flips data synchronization; 'agent' flips use by agents
  - `fullSync` boolean: When turning sync on, start from scratch
  - `deviceId` string: Local FS only
  - `deviceName` string: Local FS only

## Response `200`

Flipped

- object
  - `success` boolean, required
  - `message` string

## Other responses

- `400`: Invalid body, or the connector cannot be turned on yet: OAuth sign-in is not complete, it is not configured, or its connection test failed
- `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
- `409`: A Local FS desktop refusal, or the connector is locked
- `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 info
  - the `fullSync` request property default value `false` was added
- **2026-10-15** `a44792e4f0e6`: 1 info
  - endpoint added

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