> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.talqora.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.talqora.com/_mcp/server.

# Connectors

> Connect managed providers or a Custom API and keep a retrieval index current through durable serverless processing jobs.

Connectors turn operational systems into retrieval-ready sources without making your product build OAuth refresh, cursor management, provider polling, extraction workers, embeddings, or an indexing queue. A connection authorizes one provider account or securely defines a Custom API, then turns changed remote objects into ordinary Talqora processing jobs.

The resulting content is not a special search tier. It is indexed into the selected Talqora index alongside files and direct vector writes. Dense, sparse, hybrid retrieval, metadata filters, Assistant RAG, source citations, replacement, deletion, usage, and API-key index scopes all work the same way.

## Availability and entitlement

Connectors are a **Beta capability for Scale and Enterprise** organizations. Developer organizations may see the catalog but cannot initiate OAuth or create a shareable connection link. A Talqora administrator can also disable connector sync for an organization while a provider configuration, scope, or operational review is incomplete.

Provider availability is intentionally environment-specific. The console catalog can show Gmail, Google Drive, Google Calendar, Slack, Notion, Salesforce, HubSpot, Linear, Jira, Microsoft SharePoint, and Dropbox. A provider becomes connectable only after Talqora has configured its Nango integration ID, sync model, and sync behavior in the production environment. This avoids presenting an OAuth button for a provider that cannot yet produce a defined record schema.

Use `GET /v1/indexes/{index_id}/connectors` to read the actual availability for the index and organization rather than assuming that a catalog label means a provider is enabled.

## What a connection does

1. A workspace user chooses an index and a provider in **Processing**.
2. Talqora creates a short-lived Nango Connect session bound to the organization, index, and provider.
3. The browser opens the provider's OAuth page. Provider credentials and refresh tokens never pass through the Talqora console.
4. Nango reports the authorization result to Talqora through a signed webhook. Talqora creates a connection record bound to exactly one organization and index.
5. The console polls `GET /v1/indexes/{index_id}/connectors` until it sees the connection and its required next state.
6. The user selects an allowed scope where the provider supports it, such as Google Drive folders or an initial date for Gmail and Google Calendar.
7. Talqora stores the scope, updates Nango metadata, and triggers the provider sync. New or changed remote records become durable ingestion jobs.
8. Serverless processors normalize the remote content, chunk it, create 1536-dimensional embeddings, index lexical text, and preserve source provenance.
9. Future syncs use a cursor and content hashes so unchanged records are not reprocessed.

An integration connection is a source-of-truth relationship, not a one-time import. It keeps the selected index current as the connected system changes, subject to provider permissions, provider rate limits, plan limits, and configured sync behavior.

## Before connecting

Choose a **1536-dimensional** index. Connector content uses the same embedding path as File Processing, so it cannot target a direct-write index with a different dimension contract.

Decide your search boundary before authorization. A connection is attached to one index, so use an index that already has the correct region, tenant separation, API-key policy, and metadata strategy. For example:

* Connect a legal team's Drive and Notion spaces to `legal-knowledge-us`.
* Connect a customer-success Gmail mailbox and Salesforce records to `account-context-us`.
* Connect engineering Slack and Linear to `engineering-support-eu`.

Do not connect a broad company account to a general index and attempt to fix access later with UI hiding. Use provider scopes, a well-designed index boundary, and mandatory metadata filters in downstream queries.

## Custom API connector

Use **Custom API** when your system exposes records through an HTTPS `GET` endpoint but is not one of the managed providers. Talqora detects a JSON array at the root or under `items`, `data`, `results`, `records`, or `documents`; a `content_path` can select another nested array. JSON objects and plain-text responses are also accepted. Each record becomes an idempotent file-processing job, so the normal serverless processor performs chunking, embeddings, dense writes, sparse writes, replacement, and provenance.

Create the connector with a dashboard session. Authentication material is encrypted before persistence, never returned by the API, and only released to the ingestion processor for the outbound request.

```bash
curl --fail-with-body -X POST "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/custom-api" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Support API",
    "endpoint_url":"https://api.example.com/v1/knowledge",
    "headers":{"X-Workspace":"acme"},
    "auth":{"type":"bearer","token":"secret-token"},
    "content_path":"data.articles",
    "sync_interval_minutes":60,
    "requests_per_minute":30
  }'
```

Authentication can be `none`, `bearer`, `basic`, or a custom header. Do not put a credential in the URL. Talqora accepts HTTPS on port 443 only, rejects URL credentials, redirects, private/reserved destinations, and restricted request headers such as `Host`, `Cookie`, and forwarding headers. Responses are limited to 5 MiB.

The initial sync is queued immediately. Use the returned connection ID to request another sync after data changes:

```bash
curl --fail-with-body -X POST \
  "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/$CONNECTION_ID/sync" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
```

`sync_interval_minutes` and `requests_per_minute` define the connector's operating policy (15–1,440 minutes and 1–120 requests/minute). After a successful sync, the serverless processor queues the next run; long intervals are safely represented as SQS delay hops. The API records the next due time after every completed or failed run. The processor follows same-origin JSON `next` links for up to 100 pages and enforces the configured request rate between pages.

Pause a Custom API connector to stop subsequent scheduled runs, resume it to queue an immediate sync, or delete it when its source is no longer required:

```bash
curl -X POST "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/$CONNECTION_ID/pause" -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
curl -X POST "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/$CONNECTION_ID/resume" -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
curl -X DELETE "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/$CONNECTION_ID" -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
```

## Catalog and connection status

```bash
curl --fail-with-body \
  "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
```

This dashboard-session endpoint returns whether integrations are enabled for the organization, the configured catalog, and active connections. Connection state describes the provider relationship:

| State                 | Meaning                                                                                      | What to do                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `needs_configuration` | OAuth succeeded, but Talqora needs a required boundary before it may start a provider crawl. | Submit the provider configuration, such as `gmail_after` or `calendar_after`.       |
| `connected`           | Authorization exists and Talqora can receive or process configured changes.                  | Monitor processed objects and retrieval results.                                    |
| `syncing`             | A provider sync or initial import is in progress.                                            | Wait for jobs; do not reconnect unless authorization failed.                        |
| `failed`              | Authorization, provider API, sync, or processing setup could not continue.                   | Review the connection error, repair authorization/scope, then trigger a fresh sync. |

File-job status is more granular than connection status. A connection can be `connected` while one source job is still processing or has failed. Use the Processing job list to inspect a specific document or message.

## Start an OAuth session

The interactive flow uses a dashboard session because it opens a browser authorization page:

```bash
curl --fail-with-body \
  -X POST "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/gmail/connect-session" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
```

The response has a short-lived `connect_link`. Open it in a popup or top-level navigation and keep the product UI in a “Waiting for authorization” state until the OAuth window returns. Do not store the URL as a reusable credential, embed it in a public page, or send it to another tenant.

For delegated setup, an authenticated workspace user can create a short-lived **shareable connection link** with `POST /v1/indexes/{index_id}/connectors/{connector_slug}/connect-link`. The recipient may complete provider OAuth without being a Talqora console user; the link remains bound to the creating organization, index, and provider. Treat it like a temporary enrollment link, not like an API key. Rotate it by creating another one and do not put it into public documentation, tickets, or logs.

## Select scope before first sync

OAuth authorization is not the same as selecting what will be indexed. The connector's scope tells Talqora which remote objects are in bounds. Poll the connector overview after OAuth: a `needs_configuration` connection must be configured before the first import starts.

Google Drive currently supports server-side folder browsing. List folders through the connected identity:

```bash
curl --fail-with-body \
  "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/$CONNECTION_ID/folders" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
```

Set the selected folders or files and start the sync:

```bash
curl --fail-with-body \
  -X PUT "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/$CONNECTION_ID/scope" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folders":["drive-folder-id"],"files":[]}'
```

Google Drive requires at least one folder or file. Other providers may expose provider-specific scope selectors as they become configured, such as an inbox or label for Gmail, channels for Slack, pages/databases for Notion, objects for Salesforce, or teams/projects for Linear. Never assume that a broad OAuth grant should index the entire account.

Gmail and Google Calendar require an initial date. Talqora sends it to Nango before the first page is fetched, and Nango keeps applying it to incremental updates. This prevents historical mail or old events from being indexed accidentally:

```bash
curl --fail-with-body -X PUT \
  "https://api.talqora.com/v1/indexes/$INDEX_ID/connectors/$CONNECTION_ID/scope" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"calendar_after":"2026-07-15"}'
```

Use `{"gmail_after":"2026-07-15"}` for Gmail. Polling clients receive `selected_start_date` in the connector overview, alongside account and job status.

## Provider use cases

### Gmail

Connect a selected mailbox when answers depend on customer correspondence, approvals, escalation history, or shared attachments. A support or account team can ask, “What did this customer approve last month?” and retrieve message evidence alongside CRM records.

Keep the index bounded: use a dedicated mailbox, relevant folders or labels when supported, and a tenant or account identifier in your surrounding application filter. Email can contain sensitive content; configure access so a user only retrieves conversations they are entitled to see.

### Google Drive and SharePoint

Use document integrations for policies, contracts, sales collateral, product requirements, meeting notes, and operating procedures. These sources are a natural base for Assistant RAG because retrieved chunks retain filename and page-level provenance where available.

Start with a small set of folders, validate retrieval quality and access boundaries, then expand scope. Do not index every shared drive merely because an administrator can authorize it.

### Google Calendar

Calendar event documents keep the title, start/end, organizer, attendees, location, description, recurrence, source URL, and meeting URL. Talqora omits Nango's raw event metadata, including extended properties and conference objects. Configure `calendar_after` before the first sync to bound the source.

### Slack, Linear, and Jira

Use collaboration integrations for incident knowledge, product decisions, engineering discussions, issues, milestones, and delivery history. Hybrid retrieval is especially useful because people search exact issue IDs and error messages as well as conceptual questions such as “why did we postpone the migration?”

Prefer selected channels, teams, or projects. Chat and issue data changes quickly, so use source metadata and timestamps to let your product emphasize recent evidence and avoid presenting an old decision as current policy.

### Notion, Salesforce, HubSpot, and Dropbox

Use Notion for company knowledge, pages, and database-backed operating context. Use Salesforce and HubSpot for accounts, opportunities, cases, notes, and customer context. Use Dropbox for shared folders and business files.

These sources work well for customer-facing agents when the application enforces account and role filters. A CRM connection is not permission to expose all records to every support user; it is an ingestion mechanism that must be paired with a retrieval policy.

## Source provenance and search UX

Connector-derived chunks return normal retrieval results. When applicable, metadata contains a connector label:

```json
{
  "source_file": "gmail-18c4a.md",
  "job_id": "job_...",
  "source_from_connector": "gmail",
  "chunk": 0
}
```

Render `source_from_connector` as evidence provenance in your UI: “Gmail,” “Google Drive,” or “Notion,” rather than exposing an implementation filename. Preserve available source names, pages, and timestamps. A result should help an operator understand both **what was found** and **where the evidence came from**.

## Sync behavior, updates, and deletes

Talqora stores a connector connection ID, cursor, source IDs, hashes, job state, and retrieval provenance in the control plane. It does not use the console as an OAuth token store. Nango handles the managed provider connection and refresh behavior; Talqora verifies signed webhook events before accepting them.

Remote change delivery is at-least-once. Talqora makes it safe through idempotent event recording and content hashes:

* A duplicate event is ignored.
* An unchanged source is not reprocessed.
* A changed source creates a replacement processing job.
* The prior source remains searchable until the replacement is accepted, then it is superseded.
* A failed individual file job is visible independently of the connection and does not imply every source failed.

Provider deletion behavior depends on the configured sync model and source data returned by the provider. Build your product around observable job state and periodic reconciliation; do not assume every external provider emits immediate deletion events under every permission model.

## Security model

Use the smallest provider scope that accomplishes the use case. Keep the Talqora dashboard session separate from data-plane API keys. Provider authorization occurs through Nango Connect, and Talqora uses signed webhooks for connection and sync events.

An integration is scoped to one Talqora organization and one index. It cannot be read from another organization through a guessed connection ID. This does not eliminate the need for record-level controls: enforce tenant, user, department, or visibility metadata filters in every application query where the index contains more than one access domain.

Avoid logging provider payloads, OAuth return URLs, connect links, attachment bodies, or user email content. Use the console's connection error state for support diagnosis and share only redacted identifiers with Talqora support.

## Failure handling and operations

If OAuth is rejected, reconnect and complete the provider's consent flow. If a connection is `failed`, inspect the operational error and distinguish provider authorization, provider rate limiting, configured sync model, and downstream file-job failures. Reconnecting a provider does not repair a malformed document; inspect the file job for that source.

For a large initial import, monitor processing job counts, completed tasks, vectors written, storage, query behavior, and plan limits. Start with a bounded scope, validate dense/sparse/hybrid results, then expand. Do not repeatedly create new connections to force an import; that duplicates operational state and makes provenance harder to audit.

## Integration design checklist

1. Is the index 1536-dimensional and in the required region?
2. Which provider objects are in scope, and who is allowed to retrieve them?
3. Which metadata filters will the product enforce on every search?
4. Is the first sync bounded enough to validate quality and cost?
5. Does the UI show connection status separately from individual processing jobs?
6. Are connector-derived results clearly labeled with their source?
7. Is there a plan to review authorization failures, stale content, and provider deletion behavior?