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

# Connectors

> A generic framework for integrating external data sources into Nia — discover, install, configure, index, and search.

Connectors provide a unified way to bring external data sources into Nia. Instead of building custom integrations for every service, connectors follow a common lifecycle: discover available types, install one with credentials, configure sync settings, trigger indexing, and search the results alongside all your other Nia sources.

<Info>
  Connectors are a generalization of Nia's integration model. Each connector type (e.g., Notion, Confluence, Jira) follows the same API contract, so you can manage them all with a single set of endpoints.
</Info>

***

## How Connectors Work

<Steps>
  <Step title="Discover">
    List available connector types to see what external services Nia supports. Each type describes the authentication method it requires (API key or OAuth).
  </Step>

  <Step title="Install">
    Install a connector by providing credentials. For API-key-based connectors, pass the key directly. For OAuth-based connectors, the API returns an authorization URL — redirect the user and handle the callback.
  </Step>

  <Step title="Configure">
    Set up a sync schedule and configure what data gets indexed. You can run one-time imports or set up recurring syncs on a cron schedule.
  </Step>

  <Step title="Index">
    Trigger indexing to pull data from the external source, chunk it, embed it, and store it in Nia's vector index.
  </Step>

  <Step title="Search">
    Once indexed, connector data is searchable through the same unified search endpoint used for repositories, docs, Slack, and every other Nia source type.
  </Step>
</Steps>

***

## Available Connector Types

List all connector types your organization can use:

```bash theme={null}
curl https://apigcp.trynia.ai/v2/connectors \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "connectors": [
    {
      "type": "notion",
      "name": "Notion",
      "auth_method": "oauth",
      "description": "Index Notion pages and databases"
    },
    {
      "type": "confluence",
      "name": "Confluence",
      "auth_method": "api_key",
      "description": "Index Confluence spaces and pages"
    }
  ]
}
```

Each connector type specifies its `auth_method`:

| Auth Method | How It Works                                                                                               |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| `api_key`   | Pass the API key directly during installation                                                              |
| `oauth`     | Nia returns an authorization URL; the user approves access and Nia handles the token exchange via callback |

***

## Installing a Connector

### API Key Authentication

For connectors that use API key auth, provide the credentials directly:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/connectors/confluence/install \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "api_key": "your-confluence-api-key",
      "domain": "yourteam.atlassian.net"
    },
    "display_name": "Engineering Confluence"
  }'
```

```json theme={null}
{
  "installation_id": "c3a91f02-...",
  "connector_type": "confluence",
  "display_name": "Engineering Confluence",
  "status": "active",
  "created_at": "2026-03-29T10:00:00Z"
}
```

### OAuth Authentication

For OAuth-based connectors, the install endpoint returns an authorization URL:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/connectors/notion/install \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Team Notion"
  }'
```

```json theme={null}
{
  "authorization_url": "https://api.notion.com/v1/oauth/authorize?client_id=...&redirect_uri=...",
  "state": "abc123"
}
```

Redirect the user to `authorization_url`. After they approve, Notion redirects to Nia's callback endpoint:

```
GET /v2/connectors/notion/oauth/callback?code=...&state=abc123
```

Nia exchanges the code for an access token and creates the installation automatically.

***

## Managing Installations

### List All Installations

```bash theme={null}
curl https://apigcp.trynia.ai/v2/connectors/installations \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "installations": [
    {
      "id": "c3a91f02-...",
      "connector_type": "confluence",
      "display_name": "Engineering Confluence",
      "status": "active",
      "last_sync_at": "2026-03-28T14:30:00Z",
      "schedule": "0 */6 * * *",
      "indexed_document_count": 342
    },
    {
      "id": "f7b24e91-...",
      "connector_type": "notion",
      "display_name": "Team Notion",
      "status": "active",
      "last_sync_at": "2026-03-29T08:00:00Z",
      "schedule": null,
      "indexed_document_count": 128
    }
  ]
}
```

### Disconnect a Connector

Remove an installation and all its indexed data:

```bash theme={null}
curl -X DELETE https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-... \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "message": "Installation disconnected and data removed."
}
```

<Warning>
  Disconnecting a connector permanently deletes all indexed data from that installation. This action cannot be undone.
</Warning>

***

## Indexing

### Trigger Indexing

Start an indexing job that pulls content from the external source:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-.../index \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "installation_id": "c3a91f02-...",
  "status": "processing",
  "workflow_run_id": "d4e56f78-..."
}
```

### Check Sync Status

```bash theme={null}
curl https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-.../status \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "installation_id": "c3a91f02-...",
  "connector_type": "confluence",
  "status": "processing",
  "progress": 67,
  "message": "Indexing pages (230/342)",
  "indexed_document_count": 230,
  "chunk_count": 1840,
  "last_sync_at": "2026-03-28T14:30:00Z"
}
```

| Status       | Meaning                         |
| ------------ | ------------------------------- |
| `idle`       | No indexing in progress         |
| `processing` | Indexing is running             |
| `completed`  | Last sync finished successfully |
| `failed`     | Last sync encountered an error  |

***

## Scheduling and Sync Management

### Set a Sync Schedule

Configure automatic recurring syncs using a cron expression:

```bash theme={null}
curl -X PATCH https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-.../schedule \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 */6 * * *"
  }'
```

```json theme={null}
{
  "installation_id": "c3a91f02-...",
  "schedule": "0 */6 * * *",
  "next_sync_at": "2026-03-29T18:00:00Z"
}
```

Common schedule patterns:

| Cron Expression | Frequency                 |
| --------------- | ------------------------- |
| `0 */6 * * *`   | Every 6 hours             |
| `0 0 * * *`     | Daily at midnight         |
| `0 9 * * 1`     | Weekly on Mondays at 9 AM |
| `0 */1 * * *`   | Every hour                |

### Disable Scheduled Sync

Set the schedule to `null` to stop automatic syncs:

```bash theme={null}
curl -X PATCH https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-.../schedule \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": null
  }'
```

<Info>
  Even with a schedule disabled, you can always trigger a manual sync via `POST /v2/connectors/installations/{id}/index`.
</Info>

***

## Searching Connector Data

Once indexed, connector data is available through Nia's unified search endpoint alongside all your other sources:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/search/query \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "What is our onboarding process?"}],
    "include_sources": true,
    "stream": true
  }'
```

You can also target specific connector installations:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/search/query \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "sprint planning guidelines"}],
    "connector_installations": ["c3a91f02-...", "f7b24e91-..."],
    "include_sources": true,
    "stream": true
  }'
```

***

## API Reference

| Method   | Endpoint                                         | Description                            |
| -------- | ------------------------------------------------ | -------------------------------------- |
| `GET`    | `/v2/connectors`                                 | List available connector types         |
| `POST`   | `/v2/connectors/{connector_type}/install`        | Install a connector (API key or OAuth) |
| `GET`    | `/v2/connectors/{connector_type}/oauth/callback` | Handle OAuth callback                  |
| `GET`    | `/v2/connectors/installations`                   | List all installations                 |
| `DELETE` | `/v2/connectors/installations/{id}`              | Disconnect and remove an installation  |
| `POST`   | `/v2/connectors/installations/{id}/index`        | Trigger indexing                       |
| `PATCH`  | `/v2/connectors/installations/{id}/schedule`     | Update sync schedule                   |
| `GET`    | `/v2/connectors/installations/{id}/status`       | Get sync status                        |

***

<Accordion title="FAQ: What happens to my data when I disconnect?">
  When you disconnect a connector via `DELETE /v2/connectors/installations/{id}`, all indexed data (chunks, embeddings, metadata) is permanently removed from Nia. The external source itself is not modified.
</Accordion>

<Accordion title="FAQ: Can I install the same connector type multiple times?">
  Yes. For example, you can connect multiple Confluence instances or multiple Notion workspaces. Each installation operates independently with its own credentials, schedule, and indexed data.
</Accordion>

<Accordion title="FAQ: How long does indexing take?">
  Indexing time depends on the volume of content in the external source and any rate limits imposed by the third-party API. Most installations with a few hundred documents complete within a few minutes. Large sources (10k+ documents) may take 30-60 minutes.
</Accordion>

***

<Warning>
  **Need Help?** Join our [Discord community](https://discord.gg/BBSwUMrrfn) or reach out through [app.trynia.ai](https://app.trynia.ai/) for support.
</Warning>