# Send Message
Source: https://docs.suada.ai/api-reference/chat/send-message
POST /chat
Send a message to the business analyst
Send a message to the business analyst and receive an analyzed response.
## Request
The message to analyze
Unique identifier for the user in your system
Previous messages in the conversation
```ts theme={null}
{
role: 'user' | 'assistant' | 'system'
content: string
metadata?: {
mode?: 'chat' | 'business_analyst'
agentId?: string
thoughts?: string
reasoning?: string
actions?: Array<{
tool: string
toolInput: string
log: string
}>
followUpQuestion?: string
}
timestamp?: number
}[]
```
ID of an existing conversation to continue
List of specific integrations to use
Whether to use all available integrations
Mode of operation ('chat' or 'business\_analyst')
ID of a specific agent to use
Whether to store conversation history
Whether to use passthrough integrations
## Response
The analyzed response to the message
The agent's thought process
Actions taken by the agent
```ts theme={null}
{
tool: string
toolInput: string
log: string
}[]
```
Suggested follow-up question
Reasoning behind the analysis
ID of the conversation
Unix timestamp of the response
## Example
```bash cURL theme={null}
curl -X POST https://suada.ai/api/public/chat \
-H "Authorization: Bearer sk-suada-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "What's our revenue trend?",
"externalUserIdentifier": "user-123",
"useAllIntegrations": true,
"mode": "business_analyst"
}'
```
```typescript TypeScript theme={null}
import { Suada } from '@suada/node';
const suada = new Suada({
apiKey: 'your-api-key'
});
const response = await suada.chat({
message: "What's our revenue trend?",
externalUserIdentifier: 'user-123',
useAllIntegrations: true,
mode: 'business_analyst'
});
```
```python Python theme={null}
from suada import Suada, SuadaConfig, ChatPayload
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
response = suada.chat(
payload=ChatPayload(
message="What's our revenue trend?",
external_user_identifier="user-123",
use_all_integrations=True,
mode="business_analyst"
)
)
```
```json theme={null}
{
"answer": "Based on our analysis of recent data, your revenue shows a positive trend with a 15% growth rate over the last quarter...",
"thoughts": "Analyzing revenue data from multiple sources including Google Analytics and Zoho CRM...",
"actions": [
{
"tool": "google_analytics",
"toolInput": "query_revenue_metrics",
"log": "Retrieved revenue metrics for last quarter"
},
{
"tool": "zoho_crm",
"toolInput": "get_sales_pipeline",
"log": "Analyzed sales pipeline data"
}
],
"followUpQuestion": "Would you like to see a breakdown of revenue by product category?",
"reasoning": "The growth is primarily driven by increased enterprise sales and successful product launches",
"conversationId": "conv_123abc",
"timestamp": 1625097600000
}
```
## Error Codes
Authentication error
```json theme={null}
{
"error": "Invalid or expired API key"
}
```
Permission error
```json theme={null}
{
"error": "Insufficient permissions"
}
```
Rate limit exceeded
```json theme={null}
{
"error": "Too many requests, please try again later.",
"retryAfter": 60
}
```
## Notes
* The conversation history is automatically stored unless `privacyMode` is enabled
* When `useAllIntegrations` is true, the agent will use all available integrations for the user/organization
* The `mode` parameter determines how the message is processed:
* `business_analyst`: Full analysis with integrations
* `chat`: Simple chat response without integration data
* Rate limits apply based on your plan (see [Rate Limiting](/api-reference/overview#rate-limiting))
# Integration Callback
Source: https://docs.suada.ai/api-reference/integrations/callback
POST /integrations/{integrationType}/callback
Handle OAuth callback for an integration
Complete the OAuth flow for a third-party integration.
## URL Parameters
The type of integration being connected. Valid values:
* `google-analytics`
* `notion`
* `slack`
* `zoho`
* `gmail`
## Request
The OAuth authorization code
The state parameter from the OAuth flow
## Response
The response format varies by integration type:
### Google Analytics
Whether the callback was successful
Success or error message
List of available Google Analytics properties
```ts theme={null}
{
id: string
name: string
websiteUrl: string
}[]
```
Temporary token for property selection
The redirect URI provided during connection
### Notion
Whether the callback was successful
Success or error message
Connected Notion workspace details
```ts theme={null}
{
id: string
name: string
icon: string
}
```
The redirect URI provided during connection
### Slack
Whether the callback was successful
Success or error message
Connected Slack team details
```ts theme={null}
{
id: string
name: string
domain: string
}
```
The redirect URI provided during connection
### Zoho
Whether the callback was successful
Success or error message
Connected Zoho organization details
```ts theme={null}
{
id: string
name: string
modules: string[]
}
```
The redirect URI provided during connection
### Gmail
Whether the callback was successful
Success or error message
The redirect URI provided during connection
## Example
```bash cURL theme={null}
curl -X POST https://suada.ai/api/public/integrations/notion/callback \
-H "Content-Type: application/json" \
-d '{
"code": "oauth-code-from-provider",
"state": "oauth-state-from-provider"
}'
```
```typescript TypeScript theme={null}
import { Suada } from '@suada/node';
const suada = new Suada({
apiKey: 'your-api-key'
});
const result = await suada.handleIntegrationCallback('notion', {
code: 'oauth-code-from-provider',
state: 'oauth-state-from-provider'
});
// Redirect user back to their application
window.location.href = result.passthroughRedirectUri;
```
```python Python theme={null}
from suada import Suada, SuadaConfig
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
result = suada.handle_integration_callback(
integration_type="notion",
code="oauth-code-from-provider",
state="oauth-state-from-provider"
)
# Redirect user back to result.passthrough_redirect_uri
```
```json theme={null}
{
"success": true,
"message": "Notion workspace connected successfully",
"workspace": {
"id": "workspace-id",
"name": "My Workspace",
"icon": "https://notion.so/icons/workspace.png"
},
"passthroughRedirectUri": "https://your-app.com/oauth/callback"
}
```
## Error Codes
Invalid request
```json theme={null}
{
"error": "Missing required parameters"
}
```
Invalid OAuth code or state
```json theme={null}
{
"error": "Invalid OAuth code"
}
```
Server error
```json theme={null}
{
"error": "Failed to complete OAuth flow"
}
```
## Notes
* This endpoint should be called after receiving the OAuth callback from the integration provider
* The `state` parameter is used to verify the OAuth flow and prevent CSRF attacks
* For Google Analytics, you'll need to make an additional call to [select a property](/api-reference/integrations/select-property)
* After successful callback, redirect the user to the `passthroughRedirectUri` provided during connection
* The integration will be automatically enabled for the user after successful callback
# Connect Integration
Source: https://docs.suada.ai/api-reference/integrations/connect
POST /integrations/{integrationType}/connect
Initialize OAuth flow for an integration
Start the OAuth flow to connect a third-party integration.
## URL Parameters
The type of integration to connect. Valid values:
* `google-analytics`
* `notion`
* `slack`
* `zoho`
* `gmail`
## Request
Unique identifier for the user in your system
The URL to redirect to after OAuth completion
Data center for Zoho integration (e.g., 'com', 'eu')
Additional OAuth scopes for Zoho integration
## Response
The OAuth authorization URL to redirect the user to
## Example
```bash cURL theme={null}
curl -X POST https://suada.ai/api/public/integrations/notion/connect \
-H "Authorization: Bearer sk-suada-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"externalUserIdentifier": "user-123",
"passthroughRedirectUri": "https://your-app.com/oauth/callback"
}'
```
```typescript TypeScript theme={null}
import { Suada } from '@suada/node';
const suada = new Suada({
apiKey: 'your-api-key'
});
const { authUrl } = await suada.connectIntegration('notion', {
externalUserIdentifier: 'user-123',
passthroughRedirectUri: 'https://your-app.com/oauth/callback'
});
// Redirect user to authUrl
window.location.href = authUrl;
```
```python Python theme={null}
from suada import Suada, SuadaConfig
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
result = suada.connect_integration(
integration_type="notion",
external_user_identifier="user-123",
passthrough_redirect_uri="https://your-app.com/oauth/callback"
)
# Redirect user to result.auth_url
```
```json theme={null}
{
"authUrl": "https://api.notion.com/v1/oauth/authorize?client_id=..."
}
```
## Integration-Specific Parameters
### Google Analytics
No additional parameters required.
### Notion
No additional parameters required.
### Slack
No additional parameters required.
### Zoho
Zoho data center:
* `com` - US data center
* `eu` - EU data center
* `in` - India data center
* `com.cn` - China data center
* `com.au` - Australia data center
List of Zoho API scopes to request. Default scopes include:
* `ZohoCRM.modules.ALL`
* `ZohoBooks.fullaccess.ALL`
* `ZohoProjects.projects.ALL`
### Gmail
No additional parameters required.
## Error Codes
Invalid request
```json theme={null}
{
"error": "Missing required parameters"
}
```
Authentication error
```json theme={null}
{
"error": "Invalid or expired API key"
}
```
Server error
```json theme={null}
{
"error": "Failed to initialize OAuth flow"
}
```
## Notes
* The OAuth flow is a multi-step process:
1. Call this endpoint to get the authorization URL
2. Redirect the user to the authorization URL
3. User authorizes your application
4. Integration provider redirects to your callback URL
5. Call the [callback endpoint](/api-reference/integrations/callback) to complete the flow
* The `passthroughRedirectUri` should be a URL in your application that can handle the OAuth callback
* Store the `externalUserIdentifier` to associate the integration with the correct user after the callback
# Disconnect Integration
Source: https://docs.suada.ai/api-reference/integrations/disconnect
POST /integrations/{integrationType}/disconnect
Disconnect a third-party integration
Disconnect and disable a third-party integration for a specific user.
## URL Parameters
The type of integration to disconnect. Valid values:
* `google-analytics`
* `notion`
* `slack`
* `zoho`
* `gmail`
## Request
Unique identifier for the user in your system
## Response
Whether the disconnection was successful
## Example
```bash cURL theme={null}
curl -X POST https://suada.ai/api/public/integrations/notion/disconnect \
-H "Authorization: Bearer sk-suada-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"externalUserIdentifier": "user-123"
}'
```
```typescript TypeScript theme={null}
import { Suada } from '@suada/node';
const suada = new Suada({
apiKey: 'your-api-key'
});
const result = await suada.disconnectIntegration('notion', {
externalUserIdentifier: 'user-123'
});
```
```python Python theme={null}
from suada import Suada, SuadaConfig
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
result = suada.disconnect_integration(
integration_type="notion",
external_user_identifier="user-123"
)
```
```json theme={null}
{
"success": true
}
```
## Error Codes
Invalid request
```json theme={null}
{
"error": "Missing required parameters"
}
```
Authentication error
```json theme={null}
{
"error": "Invalid or expired API key"
}
```
Integration not found
```json theme={null}
{
"error": "Integration not found"
}
```
Server error
```json theme={null}
{
"error": "Failed to disconnect integration"
}
```
## Notes
* This endpoint disables the integration but preserves its configuration
* The integration can be re-enabled by going through the connection flow again
* Any ongoing data synchronization will be stopped
* Access tokens and other credentials are revoked
* The integration's status will be updated to reflect the disconnection
# List Integrations
Source: https://docs.suada.ai/api-reference/integrations/list
GET /integrations/available
Get a list of available integrations
Returns a list of all available integrations and their capabilities.
## Response
Google Analytics integration details
```ts theme={null}
{
name: string
icon: string
description: string
capabilities: string[]
requiresPropertySelection: boolean
}
```
Notion integration details
```ts theme={null}
{
name: string
icon: string
description: string
capabilities: string[]
}
```
Slack integration details
```ts theme={null}
{
name: string
icon: string
description: string
capabilities: string[]
}
```
Zoho integration details
```ts theme={null}
{
name: string
icon: string
description: string
capabilities: string[]
}
```
Gmail integration details
```ts theme={null}
{
name: string
icon: string
description: string
capabilities: string[]
}
```
## Example
```bash cURL theme={null}
curl https://suada.ai/api/public/integrations/available \
-H "Authorization: Bearer sk-suada-your-api-key"
```
```typescript TypeScript theme={null}
import { Suada } from '@suada/node';
const suada = new Suada({
apiKey: 'your-api-key'
});
const integrations = await suada.listIntegrations();
```
```python Python theme={null}
from suada import Suada, SuadaConfig
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
integrations = suada.list_integrations()
```
```json theme={null}
{
"google-analytics": {
"name": "Google Analytics",
"icon": "https://www.google.com/favicon.ico",
"description": "Connect your Google Analytics account to analyze website traffic and user behavior.",
"capabilities": [
"Website traffic analysis",
"User behavior tracking",
"Campaign performance",
"Conversion tracking"
],
"requiresPropertySelection": true
},
"notion": {
"name": "Notion",
"icon": "https://www.notion.so/favicon.ico",
"description": "Connect your Notion workspace to access and analyze your team's knowledge base.",
"capabilities": [
"Document access",
"Knowledge base integration",
"Project tracking",
"Database access"
]
},
"slack": {
"name": "Slack",
"icon": "https://slack.com/favicon.ico",
"description": "Connect your Slack workspace to analyze team communication and collaboration.",
"capabilities": [
"Team communication analysis",
"Channel activity tracking",
"Collaboration insights",
"Message history access"
]
}
}
```
## Error Codes
Authentication error
```json theme={null}
{
"error": "Invalid or expired API key"
}
```
Server error
```json theme={null}
{
"error": "Failed to get available integrations"
}
```
## Notes
* The response includes all available integrations, regardless of whether they are currently connected
* The `capabilities` array lists the main features of each integration
* Some integrations (like Google Analytics) require additional property selection after authentication
# Select Integration Property
Source: https://docs.suada.ai/api-reference/integrations/select-property
POST /integrations/{integrationType}/select-property
Select a property for integrations that require it
Select a specific property for integrations that require additional configuration after OAuth (e.g., Google Analytics).
## URL Parameters
The type of integration. Currently supported:
* `google-analytics`
## Request
The temporary access token received from the callback
The ID of the property to select
Unique identifier for the user in your system
## Response
Whether the property selection was successful
The redirect URI provided during connection
## Example
```bash cURL theme={null}
curl -X POST https://suada.ai/api/public/integrations/google-analytics/select-property \
-H "Authorization: Bearer sk-suada-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"temporaryAccessToken": "temp-token-from-callback",
"propertyId": "123456789",
"externalUserIdentifier": "user-123"
}'
```
```typescript TypeScript theme={null}
import { Suada } from '@suada/node';
const suada = new Suada({
apiKey: 'your-api-key'
});
const result = await suada.selectIntegrationProperty('google-analytics', {
temporaryAccessToken: 'temp-token-from-callback',
propertyId: '123456789',
externalUserIdentifier: 'user-123'
});
// Redirect user back to their application
window.location.href = result.passthroughRedirectUri;
```
```python Python theme={null}
from suada import Suada, SuadaConfig
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
result = suada.select_integration_property(
integration_type="google-analytics",
temporary_access_token="temp-token-from-callback",
property_id="123456789",
external_user_identifier="user-123"
)
# Redirect user back to result.passthrough_redirect_uri
```
```json theme={null}
{
"success": true,
"passthroughRedirectUri": "https://your-app.com/oauth/callback"
}
```
## Error Codes
Invalid request
```json theme={null}
{
"error": "Missing required parameters"
}
```
Authentication error
```json theme={null}
{
"error": "Invalid or expired API key"
}
```
Invalid temporary token
```json theme={null}
{
"error": "Invalid temporary access token"
}
```
Server error
```json theme={null}
{
"error": "Failed to select property"
}
```
## Notes
* This endpoint is currently only used for Google Analytics integration
* The `temporaryAccessToken` is received from the [callback endpoint](/api-reference/integrations/callback)
* The `propertyId` should be selected from the list of properties returned in the callback response
* After successful property selection, redirect the user to the `passthroughRedirectUri`
* The integration will be automatically enabled for the user after successful property selection
# Get Integration Status
Source: https://docs.suada.ai/api-reference/integrations/status
GET /integrations/status/{externalUserIdentifier}
Get the status of all integrations for a user
Get the current status and configuration of all integrations for a specific user.
## URL Parameters
Unique identifier for the user in your system
## Response
List of integration statuses
```ts theme={null}
{
type: string
enabled: boolean
connected: boolean
lastSynced: string
// Additional fields vary by integration type
}[]
```
### Integration-Specific Fields
#### Google Analytics
Selected Google Analytics property ID
Data sync schedule
#### Notion
Connected Notion workspace name
Data sync schedule
#### Slack
Connected Slack team ID
Data sync schedule
#### Zoho
Connected Zoho organization ID
Zoho data center
Enabled Zoho modules
```ts theme={null}
{
crm: boolean
books: boolean
projects: boolean
}
```
Data sync schedule
## Example
```bash cURL theme={null}
curl https://suada.ai/api/public/integrations/status/user-123 \
-H "Authorization: Bearer sk-suada-your-api-key"
```
```typescript TypeScript theme={null}
import { Suada } from '@suada/node';
const suada = new Suada({
apiKey: 'your-api-key'
});
const status = await suada.getIntegrationStatus('user-123');
```
```python Python theme={null}
from suada import Suada, SuadaConfig
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
status = suada.get_integration_status('user-123')
```
```json theme={null}
[
{
"type": "google-analytics",
"enabled": true,
"connected": true,
"lastSynced": "2024-02-20T15:30:00Z",
"propertyId": "123456789",
"syncSchedule": "0 */6 * * *"
},
{
"type": "notion",
"enabled": true,
"connected": true,
"lastSynced": "2024-02-20T15:00:00Z",
"workspaceName": "My Workspace",
"syncSchedule": "0 */12 * * *"
},
{
"type": "zoho",
"enabled": true,
"connected": true,
"lastSynced": "2024-02-20T14:45:00Z",
"organizationId": "org-123",
"dc": "com",
"enabledModules": {
"crm": true,
"books": true,
"projects": true
},
"syncSchedule": "0 */4 * * *"
}
]
```
## Error Codes
Authentication error
```json theme={null}
{
"error": "Invalid or expired API key"
}
```
User not found
```json theme={null}
{
"error": "User not found"
}
```
Server error
```json theme={null}
{
"error": "Failed to get integration status"
}
```
## Notes
* The response includes all available integrations, whether connected or not
* The `lastSynced` timestamp indicates when data was last synchronized
* The `syncSchedule` is in cron format
* Each integration type may have additional fields specific to its configuration
* The `enabled` field indicates whether the integration is currently active
* The `connected` field indicates whether the OAuth connection is valid
# API Reference
Source: https://docs.suada.ai/api-reference/overview
Complete reference for the Suada API
The Suada API is organized around REST, like a divine order governing the digital cosmos. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs - the sacred language through which mortals may commune with our services.
## Base URL
```bash theme={null}
https://suada.ai/api/public
```
## Authentication
The API uses API keys for authentication. You can obtain your API key from the [Suada Dashboard](https://suada.ai).
```bash theme={null}
Authorization: Bearer sk-suada-your-api-key
```
Keep your API keys secure and never share them in publicly accessible areas such as GitHub, client-side code, etc.
## External User Identifiers
When using passthrough mode, you must include an external user identifier with each request. This allows you to associate Suada resources with your application's users.
```bash theme={null}
X-External-User-Id: your-user-id
```
Or as part of the request body:
```json theme={null}
{
"externalUserIdentifier": "your-user-id",
// other request parameters
}
```
Ensure that external user identifiers are consistent across requests for the same user to maintain proper resource association.
## Rate Limiting
The API implements rate limiting based on your plan:
| Plan | Rate Limit |
| ---------- | ------------------------ |
| PRO | 300 requests per minute |
| ENTERPRISE | 1000 requests per minute |
Rate limit headers are included in all responses:
```bash theme={null}
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1625097600
```
## Error Handling
The API uses conventional HTTP response codes to indicate the success or failure of an API request:
* `2xx` - Success
* `4xx` - Client errors
* `5xx` - Server errors
Error responses include a JSON object with more details:
```json theme={null}
{
"error": "Detailed error message"
}
```
## Available Endpoints
### Chat
Send a message to the business analyst
### Integrations
Get available integrations
Initialize OAuth flow for an integration
Handle OAuth callback
Select integration property
Get integration status
Disconnect an integration
### Model Context Protocol (MCP)
Define context for the business analyst
Get available contexts
Get details about a specific context
Update an existing context
Delete a context
## API Modes
### Standard Mode
In standard mode, Suada manages user contexts internally. This is the simplest way to get started with the API.
### Passthrough Mode
In passthrough mode, you manage user contexts through your application. This mode requires you to:
1. Include an external user identifier with each request
2. Manage user authentication and authorization in your application
3. Maintain consistent user identifiers across requests
Passthrough mode is ideal for applications with existing user management systems.
```bash cURL with Passthrough Mode theme={null}
curl -X POST https://suada.ai/api/public/chat/send-message \
-H "Authorization: Bearer sk-suada-your-api-key" \
-H "Content-Type: application/json" \
-H "X-External-User-Id: your-user-id" \
-d '{"message": "What was our MRR growth last month?"}'
```
```json Request Body with External User ID theme={null}
{
"message": "What was our MRR growth last month?",
"externalUserIdentifier": "your-user-id"
}
```
## SDKs
We provide official SDKs for several platforms to help you integrate with Suada:
React, Angular, Vue, React Native, and Vanilla JS
Node.js and Python
# Changelog
Source: https://docs.suada.ai/changelog
Suada Changelog & Updates
## 18th of March 2025
**Updates to SDKs**
* Added support for external integrations in SDKs
* Fixed icons not loading in front-end packages
## 15th of March 2025
**Data Privacy Controls Released**
* Choose whether you share data with Suada on the Pro plan
* Please note that this option is not available on the Free plan
## 14th of March 2025
**GA Release of Suada Chat Screen, API & SDKs**
* Suada is now available to the general public including the Chat Screen available in the platform allowing user's to access and use their internal integrations
* User's can sign up immediately without the need to book a call
* CryptoAPIs Integration Released
* Yahoo Finance Integration Released
* Pro Plan released for Chat Screen
## 8th of March 2025
**Integrations Released**
* Confluence & Monday Integrations released for API & SDK customers
## 7th of March 2025
**Initial Release of Suada**
* Free Chat Screen released with access to Flight Radar & Polymarket
* Internal Integrations released for user's with an account
* Slack
* Notion
* Linear
* Jira
* HubSpot
* Zoho
* API & SDKs released
# Introduction
Source: https://docs.suada.ai/introduction
Rate-limit safe data access for AI agents
## What is Suada?
Suada is a rate-limit safe data access layer for AI agents. It lets your agents query synced customer data from tools like Slack, HubSpot, and Google Ads without polling live vendor APIs on every request.
## Why Suada?
Use Suada to connect external platforms to your agent without owning the OAuth, polling, indexing, and rate-limit handling yourself. Suada provides hosted OAuth, background sync, indexing, and cache-first query APIs so your agent can request scoped context when it needs it.
## Quickstart
Get started with Suada in minutes. Find all the steps you need to get Suada integrated into your platform or clone and test with one of our [examples](https://github.com/accesslabs/suada-examples.git)
## How Suada Works
Use our [SDKs](/sdks/overview) to connect your users' data sources and query synced context using our LangChain tools or API directly. Suada currently supports multiple internal and external integrations:
For a full list of currently supported integrations, please check [here](/integrations)
## Setup
### 🔑 Getting a Suada API Key
Get \$50 in free generation credits when you sign-up to our API.
Sign up for an API key [here](https://suada.ai), or book a 15-minute onboarding to get an API key [here](https://suada.ai/book-call).
## Get Started
Get started quickly with Suada using our step-by-step guide and examples.
Pre-built UI components for React, Angular, Vue, and React Native to manage integrations in minutes.
Server-side SDKs for Node.js and Python with LangChain integration support.
Complete API reference for chat and integration endpoints.
# Quickstart Guide
Source: https://docs.suada.ai/quickstart
Get started with Suada in under 10 minutes
# Quickstart Guide
This guide will help you integrate Suada into your application. We'll cover both back-end integration with LangChain and front-end UI components.
## Prerequisites
Before you begin, make sure you have:
1. A Suada account (sign up at [suada.ai](https://suada.ai) if you haven't already)
2. Your API key from the [dashboard](https://suada.ai/dashboard)
3. Node.js 16+ or Python 3.8+ for back-end integration
4. A LangChain-compatible LLM (e.g., OpenAI API key)
## Environment Setup
### Back-end Environment Variables
Create a `.env` file in your project root:
```env theme={null}
# Required
SUADA_API_KEY=your_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
# Optional
SUADA_BASE_URL=https://api.suada.ai
SUADA_DEBUG=true
```
### Front-end Environment Variables
For React/Vue/Angular applications, create a `.env` file:
```env theme={null}
# React/Vue/Angular
VITE_SUADA_API_KEY=your_api_key_here
VITE_SUADA_BASE_URL=https://api.suada.ai
# Next.js
NEXT_PUBLIC_SUADA_API_KEY=your_api_key_here
NEXT_PUBLIC_SUADA_BASE_URL=https://api.suada.ai
# React Native
SUADA_API_KEY=your_api_key_here
SUADA_BASE_URL=https://api.suada.ai
```
## Back-end Integration
### Step 1: Install the SDK
Choose your preferred back-end language:
```bash npm theme={null}
npm install @suada/node langchain
```
```bash pip theme={null}
pip install suada langchain
```
### Step 2: Create a LangChain Agent
Here's how to use Suada as a tool in your LangChain agent:
```typescript TypeScript theme={null}
import { SuadaClient } from '@suada/node';
import { ChatOpenAI } from 'langchain/chat_models/openai';
import { initializeAgentExecutorWithOptions } from 'langchain/agents';
// Initialize Suada client
const suada = new SuadaClient({
apiKey: process.env.SUADA_API_KEY
});
// Create Suada tool for LangChain
const suadaTool = suada.createTool({
name: 'business_analyst',
description: 'Use this tool to analyze business data and get insights. Input should be a specific business question.',
externalUserIdentifier: 'user_123' // Your user's identifier
});
// Initialize LLM
const model = new ChatOpenAI({
temperature: 0,
modelName: 'gpt-4',
openAIApiKey: process.env.OPENAI_API_KEY
});
// Create agent
const executor = await initializeAgentExecutorWithOptions(
[suadaTool],
model,
{
agentType: "openai-functions",
verbose: true
}
);
// Use the agent
const result = await executor.run(
"What were our top performing products last month, and what insights can you provide about their performance?"
);
```
```python Python theme={null}
from suada import SuadaClient
from langchain.chat_models import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
# Initialize Suada client
suada = SuadaClient(
api_key='your_suada_api_key'
)
# Create Suada tool for LangChain
suada_tool = suada.create_tool(
name='business_analyst',
description='Use this tool to analyze business data and get insights. Input should be a specific business question.',
external_user_identifier='user_123' # Your user's identifier
)
# Initialize LLM
llm = ChatOpenAI(
temperature=0,
model_name='gpt-4'
)
# Create agent
agent = initialize_agent(
tools=[suada_tool],
llm=llm,
agent=AgentType.OPENAI_FUNCTIONS,
verbose=True
)
# Use the agent
result = agent.run(
"What were our top performing products last month, and what insights can you provide about their performance?"
)
```
## Front-end Integration
### Step 1: Install the Front-end SDK
Choose your preferred front-end framework:
```bash React theme={null}
npm install @suada/core @suada/integrations-react
```
```bash React Native theme={null}
npm install @suada/core @suada/integrations-react-native
```
```bash Vue theme={null}
npm install @suada/core @suada/integrations-vue
```
```bash Angular theme={null}
npm install @suada/core @suada/integrations-angular
```
```bash Vanilla theme={null}
npm install @suada/core @suada/integrations-vanilla
```
Note: All front-end SDKs require the `@suada/core` package as a peer dependency.
### Step 2: Add the Integration Manager
Add the integration manager component to your application:
```tsx React theme={null}
import { IntegrationManager } from '@suada/integrations-react';
function App() {
return (
{
console.log(`Integration ${type} connected`);
}
}}
/>
);
}
```
```tsx React Native theme={null}
import { IntegrationManager } from '@suada/integrations-react-native';
function App() {
return (
{
console.log(`Integration ${type} connected`);
}
}}
style={styles.container}
/>
);
}
```
```vue Vue theme={null}
```
```typescript Angular theme={null}
import { Component } from '@angular/core';
import { SuadaIntegrationsConfig } from '@suada/integrations-angular';
@Component({
selector: 'app-root',
template: `
`
})
export class AppComponent {
config: SuadaIntegrationsConfig = {
apiKey: environment.suadaApiKey,
externalUserIdentifier: 'user_123'
};
onIntegrationConnected(type: string) {
console.log(`Integration ${type} connected`);
}
}
```
```html Vanilla theme={null}
```
## Best Practices
### Security
* Never commit API keys to version control
* Use environment variables for sensitive data
* Implement proper error handling
* Validate user input
* Use HTTPS for all API calls
### Performance
* Initialize SDK instances once and reuse them
* Implement proper cleanup in component unmount
* Handle offline scenarios gracefully
* Use proper caching strategies
* Optimize network requests
### Development
* Use TypeScript/type hints when available
* Follow framework best practices
* Write unit tests
* Keep dependencies updated
* Use proper error boundaries
## Common Issues & Solutions
### API Key Issues
If you're getting authentication errors:
1. Verify your API key is correctly set in environment variables
2. Check if the API key has the correct permissions
3. Ensure the environment variable is accessible in your application
### Integration Connection Issues
If integrations aren't connecting:
1. Verify the OAuth callback URL is correctly configured
2. Check if the integration is enabled in your Suada dashboard
3. Ensure proper error handling is in place
### LangChain Integration Issues
If the LangChain agent isn't working:
1. Verify OpenAI API key is correctly set
2. Check if the model name is supported
3. Ensure proper error handling for API calls
## Need Help?
If you run into any issues:
* Email us at [hello@suada.ai](mailto:hello@suada.ai)
# Angular SDK
Source: https://docs.suada.ai/sdks/angular
Learn how to integrate Suada with your Angular application
## Overview
The Suada Angular SDK provides a seamless way to integrate Suada's AI capabilities into your Angular applications. Built specifically for Angular 17+, it offers components, services, and utilities that follow Angular best practices and conventions.
## Prerequisites
* Angular 17.3.0 or higher
* Node.js 18.0.0 or higher
* A Suada API key
* npm or yarn package manager
## Installation
Install the Suada Angular SDK and its peer dependencies:
```bash theme={null}
# Using npm
npm install @suada/angular @suada/core
# Using yarn
yarn add @suada/angular @suada/core
```
## Quick Start
Here's a basic example to get you started:
```typescript theme={null}
// app.module.ts
import { NgModule } from '@angular/core';
import { SuadaModule } from '@suada/angular';
@NgModule({
imports: [
SuadaModule.forRoot({
apiKey: 'your-api-key'
})
]
})
export class AppModule { }
// app.component.ts
import { Component } from '@angular/core';
import { SuadaService } from '@suada/angular';
@Component({
selector: 'app-root',
template: `
{{ response }}
`
})
export class AppComponent {
response?: string;
constructor(private suada: SuadaService) {}
async sendMessage() {
try {
const result = await this.suada.chat({
message: "What insights can you provide?"
});
this.response = result.answer;
} catch (error) {
console.error('Error:', error);
}
}
}
```
## Authentication
### Setting up your API Key
We recommend storing your API key in environment files:
```typescript theme={null}
// environment.ts
export const environment = {
production: false,
suada: {
apiKey: 'your-api-key'
}
};
// environment.prod.ts
export const environment = {
production: true,
suada: {
apiKey: process.env['SUADA_API_KEY']
}
};
```
Then use it in your module:
```typescript theme={null}
import { environment } from './environments/environment';
@NgModule({
imports: [
SuadaModule.forRoot(environment.suada)
]
})
export class AppModule { }
```
## Core Components
### Chat Component
A pre-built chat interface component:
```html theme={null}
```
#### Props
| Prop | Type | Required | Description |
| --------------- | ----------------- | -------- | -------------------------------- |
| theme | 'light' \| 'dark' | No | UI theme (defaults to 'light') |
| placeholder | string | No | Input placeholder text |
| initialMessages | Message\[] | No | Pre-loaded chat messages |
| privacyMode | boolean | No | Enable enhanced privacy features |
#### Events
| Event | Type | Description |
| ---------------- | ------------ | --------------------------------- |
| messageSubmit | EventEmitter | Emitted when user sends a message |
| responseReceived | EventEmitter | Emitted when response is received |
| error | EventEmitter | Emitted when an error occurs |
### Integration Components
#### Integration Button
Handle OAuth flows for third-party services:
```html theme={null}
Connect Notion
```
#### Integration List
Display and manage integrated services:
```html theme={null}
```
## Services
### SuadaService
The main service for interacting with Suada:
```typescript theme={null}
import { SuadaService } from '@suada/angular';
export class MyComponent {
constructor(private suada: SuadaService) {}
async sendMessage() {
try {
const response = await this.suada.chat({
message: "What's our performance?",
privacyMode: true
});
console.log(response.answer);
} catch (error) {
console.error('Error:', error);
}
}
}
```
### IntegrationService
Manage third-party integrations:
```typescript theme={null}
import { IntegrationService } from '@suada/angular';
export class MyComponent {
constructor(private integrations: IntegrationService) {}
async connectService() {
try {
const authUrl = await this.integrations.initializeOAuth('notion', {
redirectUri: 'https://your-app.com/callback'
});
window.location.href = authUrl;
} catch (error) {
console.error('Error:', error);
}
}
}
```
## Error Handling
The SDK provides typed errors for better error handling:
```typescript theme={null}
import { SuadaError, SuadaAPIError } from '@suada/core';
try {
await this.suada.chat({ message: "Hello" });
} catch (error) {
if (error instanceof SuadaAPIError) {
// Handle API-specific errors
console.error('API Error:', error.message, error.status);
} else if (error instanceof SuadaError) {
// Handle general SDK errors
console.error('SDK Error:', error.message);
} else {
// Handle unexpected errors
console.error('Unexpected error:', error);
}
}
```
## Best Practices
### Security
* Store API keys in environment files
* Use privacy mode for sensitive data
* Implement proper error handling
* Secure OAuth callback endpoints
### Performance
* Reuse service instances
* Implement proper unsubscribe patterns
* Handle component lifecycle properly
* Consider implementing caching
### Development
* Use TypeScript strict mode
* Follow Angular style guide
* Write unit tests
* Keep dependencies updated
## FAQ
### How do I handle environment-specific configuration?
Use Angular's environment files and configure the module accordingly:
```typescript theme={null}
import { environment } from './environments/environment';
@NgModule({
imports: [
SuadaModule.forRoot({
apiKey: environment.suada.apiKey,
baseUrl: environment.suada.baseUrl
})
]
})
```
### How do I customize the chat component theme?
You can override the default styles using CSS variables:
```scss theme={null}
:root {
--suada-primary-color: #007bff;
--suada-background-color: #ffffff;
--suada-text-color: #333333;
}
```
### Can I use the SDK with SSR (Server-Side Rendering)?
Yes, the SDK is compatible with Angular Universal. Just ensure you handle the window object appropriately:
```typescript theme={null}
import { isPlatformBrowser } from '@angular/common';
constructor(
@Inject(PLATFORM_ID) private platformId: Object
) {
if (isPlatformBrowser(this.platformId)) {
// Browser-only code
}
}
```
### How do I implement retry logic?
The SDK includes built-in retry logic, but you can customize it:
```typescript theme={null}
@NgModule({
imports: [
SuadaModule.forRoot({
apiKey: 'your-api-key',
maxRetries: 3,
retryDelay: 1000
})
]
})
```
### How can I debug the SDK?
Enable debug mode in your environment configuration:
```typescript theme={null}
SuadaModule.forRoot({
apiKey: 'your-api-key',
debug: true
})
```
## Support & Resources
### Documentation
* [API Reference](/api-reference)
* [Component Library](/components)
* [Integration Guides](/guides)
### Support
* Email Support: [hello@suada.ai](mailto:hello@suada.ai)
# Backend SDKs Overview
Source: https://docs.suada.ai/sdks/backend-overview
Official server-side SDKs for integrating Suada with your backend services
## Introduction
Suada provides official backend SDKs to help you integrate AI-powered chat and analysis capabilities into your server-side applications. Our SDKs are designed with developer experience in mind, offering type safety, comprehensive documentation, and intuitive APIs.
## Available SDKs
Modern JavaScript/TypeScript SDK
Built-in TypeScript support
Node.js 18+ compatibility
LangChain integration
Pythonic SDK with async support
Python 3.8+ support
Pydantic type validation
LangChain integration
## Core Features
### 🔐 Authentication & Security
Both SDKs support secure authentication using API keys and include privacy features:
```typescript Node.js theme={null}
import { Suada } from '@suada/node';
const suada = new Suada({
apiKey: process.env.SUADA_API_KEY,
privacyMode: true // Optional enhanced security
});
```
```python Python theme={null}
from suada import Suada, SuadaConfig
suada = Suada(
config=SuadaConfig(
api_key=os.getenv("SUADA_API_KEY"),
privacy_mode=True # Optional enhanced security
)
)
```
### 🤖 LangChain Integration
Both SDKs provide seamless integration with LangChain for advanced AI capabilities:
```typescript Node.js theme={null}
import { Suada } from '@suada/node';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatOpenAI } from 'langchain/chat_models/openai';
const suada = new Suada({
apiKey: process.env.SUADA_API_KEY
});
const suadaTool = suada.createTool({
name: 'business_analyst',
description: 'Use this tool for business insights'
});
const agent = await createOpenAIFunctionsAgent({
llm: new ChatOpenAI({ temperature: 0 }),
tools: [suadaTool]
});
const executor = AgentExecutor.fromAgentAndTools({
agent,
tools: [suadaTool]
});
```
```python Python theme={null}
from suada import Suada, SuadaConfig
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain.chat_models import ChatOpenAI
from langchain.memory import ConversationBufferMemory
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
suada_tool = suada.create_tool(
name="business_analyst",
description="Use this tool for business insights"
)
agent = create_openai_functions_agent(
llm=ChatOpenAI(temperature=0),
tools=[suada_tool]
)
memory = ConversationBufferMemory(
memory_key="chat_history",
return_messages=True
)
executor = AgentExecutor.from_agent_and_tools(
agent=agent,
tools=[suada_tool],
memory=memory
)
```
### 💬 Chat Interface
The chat endpoint is the primary way to interact with Suada. Both SDKs provide a consistent response format:
```typescript theme={null}
interface SuadaResponse {
// Main response text
answer: string;
// Optional fields
thoughts?: string;
actions?: Array<{
tool: string;
toolInput: string;
log: string;
}>;
followUpQuestion?: string;
reasoning?: string;
sources?: string[];
conversationId?: string;
timestamp: number;
}
```
### 👤 User Context Management
Both SDKs support passthrough mode for integrating with your application's user system:
```typescript Node.js theme={null}
const suada = new Suada({
apiKey: process.env.SUADA_API_KEY,
passthroughMode: true
});
const response = await suada.chat({
message: "What's our performance?",
externalUserIdentifier: "user-123"
});
```
```python Python theme={null}
suada = Suada(
config=SuadaConfig(
api_key=os.getenv("SUADA_API_KEY"),
passthrough_mode=True
)
)
response = suada.chat(
message="What's our performance?",
external_user_identifier="user-123"
)
```
## Key Benefits
### Type Safety
* Built-in TypeScript definitions (Node.js)
* Pydantic model validation (Python)
* IDE autocompletion support
* Runtime type checking
### LangChain Support
* Tool creation for LangChain agents
* Memory management for conversations
* Custom agent configurations
* Structured prompt templates
### Error Handling
* Structured error types
* Detailed error messages
* Automatic retry mechanisms
* Rate limit handling
### Performance
* Connection pooling
* Automatic retries
* Concurrent request support
* Efficient resource management
### Security
* Secure API key handling
* Privacy mode option
* User isolation in passthrough mode
* Rate limiting protection
## Getting Started
1. **Choose Your SDK**
* Node.js: Modern JavaScript/TypeScript applications and web backends
* Python: Data science, AI/ML, or Python web applications
2. **Installation**
```bash theme={null}
# Node.js
npm install @suada/node langchain
# Python
pip install suada langchain
```
3. **Configure Environment**
```bash theme={null}
# .env file
SUADA_API_KEY=your-api-key
OPENAI_API_KEY=your-openai-key # Required for LangChain integration
```
4. **Initialize Client**
* Follow SDK-specific initialization
* Configure optional features
* Set up error handling
* Initialize LangChain tools if needed
5. **Make Your First Request**
* Send a test message
* Handle the response
* Implement error handling
## Best Practices
### Security
* Store API keys in environment variables
* Enable privacy mode for sensitive data
* Implement proper error handling
* Use secure user identification
### LangChain Integration
* Use clear tool descriptions
* Implement proper memory management
* Handle agent errors gracefully
* Monitor agent performance
### Performance
* Reuse SDK and agent instances
* Implement appropriate timeouts
* Handle rate limits gracefully
* Use async/await where available
### Development
* Use type checking tools
* Write comprehensive tests
* Follow SDK-specific conventions
* Keep dependencies updated
## FAQ
### Which SDK should I choose?
* Choose Node.js for JavaScript/TypeScript applications and modern web backends
* Choose Python for data science, AI/ML applications, or Python web services
### How do I handle rate limits?
Both SDKs implement automatic exponential backoff. You can customize retry behavior through configuration options.
### Can I use the SDKs in serverless environments?
Yes, both SDKs are compatible with serverless environments like AWS Lambda, Google Cloud Functions, and Vercel.
### How do I debug SDK issues?
Both SDKs provide detailed logging options:
* Node.js: Debug environment variable
* Python: Standard logging module
### Is local development supported?
Yes, both SDKs support local development with:
* Custom base URLs
* Debug logging
* Test environments
* Mock responses
## Support & Resources
### Documentation
* [Node.js SDK Documentation](/sdks/node)
* [Python SDK Documentation](/sdks/python)
* [LangChain Documentation](https://js.langchain.com/docs) (JavaScript)
* [LangChain Documentation](https://python.langchain.com/docs) (Python)
### Support
* Email: [support@suada.ai](mailto:support@suada.ai)
# Frontend SDKs Overview
Source: https://docs.suada.ai/sdks/frontend-overview
Pre-built UI components for managing integrations in your frontend applications
Suada provides official frontend SDKs with pre-built UI components to help you quickly add integration management to your applications. Choose the SDK that matches your frontend framework:
## Available Frontend SDKs
Modern React components with hooks and TypeScript support
React 18+ support
Custom hooks for state management
Styled components integration
LangChain integration
} href="/sdks/next">
Server-side rendering and App Router support
Next.js 13+ support
Server Components
API route handlers
Tailwind CSS integration
Enterprise-ready Angular components and services
Angular 17.3+ support
Injectable services
Standalone components
TypeScript support
Vue 3 components with composables
Vue 3.0+ support
Composition API
TypeScript support
Vite integration
Native mobile components for iOS and Android
React Native 0.73+ support
Deep linking support
Native UI components
Expo compatibility
Framework-agnostic JavaScript implementation
No framework dependencies
Modern browser support
CDN availability
UMD/ESM formats
## Getting Started
### Prerequisites
Before you begin, ensure you have:
* A Suada API key
* Node.js 16.0.0 or higher
* A modern web browser
* Your preferred package manager (npm, yarn, or pnpm)
### Installation
Choose your preferred SDK and install it:
```bash theme={null}
# React
npm install @suada/react @suada/core
# Next.js
npm install @suada/next @suada/core
# Angular
npm install @suada/angular @suada/core
# Vue
npm install @suada/vue @suada/core
# React Native
npm install @suada/react-native @suada/core
# Vanilla JS
npm install @suada/vanilla @suada/core
```
### Environment Setup
Set up your environment variables based on your framework:
```env theme={null}
# React/Vue/Angular
VITE_SUADA_API_KEY=your-api-key
VITE_SUADA_BASE_URL=https://api.suada.ai
# Next.js
NEXT_PUBLIC_SUADA_API_KEY=your-api-key
NEXT_PUBLIC_SUADA_BASE_URL=https://api.suada.ai
# React Native
SUADA_API_KEY=your-api-key
SUADA_BASE_URL=https://api.suada.ai
```
## Core Features
### 🔒 OAuth Integration Flow
The SDKs provide a seamless OAuth integration experience:
1. **Initialize Connection**
* User clicks connect button
* SDK handles OAuth redirect
* Secure token exchange
2. **Authorization**
* User authenticates with provider
* Secure callback handling
* Token management
3. **Integration Complete**
* Success confirmation
* Ready to use
### 🎨 UI Components
All SDKs provide these core components:
#### Integration Button
A customizable button for connecting services:
```jsx React theme={null}
Connect Notion
```
```tsx Next.js theme={null}
Connect Notion
```
```typescript Angular theme={null}
Connect Notion
```
```vue Vue theme={null}
Connect Notion
```
#### Integration List
Display and manage connected integrations:
```jsx React theme={null}
```
```tsx Next.js theme={null}
```
```typescript Angular theme={null}
```
```vue Vue theme={null}
```
## Best Practices
### Security
* Store API keys in environment variables
* Use HTTPS for all API calls
* Implement proper error handling
* Secure OAuth callback endpoints
* Validate user sessions
### Performance
* Lazy load components
* Implement proper cleanup
* Handle offline scenarios
* Optimize network requests
* Use proper caching
### Development
* Use TypeScript for type safety
* Follow framework best practices
* Write unit tests
* Keep dependencies updated
* Use proper error boundaries
## Common Use Cases
### Basic Integration Setup
1. **Install SDK**
```bash theme={null}
npm install @suada/react @suada/core
```
2. **Configure Provider**
```typescript theme={null}
import { SuadaProvider } from '@suada/react';
function App() {
return (
);
}
```
3. **Add Components**
```jsx theme={null}
```
## Framework-Specific Features
### Next.js
* Server Components support
* API route handlers
* App Router compatibility
* Tailwind CSS integration
### React
* Custom hooks
* Context API integration
* Styled components
* LangChain support
### Angular
* Injectable services
* Standalone components
* Dependency injection
* RxJS integration
### Vue
* Composition API
* Vite integration
* Vue Router support
* Pinia integration
### React Native
* Native UI components
* Deep linking
* Platform-specific optimizations
* Expo compatibility
## FAQ
### How do I handle OAuth callbacks?
1. Set up your callback URL in the Suada dashboard
2. Configure the redirect URI in your component
3. Handle the callback in your application
```typescript theme={null}
// Example callback handler
const handleCallback = async (code: string) => {
try {
await suada.handleOAuthCallback(code);
// Handle success
} catch (error) {
// Handle error
}
};
```
### How do I debug integration issues?
1. Enable debug mode
2. Check network requests
3. Validate OAuth flow
```typescript theme={null}
// Enable debug mode
const suada = new Suada({
debug: true,
logger: console.log
});
```
### How do I handle offline scenarios?
1. Implement proper error handling
2. Use retry mechanisms
3. Cache responses
```typescript theme={null}
// Example offline handling
const handleRequest = async () => {
try {
return await suada.request();
} catch (error) {
if (error.code === 'OFFLINE') {
// Handle offline scenario
}
}
};
```
## Support & Resources
### Documentation
* [API Reference](/api-reference)
### Support
* Email Support: [hello@suada.ai](mailto:hello@suada.ai)
# Node.js SDK
Source: https://docs.suada.ai/sdks/node
Learn how to integrate Suada with your Node.js applications
## Overview
The Suada Node.js SDK provides a simple and intuitive way to interact with the Suada API. It includes built-in TypeScript support and handles all the complexity of making API requests, managing authentication, and parsing responses.
## Prerequisites
* Node.js version 18.0.0 or higher
* A Suada API key
* npm or yarn package manager
## Installation
Install the Suada Node.js SDK using npm:
```bash theme={null}
npm install @suada/sdk
```
Or using yarn:
```bash theme={null}
yarn add @suada/sdk
```
## Quick Start
Here's a basic example to get you started:
```typescript theme={null}
import { Suada } from '@suada/sdk';
// Initialize the client
const suada = new Suada({
apiKey: 'your-api-key'
});
// Send a chat message
async function chat() {
try {
const response = await suada.chat({
message: 'What insights can you provide about our recent performance?'
});
console.log(response.answer);
} catch (error) {
console.error('Error:', error);
}
}
chat();
```
## Authentication
### Setting up your API Key
We recommend storing your API key in environment variables:
```bash theme={null}
# .env
SUADA_API_KEY=your-api-key
```
Then load it in your application:
```typescript theme={null}
import dotenv from 'dotenv';
import { Suada } from '@suada/sdk';
dotenv.config();
const suada = new Suada({
apiKey: process.env.SUADA_API_KEY
});
```
## Core Concepts
### Chat Messages
The chat endpoint is the primary way to interact with Suada. Each chat request can include:
* A message (required)
* Chat history (optional)
* Configuration options (optional)
```typescript theme={null}
const response = await suada.chat({
message: "How's our business performing?",
chatHistory: previousMessages, // Optional
privacyMode: true // Optional
});
```
### Response Format
Chat responses include several key components:
```typescript theme={null}
interface SuadaResponse {
// The main response text
answer: string;
// Internal reasoning process (optional)
thoughts?: string;
// Actions taken during processing (optional)
actions?: Array<{
tool: string;
toolInput: string;
log: string;
}>;
// Suggested follow-up question (optional)
followUpQuestion?: string;
// Reasoning behind the response (optional)
reasoning?: string;
// Reference sources (optional)
sources?: string[];
// Conversation tracking ID (optional)
conversationId?: string;
// Response timestamp
timestamp: number;
}
```
## Advanced Features
### LangChain Integration
The SDK provides seamless integration with LangChain, allowing you to use Suada's capabilities within your LangChain applications:
```typescript theme={null}
import { Suada } from '@suada/sdk';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatOpenAI } from 'langchain/chat_models/openai';
import { PromptTemplate } from 'langchain/prompts';
// Initialize Suada
const suada = new Suada({
apiKey: process.env.SUADA_API_KEY
});
// Create a Suada tool for LangChain
const suadaTool = suada.createTool({
name: 'business_analyst',
description: 'Use this tool to get business insights and analysis',
externalUserIdentifier: 'user-123' // Required if using passthrough mode
});
// Create an OpenAI agent with the Suada tool
const model = new ChatOpenAI({ temperature: 0 });
const tools = [suadaTool];
const prompt = PromptTemplate.fromTemplate(`
You are a helpful assistant that uses Suada's business analyst capabilities.
Current conversation:
{chat_history}
Human: {input}
Assistant: Let me help you with that.
`);
const agent = await createOpenAIFunctionsAgent({
llm: model,
tools,
prompt
});
const executor = AgentExecutor.fromAgentAndTools({
agent,
tools,
verbose: true
});
// Use the agent
const result = await executor.invoke({
input: "What's our revenue trend for the last quarter?",
chat_history: []
});
```
#### LangChain Best Practices
1. **Tool Configuration**
* Provide clear, specific descriptions for your tools
* Use appropriate temperature settings for your use case
* Consider implementing tool-specific error handling
2. **Agent Setup**
* Use structured prompts for consistent behavior
* Implement proper chat history management
* Consider using memory for maintaining context
3. **Error Handling**
* Implement proper error handling for both Suada and LangChain
* Consider retry logic for transient failures
* Log agent actions for debugging
4. **Performance**
* Reuse agent instances when possible
* Implement appropriate timeouts
* Consider caching for frequently used data
### Passthrough Mode
Passthrough mode allows you to associate Suada conversations with your application's user system:
```typescript theme={null}
const suada = new Suada({
apiKey: process.env.SUADA_API_KEY,
passthroughMode: true
});
// When using passthrough mode, include externalUserIdentifier
const response = await suada.chat({
message: "What's our revenue trend?",
externalUserIdentifier: 'user-123' // Required in passthrough mode
});
```
### Privacy Mode
Enable privacy mode to ensure sensitive information is handled with additional security:
```typescript theme={null}
const response = await suada.chat({
message: "Analyze our financial data",
privacyMode: true
});
```
## Error Handling
The SDK provides typed errors for better error handling:
```typescript theme={null}
import { Suada, SuadaError, SuadaAPIError } from '@suada/sdk';
try {
const response = await suada.chat({
message: "What's our revenue?"
});
} catch (error) {
if (error instanceof SuadaAPIError) {
// Handle API-specific errors
console.error('API Error:', error.message, error.status, error.code);
} else if (error instanceof SuadaError) {
// Handle general SDK errors
console.error('SDK Error:', error.message);
} else {
// Handle unexpected errors
console.error('Unexpected error:', error);
}
}
```
## Best Practices
1. **Environment Variables**
* Store API keys and sensitive configuration in environment variables
* Use a package like `dotenv` to manage environment variables
2. **Error Handling**
* Always implement try-catch blocks around API calls
* Use the provided error types for specific error handling
* Log errors appropriately for debugging
3. **TypeScript Usage**
* Take advantage of built-in type definitions
* Enable strict mode in your TypeScript configuration
* Use type annotations for better code reliability
4. **Response Processing**
* Always check for the presence of optional fields before using them
* Handle missing data gracefully
* Consider implementing retry logic for failed requests
## Configuration Options
| Option | Type | Required | Description |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| apiKey | string | Yes | Your Suada API key |
| baseUrl | string | No | Custom API endpoint (defaults to [https://suada.ai/api/public](https://suada.ai/api/public)) |
| passthroughMode | boolean | No | Enable user-specific resources |
## FAQ
### How do I handle rate limiting?
The SDK automatically handles rate limiting by implementing exponential backoff. You can customize this behavior by implementing your own retry logic.
### Can I use the SDK in a browser environment?
No, the SDK is designed for server-side Node.js applications only. For browser applications, use our REST API with appropriate CORS headers.
### How do I maintain conversation context?
Use the `chatHistory` parameter to maintain conversation context:
```typescript theme={null}
const messages = [];
const response1 = await suada.chat({ message: "How's our revenue?" });
messages.push({ role: 'user', content: "How's our revenue?" });
messages.push({ role: 'assistant', content: response1.answer });
const response2 = await suada.chat({
message: "Compare that to last year",
chatHistory: messages
});
```
### How can I debug API calls?
Enable debug logging by setting the `DEBUG` environment variable:
```bash theme={null}
DEBUG=suada:* node your-app.js
```
### Support
* Email Support: [hello@suada.ai](mailto:hello@suada.ai)
# SDKs Overview
Source: https://docs.suada.ai/sdks/overview
Choose the right SDK for your tech stack and get started with Suada
Suada provides official SDKs for multiple platforms and frameworks to help you integrate business analytics into your applications. Choose the SDK that best matches your tech stack:
## Available SDKs
### Frontend SDKs
Build interactive analytics interfaces in React applications
React 18+ support
Custom hooks
LangChain integration
} href="/sdks/next">
Server-side rendering and App Router support
Next.js 13+ support
Server Components
API route handlers
Create powerful analytics components in Angular applications
Angular 17.3+ support
Injectable services
Standalone components
Integrate analytics seamlessly in Vue 3 applications
Vue 3.0+ support
Composition API
Vite integration
Add analytics to your iOS and Android applications
React Native 0.73+ support
Native components
Deep linking
Use Suada with plain JavaScript or any web framework
Framework agnostic
CDN support
UMD/ESM formats
### Backend SDKs
Integrate with Node.js applications and LangChain agents
Node.js 18+ support
LangChain integration
TypeScript support
Build analytics solutions with Python and LangChain
Python 3.8+ support
LangChain integration
Type hints
## Quick Comparison
Choose the right SDK based on your needs:
| SDK | Best For | Key Features | Requirements |
| ------------ | ------------------------------- | -------------------------------------------- | ------------------ |
| React | Web applications using React | Component library, hooks, TypeScript support | React 18+ |
| Next.js | Server-side rendered React apps | Server Components, API routes, App Router | Next.js 13+ |
| Angular | Enterprise Angular applications | Injectable services, components, TypeScript | Angular 17.3+ |
| Vue | Vue.js applications | Composables, components, TypeScript | Vue 3.0+ |
| React Native | Mobile applications | Native components, deep linking support | React Native 0.73+ |
| Vanilla JS | Any web application | Framework agnostic, CDN support | Modern browsers |
| Node.js | Backend services, LangChain | LangChain integration, async support | Node.js 18+ |
| Python | Data analysis, LangChain | LangChain integration, type hints | Python 3.8+ |
## Core Features
### 🔒 OAuth Integration
All SDKs provide secure OAuth integration:
1. **Initialize Connection**
* User clicks connect button
* SDK handles OAuth redirect
* Secure token exchange
2. **Authorization**
* User authenticates with provider
* Secure callback handling
* Token management
3. **Integration Complete**
* Success confirmation
* Ready to use
### 🛠️ Common Features
All SDKs share these core features:
* **Type Safety**: Built-in TypeScript/type hints support
* **Error Handling**: Comprehensive error types and handling
* **API Consistency**: Similar patterns across all SDKs
* **LangChain Support**: Integration with LangChain (Node.js and Python)
* **Passthrough Mode**: Support for using with external user identifiers
## Getting Started
### Prerequisites
Before you begin, ensure you have:
* A Suada API key
* Node.js 16.0.0 or higher (for JavaScript/TypeScript SDKs)
* Python 3.8+ (for Python SDK)
* Your preferred package manager
### Installation
Each SDK can be installed via its respective package manager:
```bash npm theme={null}
# React/Next.js/Angular/Vue/React Native/Node.js
npm install @suada/[sdk-name] @suada/core
```
```bash pip theme={null}
# Python
pip install suada
```
### Environment Setup
Set up your environment variables based on your framework:
```env theme={null}
# React/Vue/Angular
VITE_SUADA_API_KEY=your-api-key
VITE_SUADA_BASE_URL=https://api.suada.ai
# Next.js
NEXT_PUBLIC_SUADA_API_KEY=your-api-key
NEXT_PUBLIC_SUADA_BASE_URL=https://api.suada.ai
# React Native
SUADA_API_KEY=your-api-key
SUADA_BASE_URL=https://api.suada.ai
# Node.js/Python
SUADA_API_KEY=your-api-key
SUADA_BASE_URL=https://api.suada.ai
```
### Basic Integration
1. **Install SDK**
```bash theme={null}
npm install @suada/react @suada/core
```
2. **Configure Provider**
```typescript theme={null}
import { SuadaProvider } from '@suada/react';
function App() {
return (
);
}
```
3. **Add Components**
```jsx theme={null}
```
## Best Practices
### Security
* Store API keys in environment variables
* Use HTTPS for all API calls
* Implement proper error handling
* Secure OAuth callback endpoints
* Validate user sessions
### Performance
* Initialize SDK instances once and reuse them
* Implement proper cleanup
* Handle offline scenarios
* Optimize network requests
* Use proper caching
### Development
* Use TypeScript/type hints when available
* Follow framework best practices
* Write unit tests
* Keep dependencies updated
* Use proper error boundaries
## FAQ
### How do I handle OAuth callbacks?
1. Set up your callback URL in the Suada dashboard
2. Configure the redirect URI in your component
3. Handle the callback in your application
```typescript theme={null}
// Example callback handler
const handleCallback = async (code: string) => {
try {
await suada.handleOAuthCallback(code);
// Handle success
} catch (error) {
// Handle error
}
};
```
### How do I manage user sessions?
1. Use the built-in session management
2. Implement proper cleanup
3. Handle token refresh
```typescript theme={null}
// Example session management
const { session, refreshToken } = useSession();
// Refresh token when needed
await refreshToken();
```
### How do I debug integration issues?
1. Enable debug mode
2. Check network requests
3. Validate OAuth flow
```typescript theme={null}
// Enable debug mode
const suada = new Suada({
debug: true,
logger: console.log
});
```
### How do I handle offline scenarios?
1. Implement proper error handling
2. Use retry mechanisms
3. Cache responses
```typescript theme={null}
// Example offline handling
const handleRequest = async () => {
try {
return await suada.request();
} catch (error) {
if (error.code === 'OFFLINE') {
// Handle offline scenario
}
}
};
```
## Support & Resources
### Documentation
* [API Reference](/api-reference)
* [Component Library](/components)
* [Integration Guides](/guides)
* [Framework Best Practices](/best-practices)
* [Performance Guide](/performance)
### Support
* Email Support: [hello@suada.ai](mailto:hello@suada.ai)
# Python SDK
Source: https://docs.suada.ai/sdks/python
Learn how to integrate Suada with your Python applications
## Overview
The Suada Python SDK provides a Pythonic interface to interact with the Suada API. Built with type safety in mind using Pydantic, it offers a robust and intuitive way to integrate Suada's capabilities into your Python applications.
## Prerequisites
* Python 3.8 or higher
* A Suada API key
* pip package manager
## Installation
Install the Suada Python SDK using pip:
```bash theme={null}
pip install suada
```
Or using poetry:
```bash theme={null}
poetry add suada
```
## Quick Start
Here's a basic example to get you started:
```python theme={null}
from suada import Suada, SuadaConfig
# Initialize the client
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
# Send a chat message
try:
response = suada.chat(
message="What insights can you provide about our recent performance?"
)
print(response.answer)
except Exception as e:
print(f"Error: {str(e)}")
```
## Authentication
### Setting up your API Key
We recommend storing your API key in environment variables:
```bash theme={null}
# .env
SUADA_API_KEY=your-api-key
```
Then load it in your application:
```python theme={null}
import os
from dotenv import load_dotenv
from suada import Suada, SuadaConfig
# Load environment variables
load_dotenv()
# Initialize the client
suada = Suada(
config=SuadaConfig(
api_key=os.getenv("SUADA_API_KEY")
)
)
```
## Core Concepts
### Chat Messages
The chat endpoint is the primary way to interact with Suada. Each chat request can include:
* A message (required)
* Chat history (optional)
* Configuration options (optional)
```python theme={null}
response = suada.chat(
message="How's our business performing?",
chat_history=previous_messages, # Optional
privacy_mode=True # Optional
)
```
### Response Format
Chat responses include several key components:
```python theme={null}
from pydantic import BaseModel
from typing import List, Optional, Dict
class SuadaResponse(BaseModel):
# The main response text
answer: str
# Internal reasoning process (optional)
thoughts: Optional[str] = None
# Actions taken during processing (optional)
actions: Optional[List[Dict[str, str]]] = None
# Suggested follow-up question (optional)
follow_up_question: Optional[str] = None
# Reasoning behind the response (optional)
reasoning: Optional[str] = None
# Reference sources (optional)
sources: Optional[List[str]] = None
# Conversation tracking ID (optional)
conversation_id: Optional[str] = None
# Response timestamp
timestamp: int
```
## Advanced Features
### Passthrough Mode
Passthrough mode allows you to associate Suada conversations with your application's user system:
```python theme={null}
suada = Suada(
config=SuadaConfig(
api_key="your-api-key",
passthrough_mode=True
)
)
# When using passthrough mode, include external_user_identifier
response = suada.chat(
message="What's our revenue trend?",
external_user_identifier="user-123" # Required in passthrough mode
)
```
### LangChain Integration
The SDK provides seamless integration with LangChain, allowing you to use Suada's capabilities within your LangChain applications:
```python theme={null}
from suada import Suada, SuadaConfig
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain.chat_models import ChatOpenAI
from langchain.prompts import PromptTemplate
from langchain.memory import ConversationBufferMemory
# Initialize Suada
suada = Suada(
config=SuadaConfig(
api_key="your-api-key"
)
)
# Create a Suada tool for LangChain
suada_tool = suada.create_tool(
name="business_analyst",
description="Use this tool to get business insights and analysis",
external_user_identifier="user-123" # Required if using passthrough mode
)
# Create an OpenAI agent with the Suada tool
model = ChatOpenAI(temperature=0)
tools = [suada_tool]
# Create a prompt template
prompt = PromptTemplate.from_template("""
You are a helpful assistant that uses Suada's business analyst capabilities.
Current conversation:
{chat_history}
Human: {input}
Assistant: Let me help you with that.
""")
# Create the agent
agent = create_openai_functions_agent(
llm=model,
tools=tools,
prompt=prompt
)
# Optional: Add conversation memory
memory = ConversationBufferMemory(
memory_key="chat_history",
return_messages=True
)
# Create the executor
executor = AgentExecutor.from_agent_and_tools(
agent=agent,
tools=tools,
memory=memory,
verbose=True
)
# Use the agent
result = executor.invoke({
"input": "What's our revenue trend for the last quarter?"
})
print(result["output"])
```
#### LangChain Best Practices
1. **Tool Configuration**
* Write clear, descriptive tool descriptions
* Set appropriate temperature for your use case
* Implement tool-specific error handling
* Consider adding custom tool validation
2. **Agent Setup**
* Use structured prompts for consistent behavior
* Implement conversation memory when needed
* Consider using different agent types based on your needs
* Test agent behavior with various input types
3. **Error Handling**
* Implement proper error handling for both Suada and LangChain
* Add retry logic for transient failures
* Log agent actions for debugging
* Consider implementing fallback mechanisms
4. **Memory Management**
* Choose appropriate memory types for your use case
* Implement memory cleanup when needed
* Consider memory persistence for long-running conversations
* Handle memory size limitations
5. **Performance Optimization**
* Reuse agent instances when possible
* Implement appropriate timeouts
* Consider caching for frequently used data
* Monitor memory usage in long-running applications
### Privacy Mode
Enable privacy mode to ensure sensitive information is handled with additional security:
```python theme={null}
response = suada.chat(
message="Analyze our financial data",
privacy_mode=True
)
```
## Error Handling
The SDK provides robust error handling with descriptive exceptions:
```python theme={null}
from suada import Suada, SuadaConfig, SuadaError, SuadaAPIError
suada = Suada(config=SuadaConfig(api_key="your-api-key"))
try:
response = suada.chat(
message="What's our revenue?"
)
except SuadaAPIError as e:
# Handle API-specific errors
print(f"API Error: {e.message}, Status: {e.status}, Code: {e.code}")
except SuadaError as e:
# Handle general SDK errors
print(f"SDK Error: {e.message}")
except Exception as e:
# Handle unexpected errors
print(f"Unexpected error: {str(e)}")
```
## Best Practices
1. **Environment Variables**
* Store API keys and sensitive configuration in environment variables
* Use python-dotenv for environment variable management
* Never commit API keys to version control
2. **Error Handling**
* Implement try-except blocks around API calls
* Use specific exception types for better error handling
* Log errors appropriately for debugging
3. **Type Safety**
* Take advantage of Pydantic models and type hints
* Use mypy for static type checking
* Enable strict type checking in your development environment
4. **Response Processing**
* Always check for the presence of optional fields
* Handle missing data gracefully
* Implement proper error handling for data parsing
## Configuration Options
| Option | Type | Required | Description |
| ----------------- | ---- | -------- | -------------------------------------------------------------------------------------------- |
| api\_key | str | Yes | Your Suada API key |
| base\_url | str | No | Custom API endpoint (defaults to [https://suada.ai/api/public](https://suada.ai/api/public)) |
| passthrough\_mode | bool | No | Enable user-specific resources |
## FAQ
### How do I handle rate limiting?
The SDK automatically implements exponential backoff for rate limits. You can customize the retry behavior:
```python theme={null}
from suada import Suada, SuadaConfig
suada = Suada(
config=SuadaConfig(
api_key="your-api-key",
max_retries=3,
retry_delay=1.0
)
)
```
### How do I maintain conversation context?
Use the chat\_history parameter to maintain conversation context:
```python theme={null}
messages = []
response1 = suada.chat(message="How's our revenue?")
messages.append({"role": "user", "content": "How's our revenue?"})
messages.append({"role": "assistant", "content": response1.answer})
response2 = suada.chat(
message="Compare that to last year",
chat_history=messages
)
```
### How can I enable debug logging?
Use Python's built-in logging module:
```python theme={null}
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("suada")
```
### Can I use the SDK in async/await code?
Yes, the SDK provides async support:
```python theme={null}
from suada import AsyncSuada, SuadaConfig
async def main():
async_suada = AsyncSuada(
config=SuadaConfig(api_key="your-api-key")
)
response = await async_suada.chat(
message="What's our performance?"
)
```
## Development Setup
For contributors and developers:
```bash theme={null}
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run type checking
mypy suada
# Run linting
flake8 suada
black suada
isort suada
```
### Support
* Email Support: [hello@suada.ai](mailto:hello@suada.ai)
# React SDK
Source: https://docs.suada.ai/sdks/react
Learn how to integrate Suada with your React application
## Overview
The Suada React SDK provides a seamless way to integrate Suada's AI capabilities into your React applications. Built with modern React practices in mind, it offers hooks, components, and utilities that make it easy to add AI-powered features to your application.
## Prerequisites
* React 16.8.0 or higher (for Hooks support)
* Node.js 16.0.0 or higher
* A Suada API key
* npm or yarn package manager
## Installation
Install the Suada React SDK and its peer dependencies:
```bash theme={null}
# Using npm
npm install @suada/react @suada/core
# Using yarn
yarn add @suada/react @suada/core
```
## Quick Start
Here's a basic example to get you started:
```tsx theme={null}
import { SuadaProvider, ChatComponent } from '@suada/react';
function App() {
return (
console.log('Message sent:', message)}
onResponseReceived={(response) => console.log('Response:', response)}
/>
);
}
```
## Authentication
### Setting up your API Key
We recommend storing your API key in environment variables:
```env theme={null}
# .env.local
REACT_APP_SUADA_API_KEY=your-api-key
```
For production, ensure you're using appropriate environment configuration:
```env theme={null}
# .env.production
REACT_APP_SUADA_API_KEY=your-production-api-key
REACT_APP_SUADA_BASE_URL=https://api.suada.ai
```
### Configuring the Provider
Wrap your application with `SuadaProvider`:
```tsx theme={null}
import { SuadaProvider } from '@suada/react';
function App() {
return (
);
}
```
## Core Components
### Chat Component
A pre-built chat interface component:
```tsx theme={null}
import { ChatComponent } from '@suada/react';
function ChatInterface() {
return (
{
console.log('Message:', message);
}}
onResponseReceived={(response) => {
console.log('Response:', response);
}}
/>
);
}
```
#### Props
| Prop | Type | Required | Description |
| ------------------ | ---------------------------- | -------- | ---------------------------------- |
| theme | 'light' \| 'dark' | No | UI theme (defaults to 'light') |
| placeholder | string | No | Input placeholder text |
| initialMessages | Message\[] | No | Pre-loaded chat messages |
| privacyMode | boolean | No | Enable enhanced privacy features |
| onMessageSubmit | (message: string) => void | Yes | Called when a message is submitted |
| onResponseReceived | (response: Response) => void | Yes | Called when a response is received |
| onError | (error: Error) => void | No | Called when an error occurs |
### Integration Components
#### Integration Manager
The main component for managing integrations:
```tsx theme={null}
import { IntegrationManager } from '@suada/react';
function IntegrationsPage() {
return (
{
console.log(`${integration.provider} connected`);
}}
onIntegrationDisconnected={(integration) => {
console.log(`${integration.provider} disconnected`);
}}
layout="grid"
className="custom-integration-manager"
/>
);
}
```
#### Integration Button
A standalone button for connecting services:
```tsx theme={null}
import { IntegrationButton } from '@suada/react';
function ConnectButton() {
return (
console.log('Connected:', result)}
onError={(error) => console.error('Error:', error)}
/>
);
}
```
## Hooks
### useSuada
The main hook for accessing Suada functionality:
```tsx theme={null}
import { useSuada } from '@suada/react';
function ChatFeature() {
const { sendMessage, isLoading, error } = useSuada();
const handleSend = async () => {
try {
const response = await sendMessage({
message: "What's the latest update?",
privacyMode: true
});
console.log('Response:', response);
} catch (error) {
console.error('Error:', error);
}
};
return (