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

# Connect a data source

> Discover connectors, create a connection, and sync documents into a workspace

Connections link an external system (Google Drive, SharePoint, OneDrive, Microsoft Teams, or Odoo) to a workspace. You discover the connector, connect with credentials or OAuth, then sync to pull documents into AiQL.

## Prerequisites

* An AiQL API key in the `AIQL_API_KEY` environment variable
* A workspace ID (see [Quickstart](/quickstart) to create one)
* Credentials for the system you want to connect (API key for Odoo, or an OAuth-capable account for Google/Microsoft)

## Discover connectors

List every connector in the marketplace catalog, including ones that are discoverable but not yet connectable through the API.

```bash theme={null}
curl https://api.aiql.io/connectors \
  -H "Authorization: Bearer $AIQL_API_KEY"
```

Each entry reports `connectable`, `auth_type`, and (when connectable) `config_schema` and `example_config`. Fetch one type for the full descriptor:

```bash theme={null}
curl https://api.aiql.io/connectors/google-drive \
  -H "Authorization: Bearer $AIQL_API_KEY"
```

Connectable types today: `google-drive`, `sharepoint`, `onedrive`, `microsoft-teams`, and `odoo`.

## Connect with an API key (Odoo)

For Odoo, pass the credential fields in the body. The connection is created immediately.

```bash theme={null}
curl -X POST https://api.aiql.io/connectors/odoo/connect \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Odoo",
    "credential": {
      "url": "https://odoo.example.com",
      "db": "prod",
      "username": "api-user",
      "api_key": "YOUR_ODOO_API_KEY"
    }
  }'
```

A successful response has `status` of `connected` and a populated `connection` object. Save `connection.id` for sync and management.

## Connect with OAuth (Google / Microsoft)

For `google-drive`, `sharepoint`, `onedrive`, and `microsoft-teams`, omit `credential_id` to start an OAuth handshake. Pass a `return_url` so the browser lands back in your app when the handshake finishes.

```bash theme={null}
curl -X POST https://api.aiql.io/connectors/google-drive/connect \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Drive",
    "config": {
      "root_folder_id": "OPTIONAL_FOLDER_ID"
    },
    "return_url": "https://your-app.example.com/connections/callback"
  }'
```

The response has `status` of `pending_authorization` and an `authorization_url`. Open that URL in the user's browser (redirect or popup). After the provider consent screen, AiQL completes the handshake and redirects to your `return_url` with `?status=success|error&connection_id=...` appended.

Microsoft Teams also requires `tenant_id` in `config` to start admin consent:

```bash theme={null}
curl -X POST https://api.aiql.io/connectors/microsoft-teams/connect \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Teams",
    "config": {
      "tenant_id": "YOUR_TENANT_ID"
    },
    "return_url": "https://your-app.example.com/connections/callback"
  }'
```

To reuse an existing credential instead of starting a new OAuth flow, pass `credential_id` from a previous connection. That path returns `status: "connected"` immediately, the same as Odoo.

## List and get connections

```bash theme={null}
curl https://api.aiql.io/connections \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"

curl https://api.aiql.io/connections/YOUR_CONNECTION_ID \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"
```

Each connection includes `connector_type`, `name`, `config`, `change_token`, and `last_synced_at`.

## Update a connection

Rename the connection or adjust connector-specific config (for example `root_folder_id` for Google Drive, or `site_id` / `drive_id` for SharePoint).

```bash theme={null}
curl -X PATCH https://api.aiql.io/connections/YOUR_CONNECTION_ID \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "Team Drive (Finance)"}'
```

## Sync a connection

Start a sync workflow. The endpoint returns `202` with Temporal identifiers while the sync runs asynchronously.

```bash theme={null}
curl -X POST https://api.aiql.io/connections/YOUR_CONNECTION_ID/sync \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false}'
```

Set `dry_run` to `true` to enumerate changes without persisting new or updated documents. After a successful sync, `last_synced_at` and `change_token` on the connection update so the next sync can run incrementally.

## Delete a connection

```bash theme={null}
curl -X DELETE https://api.aiql.io/connections/YOUR_CONNECTION_ID \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"
```

Deletion removes the connection and its attached credential.

<Tip>
  Prefer OAuth with a `return_url` for browser-based apps. For headless or automation flows, use Odoo credentials or reuse an existing `credential_id` from a prior OAuth connect.
</Tip>