> ## Documentation Index
> Fetch the complete documentation index at: https://hadiqio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors

> Create and manage connectors that sync external data sources into Hadiq.io.

Connectors pull documents from external systems (Confluence, Google Drive, Slack, and more) into the Hadiq.io search index. All connector endpoints require admin or curator role.

The **connector** stores the configuration for a data source. A **connector-credential pair** (CC pair) links a connector to a set of credentials and controls the sync schedule.

***

## Create a connector

```
POST /api/manage/admin/connector
```

Creates a new connector. The connector is not immediately linked to credentials or indexed — use the CC pair endpoints for that.

### Request body

<ParamField body="name" type="string" required>
  Human-readable name for the connector.
</ParamField>

<ParamField body="source" type="string" required>
  The source type. Examples: `confluence`, `google_drive`, `slack`, `github`, `web`, `file`.
</ParamField>

<ParamField body="input_type" type="string" required>
  How documents are ingested: `poll` (periodic sync), `event` (webhook-driven), or `load_state` (one-time load).
</ParamField>

<ParamField body="connector_specific_config" type="object" required>
  Source-specific configuration. The required keys depend on the connector type. For example, a Confluence connector requires `wiki_base`, `space`, and optionally `page_id`.
</ParamField>

<ParamField body="access_type" type="string" required>
  Access control mode: `public`, `private`, or `sync` (inherit permissions from the source).
</ParamField>

<ParamField body="refresh_freq" type="integer">
  Re-sync interval in seconds. Set to `null` for a one-time index with no automatic refresh.
</ParamField>

<ParamField body="prune_freq" type="integer">
  How often (in seconds) to prune deleted documents from the index. Optional.
</ParamField>

<ParamField body="indexing_start" type="string (ISO 8601)">
  Only index documents updated after this timestamp.
</ParamField>

<ParamField body="groups" type="array">
  Group IDs that have access to documents from this connector (Enterprise Edition only).
</ParamField>

### Response

<ResponseField name="id" type="integer">
  Numeric ID of the newly created connector.
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://cloud.hadiq.io/api/manage/admin/connector \
    -H "Authorization: Bearer hadiqk-..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Engineering Confluence",
      "source": "confluence",
      "input_type": "poll",
      "connector_specific_config": {
        "wiki_base": "https://mycompany.atlassian.net/wiki",
        "space": "ENG"
      },
      "access_type": "public",
      "refresh_freq": 86400
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://cloud.hadiq.io/api/manage/admin/connector",
      headers={"Authorization": "Bearer hadiqk-..."},
      json={
          "name": "Engineering Confluence",
          "source": "confluence",
          "input_type": "poll",
          "connector_specific_config": {
              "wiki_base": "https://mycompany.atlassian.net/wiki",
              "space": "ENG",
          },
          "access_type": "public",
          "refresh_freq": 86400,
      },
  )
  connector_id = resp.json()["id"]
  ```
</CodeGroup>

***

## List connectors

```
GET /api/manage/admin/connector
```

Returns all connectors visible to the authenticated user. System connectors are excluded from this list.

### Query parameters

<ParamField query="credential" type="integer">
  Filter by a specific credential ID.
</ParamField>

### Response

An array of connector snapshots.

<ResponseField name="id" type="integer">
  Connector ID.
</ResponseField>

<ResponseField name="name" type="string">
  Connector name.
</ResponseField>

<ResponseField name="source" type="string">
  Source type.
</ResponseField>

<ResponseField name="input_type" type="string">
  Ingestion mode: `poll`, `event`, or `load_state`.
</ResponseField>

<ResponseField name="connector_specific_config" type="object">
  Source-specific configuration.
</ResponseField>

<ResponseField name="refresh_freq" type="integer">
  Sync frequency in seconds, or `null`.
</ResponseField>

<ResponseField name="credential_ids" type="array">
  IDs of credentials linked to this connector.
</ResponseField>

<ResponseField name="time_created" type="string (ISO 8601)">
  Creation timestamp.
</ResponseField>

<ResponseField name="time_updated" type="string (ISO 8601)">
  Last update timestamp.
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://cloud.hadiq.io/api/manage/admin/connector \
    -H "Authorization: Bearer hadiqk-..."
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://cloud.hadiq.io/api/manage/admin/connector",
      headers={"Authorization": "Bearer hadiqk-..."},
  )
  for connector in resp.json():
      print(connector["id"], connector["name"], connector["source"])
  ```
</CodeGroup>

***

## Update a connector

```
PATCH /api/manage/admin/connector/{connector_id}
```

Updates connector configuration. Accepts the same fields as the create request.

### Path parameters

<ParamField path="connector_id" type="integer" required>
  ID of the connector to update.
</ParamField>

### Request body

Same as [create connector](#create-a-connector). All fields may be updated.

### Response

Returns the updated `ConnectorSnapshot`.

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://cloud.hadiq.io/api/manage/admin/connector/42 \
    -H "Authorization: Bearer hadiqk-..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Engineering Confluence",
      "source": "confluence",
      "input_type": "poll",
      "connector_specific_config": {
        "wiki_base": "https://mycompany.atlassian.net/wiki",
        "space": "ENG"
      },
      "access_type": "public",
      "refresh_freq": 3600
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.patch(
      "https://cloud.hadiq.io/api/manage/admin/connector/42",
      headers={"Authorization": "Bearer hadiqk-..."},
      json={
          "name": "Engineering Confluence",
          "source": "confluence",
          "input_type": "poll",
          "connector_specific_config": {
              "wiki_base": "https://mycompany.atlassian.net/wiki",
              "space": "ENG",
          },
          "access_type": "public",
          "refresh_freq": 3600,
      },
  )
  print(resp.json())
  ```
</CodeGroup>

***

## Trigger a manual sync

```
POST /api/manage/admin/connector/run-once
```

Queues an immediate indexing run for a connector. Use this to sync changes without waiting for the scheduled `refresh_freq`.

### Request body

<ParamField body="connector_id" type="integer" required>
  ID of the connector to sync.
</ParamField>

<ParamField body="credential_ids" type="array">
  Specific credential IDs to run for. If omitted, all credentials linked to the connector are used.
</ParamField>

<ParamField body="from_beginning" type="boolean" default="false">
  When `true`, re-indexes all documents from scratch rather than only new or changed ones.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the sync was successfully queued.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://cloud.hadiq.io/api/manage/admin/connector/run-once \
    -H "Authorization: Bearer hadiqk-..." \
    -H "Content-Type: application/json" \
    -d '{
      "connector_id": 42,
      "from_beginning": false
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://cloud.hadiq.io/api/manage/admin/connector/run-once",
      headers={"Authorization": "Bearer hadiqk-..."},
      json={"connector_id": 42, "from_beginning": False},
  )
  print(resp.json())
  ```
</CodeGroup>

***

## Get CC pair details

```
GET /api/manage/admin/cc-pair/{cc_pair_id}
```

Returns full details about a connector-credential pair, including indexing status, document counts, and sync history.

### Path parameters

<ParamField path="cc_pair_id" type="integer" required>
  The CC pair ID.
</ParamField>

### Response

<ResponseField name="id" type="integer">
  CC pair identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the CC pair.
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `active`, `paused`, or `deleting`.
</ResponseField>

<ResponseField name="num_docs_indexed" type="integer">
  Total documents currently in the index for this CC pair.
</ResponseField>

<ResponseField name="connector" type="object">
  Embedded connector snapshot.
</ResponseField>

<ResponseField name="credential" type="object">
  Embedded credential snapshot (sensitive fields masked).
</ResponseField>

<ResponseField name="last_index_attempt_status" type="string">
  Status of the most recent index attempt: `success`, `failed`, `in_progress`, or `not_started`.
</ResponseField>

<ResponseField name="last_indexed" type="string (ISO 8601)">
  Timestamp of the last successful sync.
</ResponseField>

<ResponseField name="indexing" type="boolean">
  Whether a sync is currently in progress.
</ResponseField>

<ResponseField name="access_type" type="string">
  `public`, `private`, or `sync`.
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://cloud.hadiq.io/api/manage/admin/cc-pair/7 \
    -H "Authorization: Bearer hadiqk-..."
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://cloud.hadiq.io/api/manage/admin/cc-pair/7",
      headers={"Authorization": "Bearer hadiqk-..."},
  )
  pair = resp.json()
  print(pair["name"], pair["status"], pair["num_docs_indexed"])
  ```
</CodeGroup>

***

## Pause or resume a CC pair

```
PUT /api/manage/admin/cc-pair/{cc_pair_id}/status
```

Sets the sync status of a connector-credential pair. Pausing stops all future indexing runs.

### Path parameters

<ParamField path="cc_pair_id" type="integer" required>
  The CC pair to update.
</ParamField>

### Request body

<ParamField body="status" type="string" required>
  New status: `active` to resume, `paused` to pause.
</ParamField>

<CodeGroup>
  ```bash curl (pause) theme={null}
  curl -X PUT https://cloud.hadiq.io/api/manage/admin/cc-pair/7/status \
    -H "Authorization: Bearer hadiqk-..." \
    -H "Content-Type: application/json" \
    -d '{"status": "paused"}'
  ```

  ```bash curl (resume) theme={null}
  curl -X PUT https://cloud.hadiq.io/api/manage/admin/cc-pair/7/status \
    -H "Authorization: Bearer hadiqk-..." \
    -H "Content-Type: application/json" \
    -d '{"status": "active"}'
  ```

  ```python Python theme={null}
  import requests

  requests.put(
      "https://cloud.hadiq.io/api/manage/admin/cc-pair/7/status",
      headers={"Authorization": "Bearer hadiqk-..."},
      json={"status": "paused"},
  )
  ```
</CodeGroup>

***

## Error codes

| Status | Cause                                                       |
| ------ | ----------------------------------------------------------- |
| `400`  | Invalid connector configuration or connector not deletable. |
| `403`  | Insufficient permissions to manage the connector.           |
| `404`  | Connector or CC pair not found.                             |