Connections API
Overview
Manage platform connections (Slack, Discord, etc.) to sync messages.
GET /api/connections
List all platform connections.
Response
[
{
"id": "conn_123",
"name": "Engineering Workspace",
"platform": "slack",
"status": "connected",
"created_at": "2026-01-01T00:00:00Z",
"last_sync": "2026-04-13T10:30:00Z",
"channel_count": 15
}
]Status Values
connected- Active connectiondisconnected- Disconnected (can reconnect)error- Error state (requires attention)
GET /api/connections/{connection_id}
Get connection details.
Parameters
Prop
Type
Response
{
"id": "conn_123",
"name": "Engineering Workspace",
"platform": "slack",
"status": "connected",
"created_at": "2026-01-01T00:00:00Z",
"last_sync": "2026-04-13T10:30:00Z",
"channel_count": 15,
"settings": {
"sync_interval_minutes": 240,
"wiki_enabled": true,
"graph_enabled": true
}
}POST /api/connections
Create a new platform connection.
Request Body
{
"platform": "slack",
"name": "Engineering Workspace",
"credentials": {
"bot_token": "xoxb-...",
"signing_secret": "..."
}
}Parameters
Prop
Type
Slack Credentials
{
"bot_token": "xoxb-...",
"signing_secret": "..."
}Discord Credentials
{
"bot_token": "...",
"guild_id": "..."
}Response
{
"id": "conn_123",
"name": "Engineering Workspace",
"platform": "slack",
"status": "connected",
"created_at": "2026-04-13T10:30:00Z",
"channel_count": 15
}PUT /api/connections/{connection_id}
Update a connection.
Request Body
{
"name": "Updated Name",
"credentials": {
"bot_token": "xoxb-...",
"signing_secret": "..."
}
}DELETE /api/connections/{connection_id}
Delete a connection.
Parameters
Prop
Type
Response
Status: 204 No Content
POST /api/connections/{connection_id}/validate
Validate connection credentials.
Parameters
Prop
Type
Response
{
"valid": true,
"connection": {
"id": "conn_123",
"status": "connected",
"validated_at": "2026-04-13T10:30:00Z"
}
}Error Response
{
"valid": false,
"error": {
"code": "INVALID_CREDENTIALS",
"message": "Bot token is invalid or expired"
}
}GET /api/connections/{connection_id}/channels
Get channels for a connection.
Parameters
Prop
Type
Response
[
{
"id": "C12345",
"name": "#engineering",
"is_private": false,
"member_count": 15,
"sync_enabled": true
}
]PUT /api/connections/{connection_id}/channels
Update which channels to sync.
Request Body
{
"channel_ids": ["C12345", "C67890"],
"sync_all": false
}Parameters
Prop
Type
Connection Errors
Error Codes
| Code | Description |
|---|---|
INVALID_CREDENTIALS | Provided credentials are invalid |
AUTH_EXPIRED | Authentication token expired |
RATE_LIMITED | Platform rate limit |
INSUFFICIENT_PERMISSIONS | Bot lacks required scopes |
NETWORK_ERROR | Network connectivity issue |
PLATFORM_ERROR | Platform API error |
Example Error Response
{
"valid": false,
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"message": "Bot lacks required scopes: channels:history, channels:read",
"required_scopes": [
"channels:history",
"channels:read",
"users:read"
]
}
}Best Practices
- Secure Credentials: Store credentials securely, never log them
- Validate First: Always validate connections before saving
- Handle Errors: Implement proper error handling for all connection operations
- Check Permissions: Ensure bot has required scopes
- Monitor Status: Regularly check connection status and re-authenticate when needed
- Use Webhooks: Configure webhooks for real-time updates (if supported)
Required Bot Scopes
Slack
channels:history- Read message historychannels:read- View channel informationusers:read- View user informationfiles:read- Access file metadatalinks:read:write- Unfurl links
Discord
guild.messages- Read guild messagesguild.channels- View guild channelsguild.members- View guild members
How is this guide?