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

# Connectors

> Discover connected-app integrations and manage account connections.

Connectors are the connected apps that chats and agents can use. The catalog describes available integrations; connection endpoints bind an account to the current user or an API-served external subject.

<Note>
  Catalog and connection endpoints are **\[User+Key]**. API keys use `connectors:read`, `connectors:write`, or `connectors:delete`. The provider callback is public and validates its signed state.
</Note>

## Endpoints

| Method   | Path                           | Description                     | Auth               |
| -------- | ------------------------------ | ------------------------------- | ------------------ |
| `GET`    | `/connectors/catalog`          | List available connectors       | \[User+Key]        |
| `POST`   | `/connectors/catalog/by-slugs` | Get catalog entries by slug     | \[User+Key]        |
| `POST`   | `/connectors/status`           | Check connection status         | \[User+Key]        |
| `POST`   | `/connectors/add`              | Start an account connection     | \[User+Key]        |
| `DELETE` | `/connectors/:slug`            | Disconnect an account           | \[User+Key]        |
| `GET`    | `/connectors/auth/callback`    | Complete provider authorization | \[Public callback] |

## List the catalog

`GET /connectors/catalog`

<ParamField query="offset" type="number">
  Zero-based pagination offset.
</ParamField>

<ParamField query="limit" type="number">
  Page size from 1 to 100.
</ParamField>

```bash theme={null}
curl "$AUTOSAGE_URL/connectors/catalog?limit=25" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

The response contains connector records with their canonical `slug`, display name, description, logo, and category, plus pagination fields.

## Get connectors by slug

`POST /connectors/catalog/by-slugs`

<ParamField body="slugs" type="string[]" required>
  Between 1 and 100 canonical connector slugs.
</ParamField>

```bash theme={null}
curl -X POST "$AUTOSAGE_URL/connectors/catalog/by-slugs" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slugs": ["gmail", "slack"] }'
```

## Check connection status

`POST /connectors/status`

<ParamField body="slugs" type="string[]" required>
  Connector slugs to inspect.
</ParamField>

<ParamField body="tenant_id" type="string">
  Tenant for an API-key-based connection.
</ParamField>

<ParamField body="external_subject_id" type="string">
  Non-PII identifier for the API-served end user who owns the connection.
</ParamField>

```bash theme={null}
curl -X POST "$AUTOSAGE_URL/connectors/status" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slugs": ["gmail"],
    "tenant_id": "TENANT_ID",
    "external_subject_id": "CUSTOMER_123"
  }'
```

<Warning>
  Use a stable, non-PII `external_subject_id`. A different value resolves to a different connected-app identity and cannot access the original subject's connection.
</Warning>

## Connect an account

`POST /connectors/add`

<ParamField body="slug" type="string" required>
  Canonical connector slug.
</ParamField>

<ParamField body="tenant_id" type="string">
  Tenant for API-key authentication.
</ParamField>

<ParamField body="external_subject_id" type="string">
  External end user who will own the connection.
</ParamField>

<ParamField body="redirect_url" type="string">
  Final destination after AutoSage completes the provider callback.
</ParamField>

The response includes a `redirect_url` for the account authorization flow and an `already_connected` boolean. Open the URL in the user's browser.

## Disconnect an account

`DELETE /connectors/:slug`

For API-key calls, pass `tenant_id` and `external_subject_id` as query parameters so AutoSage resolves the same connection owner used during setup.

```bash theme={null}
curl -X DELETE \
  "$AUTOSAGE_URL/connectors/gmail?tenant_id=TENANT_ID&external_subject_id=CUSTOMER_123" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

## Authorization callback

`GET /connectors/auth/callback`

This browser callback receives provider status, account information, and signed state. Applications normally do not call it directly: start with `/connectors/add` and follow the returned redirect URL.

<Tip>
  Use `/swagger` for complete callback and response schemas. After connecting an account, verify it with `/connectors/status` before enabling its slug on an agent.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Configure agents" icon="plug" href="/agents/configuring">
    Enable connected apps on a deployed agent.
  </Card>

  <Card title="Agents API" icon="robot" href="/developers/api/agents">
    Check integration readiness and deploy connector slugs.
  </Card>
</CardGroup>