> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> 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
```

<Note>
  Keep your API keys secure and never share them in publicly accessible areas such as GitHub, client-side code, etc.
</Note>

## 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
}
```

<Warning>
  Ensure that external user identifiers are consistent across requests for the same user to maintain proper resource association.
</Warning>

## 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

<CardGroup cols={2}>
  <Card title="Send Message" icon="message" href="/api-reference/chat/send-message">
    Send a message to the business analyst
  </Card>
</CardGroup>

### Integrations

<CardGroup cols={2}>
  <Card title="List Integrations" icon="list" href="/api-reference/integrations/list">
    Get available integrations
  </Card>

  <Card title="Connect Integration" icon="plug" href="/api-reference/integrations/connect">
    Initialize OAuth flow for an integration
  </Card>

  <Card title="Integration Callback" icon="arrow-right-to-bracket" href="/api-reference/integrations/callback">
    Handle OAuth callback
  </Card>

  <Card title="Select Property" icon="hand-pointer" href="/api-reference/integrations/select-property">
    Select integration property
  </Card>

  <Card title="Integration Status" icon="signal-bars" href="/api-reference/integrations/status">
    Get integration status
  </Card>

  <Card title="Disconnect Integration" icon="plug-circle-xmark" href="/api-reference/integrations/disconnect">
    Disconnect an integration
  </Card>
</CardGroup>

### Model Context Protocol (MCP)

<CardGroup cols={2}>
  <Card title="Define Context" icon="brain-circuit" href="/api-reference/mcp/define-context">
    Define context for the business analyst
  </Card>

  <Card title="List Contexts" icon="list-check" href="/api-reference/mcp/list-contexts">
    Get available contexts
  </Card>

  <Card title="Get Context" icon="magnifying-glass" href="/api-reference/mcp/get-context">
    Get details about a specific context
  </Card>

  <Card title="Update Context" icon="pen-to-square" href="/api-reference/mcp/update-context">
    Update an existing context
  </Card>

  <Card title="Delete Context" icon="trash" href="/api-reference/mcp/delete-context">
    Delete a context
  </Card>
</CardGroup>

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

<CodeGroup>
  ```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"
  }
  ```
</CodeGroup>

## SDKs

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

<CardGroup cols={2}>
  <Card title="Frontend SDKs" icon="browser" href="/sdks/overview#frontend-sdks">
    React, Angular, Vue, React Native, and Vanilla JS
  </Card>

  <Card title="Backend SDKs" icon="server" href="/sdks/overview#backend-sdks">
    Node.js and Python
  </Card>
</CardGroup>