> ## Documentation Index
> Fetch the complete documentation index at: https://moonshadow-ep3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

Integrations connect Moonshadow to external tools such as Slack, GitHub, and Jira. Use these endpoints to discover which providers are available, connect them to your workspace, and manage their configuration and lifecycle.

***

## List Available Integrations

Returns all integration providers that you can connect to a workspace.

```bash theme={null}
curl https://api.moonshadow.dev/v1/integrations \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

<ResponseField name="data" type="array">
  Array of available integration providers.
</ResponseField>

<ResponseField name="data[].provider" type="string">
  Provider key: `slack`, `github`, `jira`, `notion`, etc.
</ResponseField>

<ResponseField name="data[].name" type="string">
  Human-readable provider name.
</ResponseField>

<ResponseField name="data[].description" type="string">
  Short description of what the integration does.
</ResponseField>

<ResponseField name="data[].required_credentials" type="array">
  List of credential fields required to connect, such as `token`, `api_key`, or `oauth`.
</ResponseField>

```json theme={null}
{
  "data": [
    {
      "provider": "slack",
      "name": "Slack",
      "description": "Send channel notifications and trigger workflows from Slack messages.",
      "required_credentials": ["token"]
    },
    {
      "provider": "github",
      "name": "GitHub",
      "description": "Sync issues, pull requests, and repository events into Moonshadow.",
      "required_credentials": ["token"]
    },
    {
      "provider": "jira",
      "name": "Jira",
      "description": "Create and track Jira issues directly from Moonshadow workflows.",
      "required_credentials": ["api_key", "domain"]
    }
  ]
}
```

***

## Connect an Integration

Connects an external provider to a workspace.

```bash theme={null}
curl -X POST https://api.moonshadow.dev/v1/integrations/connect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "slack",
    "workspace_id": "ws_abc123",
    "credentials": {
      "token": "xoxb-your-slack-bot-token"
    }
  }'
```

### Request Body

<ParamField body="provider" type="string" required>
  Provider key from the available integrations list, e.g. `slack` or `github`.
</ParamField>

<ParamField body="workspace_id" type="string" required>
  The workspace ID to connect the integration to.
</ParamField>

<ParamField body="credentials" type="object" required>
  Provider-specific credentials. Fields match `required_credentials` from the available integrations list.
</ParamField>

### Response

```json theme={null}
{
  "integration_id": "int_ghi789",
  "provider": "slack",
  "workspace_id": "ws_abc123",
  "status": "connected",
  "connected_at": "2024-06-10T17:45:00Z"
}
```

<Warning>
  Store credentials securely and rotate them regularly. Moonshadow encrypts credentials at rest, but leaked tokens can still be used against the third-party provider.
</Warning>

***

## List Connected Integrations

Returns all integrations currently connected to a workspace.

```bash theme={null}
curl https://api.moonshadow.dev/v1/workspaces/ws_abc123/integrations \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID.
</ParamField>

### Response

```json theme={null}
{
  "data": [
    {
      "integration_id": "int_ghi789",
      "provider": "slack",
      "status": "connected",
      "connected_at": "2024-06-10T17:45:00Z",
      "last_synced_at": "2024-06-10T18:00:00Z"
    },
    {
      "integration_id": "int_jkl012",
      "provider": "github",
      "status": "error",
      "connected_at": "2024-05-01T12:00:00Z",
      "last_synced_at": "2024-05-15T09:30:00Z"
    }
  ]
}
```

<ResponseField name="data[].status" type="string">
  Current connection status: `connected`, `disconnected`, or `error`.
</ResponseField>

<ResponseField name="data[].last_synced_at" type="string | null">
  ISO 8601 timestamp of the last successful data sync, or `null` if never synced.
</ResponseField>

***

## Disconnect an Integration

Removes an integration from a workspace and deletes stored credentials.

```bash theme={null}
curl -X DELETE https://api.moonshadow.dev/v1/workspaces/ws_abc123/integrations/int_ghi789 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID.
</ParamField>

<ParamField path="integrationId" type="string" required>
  The integration ID to disconnect.
</ParamField>

### Response

Returns `204 No Content` on success.

<Tip>
  Disconnecting an integration stops all event ingestion from that provider and removes associated webhooks. You can reconnect later without losing workspace configuration.
</Tip>