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

https://suada.ai/api/public

​
Authentication

The API uses API keys for authentication. You can obtain your API key from the Suada Dashboard.

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.

X-External-User-Id: your-user-id

Or as part of the request body:

{
  "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:

PlanRate Limit
PRO300 requests per minute
ENTERPRISE1000 requests per minute

Rate limit headers are included in all responses:

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:

{
  "error": "Detailed error message"
}

​
Available Endpoints

​
Chat

Send Message

Send a message to the business analyst

​
Integrations

List Integrations

Get available integrations

Connect Integration

Initialize OAuth flow for an integration

Integration Callback

Handle OAuth callback

Select Property

Select integration property

Integration Status

Get integration status

Disconnect Integration

Disconnect an integration

​
Model Context Protocol (MCP)

Define Context

Define context for the business analyst

List Contexts

Get available contexts

Get Context

Get details about a specific context

Update Context

Update an existing context

Delete 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.

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?"}'

​
SDKs

We provide official SDKs for several platforms to help you integrate with Suada:

Frontend SDKs

React, Angular, Vue, React Native, and Vanilla JS

Backend SDKs

Node.js and Python