Documentation

Introduction

Schwiha.ai is a complete AI workspace platform. Use it through our web app, embed it as a chatbot widget, or build on top of it with our TypeScript SDK and REST API. All data is stored in the EU, GDPR-compliant, and never used to train AI models.

This documentation is organized into three areas:

• End Users — how to use Schwiha.ai as a team member
• Developers — SDK, API, webhooks, and self-hosting
• Integrations — connecting Slack, Notion, GitHub, Google Drive

Quickstart

Get up and running in under 5 minutes with the TypeScript SDK.

1. Install

npm install @schwiha/sdk

2. Initialize

import { SchwihaClient } from '@schwiha/sdk';

const client = new SchwihaClient({
  apiKey: process.env.SCHWIHA_API_KEY,
  workspaceId: 'ws_your_workspace_id',
});

3. Send your first message

const response = await client.chat.complete({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Summarize our Q3 sales report.' }
  ],
});

console.log(response.content);
// → "Q3 Revenue: €2.4M (+23% YoY). Enterprise segment..."

4. Stream responses

const stream = await client.chat.stream({
  model: 'claude-3-5-sonnet',
  messages: [{ role: 'user', content: 'Draft a press release.' }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.delta);
}

Core Concepts

Workspaces

A workspace is the top-level container for all resources: chat sessions, documents, launchpads, and team members. Every API call is scoped to a workspace. Users can be members of multiple workspaces with different permission levels (Admin, Editor, Viewer).

Launchpads

Launchpads are pre-configured AI environments. You define a system prompt, data sources (documents, websites, APIs), and the model. Users chat without any further setup. Launchpads can be embedded as widgets or shared via link.

Vector Database

Every workspace includes a built-in vector database. Documents you upload are automatically chunked, embedded, and indexed. The AI retrieves relevant chunks to answer questions accurately — this is Retrieval-Augmented Generation (RAG).

Models

Schwiha.ai routes requests to the underlying model of your choice. You can switch models per-request without changing your application code. Supported: gpt-4o, gpt-4o-mini, claude-3-5-sonnet, gemini-pro, mistral-large, and more.

Using Chat

The chat interface is the primary way to interact with AI on Schwiha.ai. You can access it at schwiha.ai/team/your-workspace.

Sending messages

Type your message in the input box and press Enter or click the send button. Use Shift+Enter for a new line. Responses stream in real time.

Switching AI models

Click the model selector in the top bar to switch between GPT-4o, Claude, Gemini, and others. The model selection persists for your current session.

Conversation history

All conversations are saved automatically. Access previous conversations from the left sidebar. You can search, filter by date, and export any conversation as Markdown or PDF.

Reactions and sharing

React to any AI response with emoji reactions to give feedback. Share a conversation with a teammate by clicking the share icon — they'll get a read-only link that requires workspace membership to view.

Voice input

Click the microphone icon to dictate your message. Speech is transcribed in real time using your browser's native speech API. Voice input works in Chrome, Edge, and Safari.

Documents & Files

Upload any file to the vector database and your AI will be able to search, cite, and reason over its contents.

Supported formats

• Documents: PDF, DOCX, PPTX, TXT, Markdown, HTML
• Data: XLSX, CSV, JSON
• Images: PNG, JPG, WebP (with vision models)
• Web: paste any URL and we'll crawl and index it

Uploading files

Drag and drop files into the chat input, or use the paperclip icon. Files uploaded to a chat are available for that conversation only. To make a file available across all conversations and to the vector database, upload it via Settings → Knowledge Base.

Citing sources

When the AI answers from an indexed document, it will cite the specific page and section. Click a citation to jump directly to the source material in the document viewer.

File size limits

• Starter: 5 MB per file
• Business: 100 MB per file
• Enterprise: unlimited

Collaboration

Schwiha.ai is built for teams. Multiple users can view and contribute to shared conversations in real time.

Shared conversations

Conversations created inside a shared workspace are visible to all workspace members by default. You can restrict a conversation to specific users via the privacy settings (lock icon in the top bar).

Presence indicators

See who is active in a conversation right now via the avatar stack in the top bar. Hover over an avatar to see their name and current status.

Inline comments

Select any part of an AI response and click "Comment" to leave a note for your team. Comments are visible to all workspace members and can be resolved once addressed.

Roles and permissions

• Admin: full access, can invite users, manage billing and settings
• Editor: can create conversations, launchpads, and upload documents
• Viewer: read-only access to shared conversations

AI Models

Schwiha.ai gives you access to the best models from every major provider, in one place.

Model	Provider	Best for
gpt-4o	OpenAI	General purpose, vision, code
gpt-4o-mini	OpenAI	Fast, cost-efficient tasks
claude-3-5-sonnet	Anthropic	Long documents, writing, analysis
gemini-pro	Google	Multimodal, long context
mistral-large	Mistral AI	EU-hosted, multilingual
custom	Your API	Enterprise: bring your own model

Authentication

All API requests must include your API key in the Authorization header as a Bearer token.

Generating an API key

Go to Settings → API Keys in your workspace and click New API Key. Keys are workspace-scoped and can have read-only or read-write permissions. Copy the key immediately — it won't be shown again.

Using the key

curl https://api.schwiha.ai/v1/chat \
  -H "Authorization: Bearer sk_schwiha_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Security best practices

• Never commit API keys to version control
• Use environment variables: process.env.SCHWIHA_API_KEY
• Create separate keys for development and production
• Rotate keys regularly from the dashboard
• Use read-only keys when write access is not needed

SSO (Enterprise)

Enterprise workspaces can configure SAML 2.0 SSO with any identity provider (Okta, Azure AD, Google Workspace, etc.). Go to Settings → Security → SSO to set up your identity provider.

TypeScript SDK

The official @schwiha/sdk package provides a fully-typed client for Node.js and browser environments.

Installation

npm install @schwiha/sdk
# or
pnpm add @schwiha/sdk
# or
yarn add @schwiha/sdk

Available clients

• client.chat — completions and streaming
• client.embed — generate text embeddings
• client.files — upload and manage documents
• client.vector — query the vector database directly
• client.workspaces — workspace and user management
• client.launchpads — create and configure launchpads

Upload a file and query it

// Upload a PDF to the vector database
const file = await client.files.upload({
  file: fs.readFileSync('./report.pdf'),
  filename: 'Q3-Report.pdf',
  collection: 'quarterly-reports',
});

// Ask a question over it
const response = await client.chat.complete({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'What were the key findings?' }],
  contextCollections: ['quarterly-reports'],
});

console.log(response.content);
// → "The key findings from Q3 are: 1. Revenue grew 23%..."
// → response.citations: [{ file: 'Q3-Report.pdf', page: 4 }]

Error handling

import { SchwihaError, RateLimitError } from '@schwiha/sdk';

try {
  const response = await client.chat.complete({ ... });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof SchwihaError) {
    console.log(`API error ${err.status}: ${err.message}`);
  }
}

Launchpads

Launchpads are pre-configured AI environments that your team or external users can chat with directly — no setup required on their end.

Creating a launchpad via API

const launchpad = await client.launchpads.create({
  name: 'Support Bot',
  systemPrompt: `You are a helpful support agent for Acme Corp.
Answer questions about our products using the provided documentation.
Be friendly, concise, and always cite your sources.`,
  model: 'gpt-4o',
  contextCollections: ['support-docs', 'faq'],
  allowedDomains: ['acme.com'],  // restrict widget embedding
});

Embedding as a widget

Once created, embed any launchpad on your website with a single script tag:

<script
  defer
  src="https://schwiha.ai/widget.js"
  data-id="lp_your_launchpad_id"
  data-primary-color="#3ddc84"
  data-position="bottom-right"
/>

Sharing via link

Every launchpad gets a shareable URL: https://schwiha.ai/chat/lp_your_id. You can require workspace login or allow anonymous access (configurable per launchpad).

Vector Database

Every workspace includes a built-in vector database powered by pgvector. Documents are automatically chunked and embedded when you upload them. You can also query the vector DB directly for custom RAG pipelines.

Direct vector search

// Semantic search across a collection
const results = await client.vector.search({
  query: 'refund policy international orders',
  collection: 'support-docs',
  topK: 5,
  minScore: 0.75,
});

results.forEach(r => {
  console.log(`[${r.score.toFixed(2)}] ${r.content}`);
  console.log(`Source: ${r.metadata.filename}, page ${r.metadata.page}`);
});

Upsert custom vectors

// Insert your own pre-computed embeddings
await client.vector.upsert({
  collection: 'products',
  vectors: [
    {
      id: 'prod_123',
      embedding: yourEmbeddingArray, // float32[]
      content: 'Product name and description...',
      metadata: { sku: 'ABC-123', category: 'electronics' },
    }
  ],
});

Collections

Vectors are organized into named collections. A workspace can have unlimited collections. Collections are isolated — a search in one collection won't return results from another. Use collections to separate data by department, project, or access level.

Webhooks

Receive real-time HTTP notifications when events happen in your workspace.

Available events

• chat.message.created — a new message was sent
• chat.conversation.created — a new conversation was started
• file.uploaded — a document was uploaded and indexed
• launchpad.conversation.created — a widget conversation started
• workspace.user.invited — a new user joined the workspace
• billing.subscription.updated — plan changed or payment processed

Registering a webhook

const webhook = await client.workspaces.webhooks.create({
  url: 'https://your-app.com/webhooks/schwiha',
  events: ['chat.message.created', 'file.uploaded'],
  secret: 'your_signing_secret',  // used to verify payloads
});

Verifying payloads

import { verifyWebhookSignature } from '@schwiha/sdk';

app.post('/webhooks/schwiha', (req, res) => {
  const isValid = verifyWebhookSignature({
    payload: req.rawBody,
    signature: req.headers['x-schwiha-signature'],
    secret: process.env.WEBHOOK_SECRET,
  });

  if (!isValid) return res.status(401).send('Unauthorized');

  const event = req.body;
  console.log(`Event: ${event.type}`, event.data);
  res.status(200).send('OK');
});

POST/v1/chat

Create a chat completion. Compatible with the OpenAI Chat Completions API format.

Request body

Parameter	Type	Description
model	string	Required. Model ID, e.g. gpt-4o
messages	array	Required. Array of {role, content} objects
stream	boolean	Optional. Enable SSE streaming. Default: false
temperature	number	Optional. 0.0–2.0. Default: 0.7
max_tokens	integer	Optional. Max tokens in the response
context_collections	array	Optional. Vector DB collections to search
workspace_id	string	Required if not set in client constructor

Response

{
  "id": "chat_abc123",
  "content": "Based on your Q3 data, revenue grew 23% YoY...",
  "model": "gpt-4o",
  "citations": [
    { "file": "Q3-Report.pdf", "page": 4, "score": 0.94 }
  ],
  "usage": {
    "prompt_tokens": 142,
    "completion_tokens": 318,
    "total_tokens": 460
  },
  "created_at": "2026-05-14T10:22:33Z"
}

POST/v1/embed

Generate text embeddings using the workspace's configured embedding model (default: text-embedding-3-large).

Request body

Parameter	Type	Description
input	string | array	Required. Text or array of texts to embed
model	string	Optional. Embedding model ID
dimensions	integer	Optional. Output dimensions (256–3072)

Response

{
  "embeddings": [
    { "index": 0, "embedding": [0.002, -0.009, 0.014, ...] }
  ],
  "model": "text-embedding-3-large",
  "usage": { "total_tokens": 12 }
}

GET/v1/files

List all files uploaded to the workspace's vector database.

Query parameters

Parameter	Type	Description
collection	string	Optional. Filter by collection name
limit	integer	Optional. Max results (default: 20, max: 100)
cursor	string	Optional. Pagination cursor from previous response

Response

{
  "files": [
    {
      "id": "file_xyz789",
      "filename": "Q3-Report.pdf",
      "collection": "quarterly-reports",
      "size_bytes": 2048000,
      "chunk_count": 142,
      "status": "indexed",
      "created_at": "2026-05-01T09:00:00Z"
    }
  ],
  "next_cursor": "cursor_abc",
  "total": 47
}

GET/v1/workspaces

List all workspaces the authenticated API key has access to.

Response

{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "Acme Corp",
      "plan": "business",
      "member_count": 28,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Get a single workspace

GET /v1/workspaces/{workspace_id}

{
  "id": "ws_abc123",
  "name": "Acme Corp",
  "plan": "business",
  "member_count": 28,
  "settings": {
    "default_model": "gpt-4o",
    "sso_enabled": true,
    "audit_log_enabled": true
  }
}

Slack Integration

Connect Schwiha.ai to Slack and let your team interact with AI directly in channels and DMs.

Setup

1. Go to Settings → Integrations → Slack in your workspace
2. Click Connect to Slack and authorize the app
3. Choose which workspaces to expose to which Slack channels
4. Mention @Schwiha in any channel to start chatting

Usage in Slack

@Schwiha Summarize this week's support tickets
@Schwiha Draft a reply to this customer complaint
@Schwiha /switch-model claude-3-5-sonnet

Channel mapping

You can map specific Slack channels to specific launchpads, so #support uses your Support Bot launchpad and #sales uses your Sales AI launchpad — each with their own data sources and persona.

Notion Integration

Sync your Notion pages and databases with Schwiha.ai's vector database so your AI can search and reason over your team's knowledge base.

Setup

1. Go to Settings → Integrations → Notion
2. Click Connect Notion and grant access to the pages you want to sync
3. Select the pages and databases to include in your vector database
4. Schwiha.ai syncs automatically — new pages are indexed within minutes

What gets synced

• Page titles and body content
• Database properties and rows
• Inline tables and callout blocks
• Linked databases (with permission)

GitHub Integration

Connect your GitHub repositories to enable AI-powered code review, documentation generation, and codebase Q&A.

Setup

1. Go to Settings → Integrations → GitHub
2. Install the Schwiha GitHub App on your organization or repository
3. Select which repositories to index
4. Configure which events trigger AI actions (pull requests, issues, etc.)

Pull request review

When a PR is opened, Schwiha.ai automatically reviews the diff, checks for common issues, and posts a summary comment. You can customize the review prompt per repository.

Codebase Q&A

Ask questions about your codebase in natural language: "Where is the payment processing logic?" or "How does the auth middleware work?". The AI searches indexed code semantically and provides answers with file references.

Google Drive Integration

Index your Google Drive files so your AI can search and answer questions over Docs, Sheets, Slides, and PDFs stored in Drive.

Setup

1. Go to Settings → Integrations → Google Drive
2. Sign in with Google and grant read access to Drive
3. Select specific folders or drives to sync
4. Files are indexed and kept in sync automatically

Supported file types

• Google Docs → converted to plain text and indexed
• Google Sheets → indexed as structured data
• Google Slides → slide titles and speaker notes indexed
• PDFs, DOCX, XLSX → extracted and indexed

Access control

Schwiha.ai respects Google Drive sharing settings. Files marked as private in Drive are only accessible to users who have permission to view them in Drive — this is enforced at query time using the user's Google OAuth token.