> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# Integrations

`/api/v1` operations for integrations. See [HTTP API](/api/) for authentication, the error envelope, and rate limits.

## Operations

### GET /api/v1/integrations

List integrations

Returns the organization's connected mailbox integrations (first-party, org-owned). Responses never include token material; use the token endpoint to mint an access token.

Auth: API key required.

Operation ID: `listIntegrations`

Responses:
- `200` — The organization's integrations.
- `401` — Authentication is missing or invalid.
- `429` — Too many requests; retry after the indicated delay.

CLI: `khotan integrations list`

### POST /api/v1/integrations

Start connecting an integration

Begins a Gmail (`google`) or Outlook (`microsoft`) mailbox connection and returns a connect URL. The provider defaults to `google`. OAuth consent happens in a browser, so a human must open the returned URL to authorize; the connection appears in the list once approved. Returns 503 provider_not_configured when the requested provider is not configured in this environment.

Auth: API key required.

Operation ID: `connectIntegration`

Request body (`application/json`, required):
- `provider` ("google" | "microsoft", optional)

Responses:
- `200` — A connect URL for the requested provider.
- `400` — The request was malformed or failed validation.
- `401` — Authentication is missing or invalid.
- `404` — The resource was not found.
- `429` — Too many requests; retry after the indicated delay.
- `503` — Response.

CLI: `khotan integrations connect`

### GET /api/v1/integrations/{integrationId}

Get an integration

Returns one connected mailbox integration. Responses never include token material.

Auth: API key required.

Operation ID: `getIntegration`

Path parameters:
- `integrationId` (string, required)

Responses:
- `200` — The integration.
- `401` — Authentication is missing or invalid.
- `404` — The resource was not found.
- `429` — Too many requests; retry after the indicated delay.

CLI: `khotan integrations get`

### PATCH /api/v1/integrations/{integrationId}

Update an integration

Updates an integration's display name. Pass null to clear it. Tokens and the mailbox are fixed by OAuth and cannot be changed.

Auth: API key required.

Operation ID: `updateIntegration`

Path parameters:
- `integrationId` (string, required)

Request body (`application/json`, required):
- `name` (string | null, required)

Responses:
- `200` — The updated integration.
- `400` — The request was malformed or failed validation.
- `401` — Authentication is missing or invalid.
- `404` — The resource was not found.
- `429` — Too many requests; retry after the indicated delay.

CLI: `khotan integrations rename`

### DELETE /api/v1/integrations/{integrationId}

Disconnect an integration

Disconnects a mailbox: the stored credentials are revoked and the connection stops driving sync. This is permanent; reconnecting requires a fresh OAuth consent.

Auth: API key required.

Operation ID: `deleteIntegration`

Path parameters:
- `integrationId` (string, required)

Responses:
- `200` — The integration was disconnected.
- `401` — Authentication is missing or invalid.
- `404` — The resource was not found.
- `429` — Too many requests; retry after the indicated delay.

CLI: `khotan integrations delete`

### POST /api/v1/integrations/{integrationId}/token

Mint an access token (secret)

Mints a fresh, short-lived OAuth access token for a Gmail or Outlook integration using its stored refresh token, and returns it with its expiry and scopes. The token grants access to the connected mailbox; treat it as a secret. Returns 409 connection_unusable if the grant was revoked at the provider, and 503 provider_not_configured if the integration's provider is not configured in this environment.

Auth: API key required.

Operation ID: `mintIntegrationToken`

Path parameters:
- `integrationId` (string, required)

Responses:
- `200` — A freshly-minted access token. Secret-bearing.
- `400` — The request was malformed or failed validation.
- `401` — Authentication is missing or invalid.
- `404` — The resource was not found.
- `409` — Response.
- `429` — Too many requests; retry after the indicated delay.
- `503` — Response.

CLI: `khotan integrations token`

<!-- generated from the /api/v1 OpenAPI spec v1.0.0 (adapter 0.10.0); do not edit by hand -->