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

# Integrations

> Connect thinnestAI to your existing tools and services — Google Workspace, CRMs, communication platforms, and more via OAuth and API keys.

# Integrations

thinnestAI connects to dozens of external services. Integrations provide your agents with real-world capabilities — reading emails, scheduling meetings, querying databases, and interacting with your existing business tools.

## Integration Types

| Type                  | Setup                            | Example                                    |
| --------------------- | -------------------------------- | ------------------------------------------ |
| **OAuth**             | Browser-based authorization flow | Google Workspace (Gmail, Calendar, Sheets) |
| **API Key**           | Paste an API key in settings     | Firecrawl, Tavily, OpenWeather             |
| **Connection String** | Database connection URL          | PostgreSQL, BigQuery                       |
| **Webhook**           | Register a webhook URL           | CRM webhooks, custom APIs                  |

## Google Workspace (OAuth)

### Gmail

Connect Gmail to let your agents read, search, send, and draft emails.

**Setup:**

1. Go to **Settings > Integrations > Google**.
2. Click **Connect Gmail**.
3. Sign in with your Google account.
4. Grant the requested permissions.
5. Select which agents can use this connection.

**Capabilities:**

* Read inbox messages
* Search by subject, sender, date
* Send emails
* Create drafts
* Reply to threads

See [Gmail Tool Guide](/docs/tools/gmail) for detailed usage.

### Google Calendar

Connect Google Calendar for appointment scheduling and availability checking.

**Setup:**

1. Go to **Settings > Integrations > Google**.
2. Click **Connect Google Calendar**.
3. Authorize access to your calendar.

**Capabilities:**

* List upcoming events
* Check availability for time slots
* Create new events
* Update or cancel existing events
* Handle recurring events

See [Google Calendar Tool Guide](/docs/tools/google-calendar) for detailed usage.

### Google Sheets

Connect Google Sheets for reading and writing spreadsheet data.

**Setup:**

1. Go to **Settings > Integrations > Google**.
2. Click **Connect Google Sheets**.
3. Authorize access.

**Capabilities:**

* Read spreadsheet data
* Write rows and cells
* Search across sheets
* Append data to sheets

See [Google Sheets Tool Guide](/docs/tools/google-sheets) for detailed usage.

## API Key Integrations

Configure API keys for third-party services in **Settings > Integrations**.

### Managing Integration Keys

```bash theme={null}
# Store an integration key
curl -X POST https://api.thinnest.ai/integration-keys \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "firecrawl",
    "key_value": "fc-xxxxxxxxxxxxx",
    "name": "Firecrawl Production Key"
  }'
```

Keys are encrypted at rest using the platform's encryption key.

### Supported Services

| Service         | Key Name      | Description                    |
| --------------- | ------------- | ------------------------------ |
| **Firecrawl**   | `firecrawl`   | Web scraping with JS rendering |
| **Tavily**      | `tavily`      | AI-optimized web search        |
| **Exa**         | `exa`         | Neural search engine           |
| **Serper**      | `serper`      | Google Search API              |
| **JinaReader**  | `jina`        | URL-to-text conversion         |
| **Spider**      | `spider`      | High-performance web crawler   |
| **Cal.com**     | `calcom`      | Scheduling platform            |
| **ElevenLabs**  | `elevenlabs`  | Text-to-speech                 |
| **Replicate**   | `replicate`   | AI model inference             |
| **OpenWeather** | `openweather` | Weather data                   |
| **Google Maps** | `google_maps` | Location and directions        |

## CRM Integrations

### Webhook-Based CRM

Connect any CRM that supports webhooks:

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/agent_abc123/tools \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "crm_webhook",
    "config": {
      "webhook_url": "https://your-crm.com/api/webhook",
      "auth_header": "Bearer your-crm-token",
      "actions": ["create_contact", "update_contact", "get_contact"]
    }
  }'
```

### Supported CRM Platforms

| Platform           | Integration Type | Features                              |
| ------------------ | ---------------- | ------------------------------------- |
| **HubSpot**        | API Key          | Contacts, deals, companies, pipelines |
| **Salesforce**     | OAuth            | Full CRM operations                   |
| **ActiveCampaign** | API Key          | Contacts, campaigns, automations      |
| **Apollo**         | API Key          | Lead enrichment, contact search       |

## Communication Integrations

| Platform            | Type      | Setup                             |
| ------------------- | --------- | --------------------------------- |
| **Slack**           | Bot Token | Install Slack app, get bot token  |
| **Discord**         | Bot Token | Create Discord bot, add to server |
| **Telegram**        | Bot Token | Create bot via @BotFather         |
| **Microsoft Teams** | OAuth     | Register Azure AD app             |
| **Twilio**          | API Key   | Account SID + Auth Token          |

### SMS Configuration

Multiple SMS providers are supported:

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/agent_abc123/tools \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "config": {
      "provider": "twilio",
      "account_sid": "ACxxxxx",
      "auth_token": "xxxxx",
      "from_number": "+14155551234"
    }
  }'
```

See [SMS Tool Guide](/docs/tools/sms) for detailed setup.

## Database Integrations

Connect directly to databases for real-time data access:

| Database       | Connection                            |
| -------------- | ------------------------------------- |
| **PostgreSQL** | `postgresql://user:pass@host:5432/db` |
| **BigQuery**   | Google Cloud credentials              |
| **DuckDB**     | In-memory or file-based               |

### Test Database Connection

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/agent_abc123/tools/test-connection \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "postgres",
    "config": {
      "connection_string": "postgresql://user:pass@host:5432/mydb"
    }
  }'
```

## Webhook Integrations

Create custom integrations using webhooks:

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/agent_abc123/tools \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http_request",
    "config": {
      "base_url": "https://api.your-service.com",
      "headers": {
        "Authorization": "Bearer your-token"
      },
      "endpoints": [
        {
          "name": "get_customer",
          "method": "GET",
          "path": "/customers/{id}",
          "description": "Look up a customer by ID"
        },
        {
          "name": "create_ticket",
          "method": "POST",
          "path": "/tickets",
          "description": "Create a support ticket"
        }
      ]
    }
  }'
```

Your agent can then call these endpoints during conversations.

## Security

* **API keys are encrypted** at rest using AES encryption
* **OAuth tokens are refreshed** automatically when they expire
* **Connection strings are never exposed** in API responses
* **Origin restrictions** for widget integrations prevent unauthorized access
* **Integration keys can be rotated** without downtime

## Managing Integrations

### List All Integrations

```bash theme={null}
curl https://api.thinnest.ai/integration-keys \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

### Delete an Integration

```bash theme={null}
curl -X DELETE https://api.thinnest.ai/integration-keys/42 \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

## Best Practices

* **Use separate keys for dev and production** — Never share API keys across environments.
* **Rotate keys regularly** — Especially for sensitive integrations like CRMs and payment systems.
* **Test connections before deploying** — Use the test endpoint to verify database and API connections.
* **Limit permissions** — When setting up OAuth, grant only the scopes your agent needs.
* **Monitor usage** — Track which integrations your agents use most in analytics.