> ## Documentation Index
> Fetch the complete documentation index at: https://outlit-codex-platform-actions-create-update-cli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Routes

> List, connect, disconnect, poll, and inspect integration sync status

Every integration request requires an Outlit API key:

```http theme={null}
Authorization: Bearer ok_...
```

## Provider IDs

Use the currently enabled public provider IDs below when calling integration routes.

| Provider ID       | Name            | Category      | Direct config support           |
| ----------------- | --------------- | ------------- | ------------------------------- |
| `hubspot`         | HubSpot         | CRM           | Browser session                 |
| `attio`           | Attio           | CRM           | Browser session                 |
| `slack`           | Slack           | Communication | Browser session                 |
| `fireflies`       | Fireflies.ai    | Calls         | `apiKey`                        |
| `granola`         | Granola         | Calls         | `apiKey`                        |
| `google-calendar` | Google Calendar | Calendar      | Browser session                 |
| `google-mail`     | Gmail           | Communication | Browser session                 |
| `posthog`         | PostHog         | Analytics     | `apiKey`, `region`, `projectId` |
| `stripe`          | Stripe          | Billing       | `apiKey`                        |
| `supabase`        | Supabase Auth   | Analytics     | `projectUrl`, `serviceRoleKey`  |
| `clerk`           | Clerk           | Analytics     | `secretKey`                     |
| `pylon`           | Pylon           | Support       | `apiToken`                      |

<Info>
  Use `google-mail` for direct API requests. The CLI also accepts `gmail` as a convenience alias.
</Info>

## List Integrations

```http theme={null}
GET https://app.outlit.ai/api/integrations
```

<ParamField query="connectedOnly" type="boolean" default="false">
  When `true`, only returns currently connected integrations.
</ParamField>

### Example

```bash theme={null}
curl https://app.outlit.ai/api/integrations?connectedOnly=true \
  -H "Authorization: Bearer ok_your_api_key"
```

### Response

```json theme={null}
{
  "items": [
    {
      "id": "stripe",
      "name": "Stripe",
      "category": "billing",
      "status": "connected",
      "connectionId": "stripe-org_123",
      "lastDataReceivedAt": "2026-04-10T18:22:11.000Z",
      "syncStatus": "SUCCESS",
      "errorMessage": null
    }
  ]
}
```

## Get Setup Capabilities

```http theme={null}
GET https://app.outlit.ai/api/integrations/capabilities
```

<ParamField query="provider" type="string">
  Optional public provider ID or CLI alias. When omitted, returns all provider capabilities.
</ParamField>

Capabilities tell agents which setup mode to use, which credential fields are required, and which post-connect steps still need follow-up.

### Response

```json theme={null}
{
  "provider": {
    "cliName": "pylon",
    "providerId": "pylon",
    "setupMode": "direct_api_key",
    "credentialType": "api_token",
    "requiredFields": [{ "key": "apiToken", "label": "API Token", "secret": true }],
    "commands": ["outlit integrations setup pylon"],
    "postConnectSteps": [
      {
        "id": "webhook-setup",
        "required": true,
        "supported": true,
        "command": "outlit integrations setup pylon webhooks"
      }
    ]
  }
}
```

## Run Provider Setup Step

```http theme={null}
POST https://app.outlit.ai/api/integrations/setup-step
```

Use this after a provider is connected when `postConnectSteps` reports a supported follow-up such as CRM mappings or webhooks.

### Request Body

```json theme={null}
{
  "provider": "hubspot",
  "step": "mappings",
  "config": {
    "mappings": []
  }
}
```

<ParamField body="provider" type="string" required>
  Public provider ID from setup capabilities.
</ParamField>

<ParamField body="step" type="string" required>
  Follow-up step token, such as `mappings` or `webhooks`.
</ParamField>

<ParamField body="config" type="object">
  Optional step-specific config. CRM mappings use `{ "mappings": [...] }`; Stripe webhooks can use `{ "webhookSecret": "whsec_..." }`; Fireflies webhooks can use `{ "webhookSecret": "..." }`.
</ParamField>

When config is omitted, CRM mapping setup returns available pipelines and a `config_required` response. Webhook setup returns the URL, headers/secrets, required events, and status needed for manual provider setup without creating a browser session.

## Connect Integration

```http theme={null}
POST https://app.outlit.ai/api/integrations/connect
```

### Request Body

```json theme={null}
{
  "provider": "posthog",
  "config": {
    "apiKey": "phx_...",
    "region": "us",
    "projectId": "12345"
  }
}
```

<ParamField body="provider" type="string" required>
  Public provider ID from the provider table.
</ParamField>

<ParamField body="config" type="object">
  Required for direct credential connections. Omit this field to create a browser-auth connection session.
</ParamField>

### Direct Credential Response

```json theme={null}
{
  "connected": true,
  "connectionId": "posthog-org_123",
  "alreadyConnected": false
}
```

### Browser Session Response

```json theme={null}
{
  "sessionId": "0f6d0f76-1dc7-4c5c-bba5-6685f74a5e3a",
  "connectUrl": "https://app.outlit.ai/integrations",
  "alreadyConnected": false
}
```

Open `connectUrl` in a browser where the user can complete the provider connection, then poll the connect status route with `sessionId`. Direct credential setup, such as Pylon API-token setup, returns the direct credential response and does not create a session ID.

### Errors

Invalid providers or malformed JSON return `400`. Connection-limit failures return `403`:

```json theme={null}
{
  "error": "Your plan has reached its integration connection limit.",
  "code": "plan_connection_limit_exceeded",
  "feature": "integration_connections",
  "plan": "free",
  "currentConnections": 3,
  "limit": 3
}
```

## Poll Connection Status

```http theme={null}
GET https://app.outlit.ai/api/integrations/connect/status
```

<ParamField query="sessionId" type="string" required>
  Session ID returned by `POST /api/integrations/connect`.
</ParamField>

### Response

```json theme={null}
{
  "status": "pending",
  "provider": "slack"
}
```

`status` is one of `pending`, `connected`, `failed`, or `expired`. Failed responses may include `error`.

## Disconnect Integration

```http theme={null}
POST https://app.outlit.ai/api/integrations/disconnect
```

### Request Body

```json theme={null}
{
  "provider": "stripe"
}
```

<ParamField body="provider" type="string" required>
  Public provider ID from the provider table.
</ParamField>

### Response

```json theme={null}
{
  "success": true
}
```

If the provider is valid but not currently connected, the route returns `404`:

```json theme={null}
{
  "success": false,
  "message": "Integration is not connected"
}
```

## Get Sync Status

```http theme={null}
GET https://app.outlit.ai/api/integrations/sync-status
```

<ParamField query="provider" type="string" required>
  Public provider ID from the provider table.
</ParamField>

### Response

```json theme={null}
{
  "provider": "stripe",
  "name": "Stripe",
  "category": "billing",
  "status": "connected",
  "syncs": [
    {
      "model": "StripeCustomer",
      "status": "SUCCESS",
      "lastSyncedAt": "2026-04-10T18:22:11.000Z",
      "errorMessage": null
    }
  ]
}
```

When the provider is valid but not connected, the route returns:

```json theme={null}
{
  "provider": "stripe",
  "name": "Stripe",
  "category": "billing",
  "status": "not_connected",
  "syncs": []
}
```