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

# Integrations

List, install, configure, and disconnect third-party integrations (Slack, Shopify, Stripe, Linear, GitHub, Discord).

# Integrations API

The v1 surface covers what's headless-friendly: list, browse catalog,
get install URL, update lifecycle, disconnect. The OAuth handshake
itself still needs a real browser.

## Endpoints

| Method | Path | Scope |
|--------|------|-------|
| `GET` | `/v1/projects/{projectId}/integrations` | `read` |
| `GET` | `/v1/projects/{projectId}/integrations/catalog` | `read` |
| `GET` | `/v1/projects/{projectId}/integrations/catalog/{provider}` | `read` |
| `POST` | `/v1/projects/{projectId}/integrations/{provider}/install-url` | `integrations:write` |
| `PATCH` | `/v1/projects/{projectId}/integrations/{provider}/lifecycle` | `integrations:write` |
| `DELETE` | `/v1/projects/{projectId}/integrations/{provider}` | `integrations:write` |

## List installed

```bash cURL
curl https://api.rogeriq.com/api/v1/projects/prj_xxx/integrations \
  -H "X-API-Key: riq_xxx"
```

```bash CLI
rogeriq integrations list
```

```ts SDK
const installed = await roger.integrations.list();
```

```json
{
  "data": [
    {
      "id": "int_xxx",
      "provider": "slack",
      "status": "active",
      "display_name": "Acme Workspace",
      "setup_type": "oauth",
      "health_status": "healthy",
      "sidebar_enabled": true,
      "last_synced_at": "2026-05-17T17:55:00Z",
      "error_message": null,
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-05-17T17:55:00Z"
    }
  ]
}
```

## Browse catalog

```bash
curl 'https://api.rogeriq.com/api/v1/projects/prj_xxx/integrations/catalog?category=commerce&status=available' \
  -H "X-API-Key: riq_xxx"
```

Returns every catalog entry — installed and available — with health and
sync metadata.

Filters: `q` (free text), `category`, `status`.

## Get install URL

OAuth installs require a real browser. The v1 API returns a dashboard
URL that the user opens:

```bash
curl -X POST https://api.rogeriq.com/api/v1/projects/prj_xxx/integrations/slack/install-url \
  -H "X-API-Key: riq_xxx"
```

```json
{
  "data": {
    "provider": "slack",
    "install_url": "https://rogeriq.com/dashboard/projects/prj_xxx/integrations/slack",
    "setup_type": "oauth",
    "message": "Open the URL above in a browser to complete installation."
  }
}
```

For non-OAuth providers (API key, webhook URL) the dashboard collects
the credential and stores it server-side.

## Update lifecycle

Toggle status, change display name, hide / show in the inbox sidebar,
patch settings:

```bash cURL
curl -X PATCH https://api.rogeriq.com/api/v1/projects/prj_xxx/integrations/shopify/lifecycle \
  -H "X-API-Key: riq_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "display_name": "Acme Store",
    "sidebar_enabled": true,
    "settings": {"refunds_enabled": true}
  }'
```

```bash CLI
rogeriq integrations lifecycle shopify \
  --status active --display-name "Acme Store" --sidebar true \
  --settings '{"refunds_enabled":true}'
```

`active`, `paused`, `disconnected`.
Override the catalog name shown in the dashboard / sidebar.
Show this integration's panel in the inbox sidebar.
Provider-specific JSON merged into the integration's settings.
Which agent actions this integration is allowed to perform
  (e.g. issue refunds, cancel orders).

## Disconnect

```bash
curl -X DELETE https://api.rogeriq.com/api/v1/projects/prj_xxx/integrations/slack \
  -H "X-API-Key: riq_xxx"
```

Sets status to `disconnected`, hides the sidebar, clears health status.
Existing OAuth tokens are NOT revoked at the provider — handle that in
the provider's own settings if needed.

## Providers in the catalog

Slack, Discord, Shopify, Stripe, Linear, GitHub, Notion, Cal.com,
HubSpot, Pipedrive, Salesforce, Zendesk, Mailgun, Postmark, ... see
`/v1/projects/.../integrations/catalog` for the full live list.

## Audit

Lifecycle changes and disconnects are recorded in the audit log as
`integration.lifecycle.updated` / `integration.disconnected` with the
acting API key id.