From ad836760fba8c52943a75f04b9991caf015a542e Mon Sep 17 00:00:00 2001 From: Waleed Latif Date: Sat, 11 Apr 2026 11:26:21 -0700 Subject: [PATCH 1/3] feat(docs): fill documentation gaps across platform features --- apps/docs/content/docs/en/blocks/function.mdx | 112 +++++++- .../docs/en/execution/api-deployment.mdx | 262 ++++++++++++++++++ apps/docs/content/docs/en/execution/chat.mdx | 174 ++++++++++++ apps/docs/content/docs/en/execution/costs.mdx | 15 + apps/docs/content/docs/en/execution/index.mdx | 37 ++- apps/docs/content/docs/en/execution/meta.json | 2 +- .../docs/en/knowledgebase/connectors.mdx | 42 ++- .../content/docs/en/knowledgebase/tags.mdx | 48 +++- .../content/docs/en/mcp/deploy-workflows.mdx | 61 +++- apps/docs/content/docs/en/mcp/index.mdx | 44 ++- .../content/docs/en/tools/custom-tools.mdx | 162 +++++++++++ apps/docs/content/docs/en/tools/meta.json | 1 + apps/docs/content/docs/en/variables/index.mdx | 90 ++++++ apps/docs/content/docs/en/variables/meta.json | 5 + 14 files changed, 1020 insertions(+), 35 deletions(-) create mode 100644 apps/docs/content/docs/en/execution/api-deployment.mdx create mode 100644 apps/docs/content/docs/en/execution/chat.mdx create mode 100644 apps/docs/content/docs/en/tools/custom-tools.mdx create mode 100644 apps/docs/content/docs/en/variables/index.mdx create mode 100644 apps/docs/content/docs/en/variables/meta.json diff --git a/apps/docs/content/docs/en/blocks/function.mdx b/apps/docs/content/docs/en/blocks/function.mdx index 05510aa3d22..bfad3468b1f 100644 --- a/apps/docs/content/docs/en/blocks/function.mdx +++ b/apps/docs/content/docs/en/blocks/function.mdx @@ -2,10 +2,12 @@ title: Function --- +import { Callout } from 'fumadocs-ui/components/callout' +import { Tab, Tabs } from 'fumadocs-ui/components/tabs' import { Image } from '@/components/ui/image' import { FAQ } from '@/components/ui/faq' -The Function block executes custom JavaScript or TypeScript code in your workflows. Transform data, perform calculations, or implement custom logic. +The Function block executes custom JavaScript, TypeScript, or Python code in your workflows. Transform data, perform calculations, or implement custom logic.
+ ```javascript title="loyalty-calculator.js" // Process customer data and calculate loyalty score const { purchaseHistory, accountAge, supportTickets } = ; @@ -64,6 +68,112 @@ return { metrics: { spendScore, frequencyScore, supportScore } }; ``` + + +```python title="loyalty-calculator.py" +import json + +# Reference outputs from other blocks using angle bracket syntax +data = json.loads('') +purchase_history = data["purchaseHistory"] +account_age = data["accountAge"] +support_tickets = data["supportTickets"] + +# Calculate metrics +total_spent = sum(p["amount"] for p in purchase_history) +purchase_frequency = len(purchase_history) / (account_age / 365) +ticket_ratio = support_tickets["resolved"] / support_tickets["total"] + +# Calculate loyalty score (0-100) +spend_score = min(total_spent / 1000 * 30, 30) +frequency_score = min(purchase_frequency * 20, 40) +support_score = ticket_ratio * 30 + +loyalty_score = round(spend_score + frequency_score + support_score) + +tier = "Platinum" if loyalty_score >= 80 else "Gold" if loyalty_score >= 60 else "Silver" + +result = { + "customer": data["name"], + "loyaltyScore": loyalty_score, + "loyaltyTier": tier, + "metrics": { + "spendScore": spend_score, + "frequencyScore": frequency_score, + "supportScore": support_score + } +} +print(json.dumps(result)) +``` + + + +## Python Support + +The Function block supports Python as an alternative to JavaScript. Python code runs in a secure [E2B](https://e2b.dev) cloud sandbox. + +{/* TODO: Screenshot of the Function block with Python language selected */} + +### Enabling Python + +Select **Python** from the language dropdown in the Function block. Python execution requires E2B to be enabled on your Sim instance. + + +If you don't see Python as an option in the language dropdown, E2B is not enabled. This only applies to self-hosted instances — E2B is enabled by default on sim.ai. + + + +Python code always runs in the E2B sandbox, even for simple scripts without imports. This ensures a secure, isolated execution environment. + + +### Returning Results + +In Python, print your result as JSON to stdout. The Function block captures stdout and makes it available via ``: + +```python title="example.py" +import json + +data = {"status": "processed", "count": 42} +print(json.dumps(data)) +``` + +### Available Libraries + +The E2B sandbox includes the Python standard library (`json`, `re`, `datetime`, `math`, `os`, `collections`, etc.) and common packages like `matplotlib` for visualization. Charts generated with matplotlib are captured as images automatically. + + + The exact set of pre-installed packages depends on the E2B sandbox configuration. If a package you need isn't available, consider calling an external API from your code instead. + + +### Matplotlib Charts + +When your Python code generates matplotlib figures, they are automatically captured and returned as base64-encoded PNG images in the output: + +```python title="chart.py" +import matplotlib.pyplot as plt +import json + +data = json.loads('') + +plt.figure(figsize=(10, 6)) +plt.bar(data["labels"], data["values"]) +plt.title("Monthly Revenue") +plt.xlabel("Month") +plt.ylabel("Revenue ($)") +plt.savefig("chart.png") +plt.show() +``` + +{/* TODO: Screenshot of Python code execution output in the logs panel */} + +### JavaScript vs. Python + +| | JavaScript | Python | +|--|-----------|--------| +| **Execution** | Local VM (fast) or E2B sandbox (with imports) | Always E2B sandbox | +| **Returning results** | `return { ... }` | `print(json.dumps({ ... }))` | +| **HTTP requests** | `fetch()` built-in | `requests` or `httpx` | +| **Best for** | Quick transforms, JSON manipulation | Data science, charting, complex math | ## Best Practices diff --git a/apps/docs/content/docs/en/execution/api-deployment.mdx b/apps/docs/content/docs/en/execution/api-deployment.mdx new file mode 100644 index 00000000000..43ec5cea3e4 --- /dev/null +++ b/apps/docs/content/docs/en/execution/api-deployment.mdx @@ -0,0 +1,262 @@ +--- +title: API Deployment +--- + +import { Callout } from 'fumadocs-ui/components/callout' +import { Tab, Tabs } from 'fumadocs-ui/components/tabs' +import { FAQ } from '@/components/ui/faq' + +Deploy your workflow as a REST API endpoint that applications can call directly. Supports synchronous, streaming, and asynchronous execution modes. + +## Deploying a Workflow + +1. Open your workflow and click **Deploy** +2. The **General** tab shows deployment status — click **Deploy** to publish +3. Switch to the **API** tab to see your endpoint URL and code examples + +{/* TODO: Screenshot of the API tab in the deploy modal showing code examples */} + +Once deployed, your workflow is available at: + +``` +POST https://sim.ai/api/workflows/{workflow-id}/execute +``` + + + API executions run against the active deployment snapshot. After making canvas changes, click **Update** in the Deploy modal to publish a new version. + + +## Authentication + +By default, API endpoints require an API key in the `x-api-key` header. You can generate keys in **Settings → Sim Keys**. + +```bash +curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \ + -H "Content-Type: application/json" \ + -H "x-api-key: $SIM_API_KEY" \ + -d '{ "input": "Hello" }' +``` + +### Public APIs + +You can make an API endpoint public so it doesn't require authentication. This is useful for public-facing integrations or webhooks from external services. + +{/* TODO: Screenshot of the public/private API toggle */} + + + Public endpoints can be called by anyone with the URL. Only use this for workflows that don't expose sensitive data or perform sensitive actions. + + +## Execution Modes + +The API tab in the Deploy modal shows code examples for each mode in **cURL**, **Python**, **JavaScript**, and **TypeScript**. + +### Synchronous + +The default mode. Send a request and wait for the complete response: + + + +```bash +curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \ + -H "Content-Type: application/json" \ + -H "x-api-key: $SIM_API_KEY" \ + -d '{ "input": "Summarize this article" }' +``` + + +```python +import requests +import os + +response = requests.post( + "https://sim.ai/api/workflows/{workflow-id}/execute", + headers={ + "Content-Type": "application/json", + "x-api-key": os.environ.get("SIM_API_KEY") + }, + json={"input": "Summarize this article"} +) + +print(response.json()) +``` + + + +### Streaming + +Stream the response as it's generated. Choose which block outputs to stream using the output selector in the API tab. + +{/* TODO: Screenshot of the streaming output selector dropdown */} + + + +```bash +curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \ + -H "Content-Type: application/json" \ + -H "x-api-key: $SIM_API_KEY" \ + -d '{ + "input": "Write a long essay", + "stream": true, + "selectedOutputs": ["agent_1.content"] + }' +``` + + +```python +import requests +import os + +response = requests.post( + "https://sim.ai/api/workflows/{workflow-id}/execute", + headers={ + "Content-Type": "application/json", + "x-api-key": os.environ.get("SIM_API_KEY") + }, + json={ + "input": "Write a long essay", + "stream": True, + "selectedOutputs": ["agent_1.content"] + }, + stream=True +) + +for line in response.iter_lines(): + if line: + print(line.decode()) +``` + + + +### Asynchronous + +For long-running workflows, use async mode to start a job and poll for results. Set the `X-Execution-Mode: async` header to submit the workflow and receive a job ID immediately without waiting for completion. + + + +```bash +curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \ + -H "Content-Type: application/json" \ + -H "x-api-key: $SIM_API_KEY" \ + -H "X-Execution-Mode: async" \ + -d '{ "input": "Process this large dataset" }' +``` + +**Response** (HTTP 202): +```json +{ + "success": true, + "async": true, + "jobId": "run_abc123", + "executionId": "exec_xyz", + "message": "Workflow execution queued", + "statusUrl": "https://sim.ai/api/jobs/run_abc123" +} +``` + + +```bash +curl https://sim.ai/api/jobs/{jobId} \ + -H "x-api-key: $SIM_API_KEY" +``` + +**Response** (while processing): +```json +{ + "success": true, + "taskId": "run_abc123", + "status": "processing", + "metadata": { + "createdAt": "2025-09-10T12:00:00.000Z", + "startedAt": "2025-09-10T12:00:01.000Z" + }, + "estimatedDuration": 300000 +} +``` + +**Response** (when completed): +```json +{ + "success": true, + "taskId": "run_abc123", + "status": "completed", + "metadata": { + "createdAt": "2025-09-10T12:00:00.000Z", + "startedAt": "2025-09-10T12:00:01.000Z", + "completedAt": "2025-09-10T12:00:05.000Z", + "duration": 4000 + }, + "output": { "result": "..." } +} +``` + + + +#### Job Status Values + +| Status | Description | +|--------|-------------| +| `queued` | Job is waiting to be picked up | +| `processing` | Workflow is actively executing | +| `completed` | Finished successfully — `output` field contains the result | +| `failed` | Execution failed — `error` field contains the message | + +Poll the `statusUrl` returned in the initial response until the status is `completed` or `failed`. + +#### Execution Time Limits + +Async jobs can run significantly longer than synchronous requests: + +| Plan | Sync Limit | Async Limit | +|------|-----------|-------------| +| **Community** | 5 minutes | 90 minutes | +| **Pro / Max / Team / Enterprise** | 50 minutes | 90 minutes | + +If a job exceeds its time limit, it is automatically marked as `failed`. + +#### Job Retention + +Completed and failed job results are retained for **24 hours**. After that, the job data is cleaned up and the status endpoint returns `404`. If you need results longer, retrieve and store them on your end after completion. + +#### Capacity Limits + +If the execution queue is full, the API returns a `503` response with a `Retry-After` header: + +```json +{ + "error": "Service temporarily at capacity", + "retryAfterSeconds": 10 +} +``` + +Wait the indicated number of seconds before retrying. + + + Async mode always runs against the deployed version. It does not support draft state, block overrides, or partial execution options like `runFromBlock` or `stopAfterBlockId`. + + +## API Key Management + +Generate and manage API keys in **Settings → Sim Keys**: + +- **Create** new keys for different applications or environments +- **Revoke** keys that are no longer needed +- Keys are scoped to your workspace + + + The API tab in the Deploy modal shows a masked version of your key in the code examples. Copy the examples directly — they include the correct authentication header. + + +## Rate Limits + +API calls are subject to rate limits based on your plan. Rate limit details are returned in response headers (`X-RateLimit-*`) and in the response body. Use async mode for high-volume or long-running workloads. + +For detailed rate limit information and the logs/webhooks API, see [External API](/execution/api). + + diff --git a/apps/docs/content/docs/en/execution/chat.mdx b/apps/docs/content/docs/en/execution/chat.mdx new file mode 100644 index 00000000000..5b10df13300 --- /dev/null +++ b/apps/docs/content/docs/en/execution/chat.mdx @@ -0,0 +1,174 @@ +--- +title: Chat Deployment +--- + +import { Callout } from 'fumadocs-ui/components/callout' +import { Tab, Tabs } from 'fumadocs-ui/components/tabs' +import { FAQ } from '@/components/ui/faq' + +Deploy your workflow as a conversational chat interface that users can interact with via a shareable link or embedded widget. Chat supports multi-turn conversations, file uploads, and voice input. + +## Overview + +Chat deployment wraps your workflow in a real-time conversational UI with: +- Multi-turn conversations with streaming responses +- File uploads (up to 15 files per message, 10 MB each) +- Voice input and text-to-speech output +- Customizable branding (title, welcome message, logo) +- Access control (public, password, email, or SSO) + +{/* TODO: Screenshot of a deployed chat interface (end-user view) */} + + +Chat executions run against your workflow's active deployment snapshot. Publish a new deployment after making canvas changes so the chat uses the updated version. + + +## Creating a Chat + +1. Open your workflow and click **Deploy** +2. Select the **Chat** tab +3. Configure: + - **Identifier**: URL slug for the chat (e.g., `support-bot` becomes `sim.ai/chat/support-bot`). Lowercase letters, numbers, and hyphens only. + - **Title**: Display name shown in the chat header + - **Output Blocks**: Select which block outputs are returned to the user (at least one required) + - **Welcome Message**: Greeting shown when the chat loads (default: "Hi there! How can I help you today?") + - **Access Control**: Who can access the chat (see below) +4. Click **Launch** + +{/* TODO: Screenshot of the chat deployment configuration panel in the deploy modal */} + +## Access Control + +| Mode | Description | +|------|-------------| +| **Public** | Anyone with the link can chat | +| **Password** | Users must enter a password before chatting | +| **Email** | Only verified emails/domains can access. Users receive a 6-digit OTP code via email | +| **SSO** | OIDC-based single sign-on (enterprise) | + +{/* TODO: Screenshot of access control settings (public/password/email whitelist) */} + +For email and SSO: +- Exact email: `user@example.com` +- Domain pattern: `@example.com` (allows any email from that domain) + +## Sharing + +### Direct Link + +``` +https://sim.ai/chat/your-identifier +``` + +### Iframe + +```html + +``` + +## API Submission + +Send messages to a chat programmatically. The response is streamed using server-sent events (SSE). + + + +```bash +curl -X POST https://sim.ai/api/chat/your-identifier \ + -H "Content-Type: application/json" \ + -d '{ + "input": "Hello, I need help with my order", + "conversationId": "optional-conversation-id" + }' +``` + + +```typescript +const response = await fetch('https://sim.ai/api/chat/your-identifier', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + input: 'Hello, I need help with my order', + conversationId: 'optional-conversation-id' + }) +}); + +// Response is an SSE stream +const reader = response.body?.getReader(); +const decoder = new TextDecoder(); + +while (true) { + const { done, value } = await reader!.read(); + if (done) break; + console.log(decoder.decode(value)); +} +``` + + + +### With File Uploads + +```bash +curl -X POST https://sim.ai/api/chat/your-identifier \ + -H "Content-Type: application/json" \ + -d '{ + "input": "What does this document say?", + "files": [{ + "name": "report.pdf", + "type": "application/pdf", + "size": 1048576, + "data": "data:application/pdf;base64,..." + }] + }' +``` + +### Protected Chats + +For password-protected chats: +```bash +curl -X POST https://sim.ai/api/chat/your-identifier \ + -H "Content-Type: application/json" \ + -d '{ "password": "secret", "input": "Hello" }' +``` + +For email-protected chats, authenticate first with OTP: +```bash +# Step 1: Request OTP +curl -X POST https://sim.ai/api/chat/your-identifier/otp \ + -H "Content-Type: application/json" \ + -d '{ "email": "allowed@example.com" }' + +# Step 2: Verify OTP +curl -X PUT https://sim.ai/api/chat/your-identifier/otp \ + -H "Content-Type: application/json" \ + -d '{ "email": "allowed@example.com", "otp": "123456" }' + +# Step 3: Send messages (include the auth cookie from step 2) +curl -X POST https://sim.ai/api/chat/your-identifier \ + -H "Content-Type: application/json" \ + -b "chat_auth_cookie" \ + -d '{ "input": "Hello" }' +``` + +## Troubleshooting + +**Chat returns 403** - The deployment is inactive. Re-deploy the workflow. + +**"At least one output block is required"** - Select at least one block output in the Output Blocks configuration. + +**OTP email not arriving** - Check the email address is correct and check spam folders. OTP codes expire and can be resent after a 30-second cooldown. + +**Chat not loading in iframe** - Check your site's Content Security Policy allows iframes from `sim.ai`. + + diff --git a/apps/docs/content/docs/en/execution/costs.mdx b/apps/docs/content/docs/en/execution/costs.mdx index a069c541415..944814817ce 100644 --- a/apps/docs/content/docs/en/execution/costs.mdx +++ b/apps/docs/content/docs/en/execution/costs.mdx @@ -452,6 +452,21 @@ curl -X GET -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" htt - `limit` is derived from individual limits (Free/Pro/Max) or pooled organization limits (Team/Enterprise) - `plan` is the highest-priority active plan associated with your user +## Purchasing Additional Credits + +Pro and Team plan users can buy additional credits at any time in **Settings → Subscription → Credit Balance**: + +- **Range**: $10 to $1,000 per purchase +- **Conversion**: 1 credit = $0.005 (a $10 purchase adds 2,000 credits) +- **Availability**: Credits are added immediately after payment +- **Expiration**: Purchased credits do not expire +- **Refunds**: Purchases are non-refundable +- **Team plans**: Only organization owners and admins can purchase credits. Purchased credits are added to the team's shared pool. + + + Enterprise users should contact support for credit adjustments. + + ## Cost Optimization Strategies - **Model Selection**: Choose models based on task complexity. Simple tasks can use GPT-4.1-nano while complex reasoning might need o1 or Claude Opus. diff --git a/apps/docs/content/docs/en/execution/index.mdx b/apps/docs/content/docs/en/execution/index.mdx index cc80425ecfb..9e37105fb19 100644 --- a/apps/docs/content/docs/en/execution/index.mdx +++ b/apps/docs/content/docs/en/execution/index.mdx @@ -32,6 +32,15 @@ Sim's execution engine brings your workflows to life by processing blocks in the Access execution logs and set up webhooks programmatically via REST API + + + Deploy your workflow as a REST API endpoint with sync, streaming, and async modes + + + + Deploy your workflow as a conversational chat interface with streaming, file uploads, and voice + + ## Key Concepts @@ -58,17 +67,35 @@ Each workflow maintains a rich context during execution containing: API, Chat, Schedule, and Webhook executions run against the workflow’s active deployment snapshot. Manual runs from the editor execute the current draft canvas state, letting you test changes before deploying. Publish a new deployment whenever you change the canvas so every trigger uses the updated version. -
+
Deployment versions table
-The Deploy modal keeps a full version history—inspect any snapshot, compare it against your draft, and promote or roll back with one click when you need to restore a prior release. +### Version History + +The **General** tab in the Deploy modal shows a version history table for every deployment. Each row shows the version name, who deployed it, and when. + +{/* TODO: Screenshot of the version history table with multiple versions */} + +From the version table you can: + +- **Rename** a version to give it a meaningful label (e.g., "v2 — added error handling") +- **Add a description** with notes about what changed in that deployment +- **Promote to live** to roll back to an older version — this makes the selected version the active deployment without changing your draft canvas +- **Load into editor** to restore a previous version’s workflow into the canvas for editing and redeploying +- **Preview a version** by selecting a row, then toggle between viewing the live deployment and the selected version in the canvas + +{/* TODO: Screenshot of the version preview toggle (live vs selected) */} + + + Promoting an old version takes effect immediately — all API, Chat, Schedule, and Webhook executions will use the promoted version. Your draft canvas is not affected. + ## Programmatic Execution diff --git a/apps/docs/content/docs/en/execution/meta.json b/apps/docs/content/docs/en/execution/meta.json index fd2124b9dd4..9092f40f161 100644 --- a/apps/docs/content/docs/en/execution/meta.json +++ b/apps/docs/content/docs/en/execution/meta.json @@ -1,3 +1,3 @@ { - "pages": ["index", "basics", "files", "api", "logging", "costs"] + "pages": ["index", "basics", "files", "api", "api-deployment", "chat", "logging", "costs"] } diff --git a/apps/docs/content/docs/en/knowledgebase/connectors.mdx b/apps/docs/content/docs/en/knowledgebase/connectors.mdx index c6573ed5505..b4f0953338d 100644 --- a/apps/docs/content/docs/en/knowledgebase/connectors.mdx +++ b/apps/docs/content/docs/en/knowledgebase/connectors.mdx @@ -43,7 +43,13 @@ Open a knowledge base and click **Add Connector**. You'll see the full list of a Most connectors use **OAuth** — select an existing credential from the dropdown, or click **Connect new account** to authorize through the service's login flow. Tokens are refreshed automatically, so you won't need to re-authenticate unless you revoke access. -A few connectors (Evernote, Obsidian, Fireflies) use **API keys** instead. Paste your key or developer token directly, and it will be stored securely. +A few connectors use **API keys** instead of OAuth. Paste your key or developer token directly, and it will be stored securely. + +| Connector | Credential | Where to find it | +|-----------|-----------|-----------------| +| **Evernote** | Developer Token (starts with `S=`) | [Evernote Developer Tokens](https://dev.evernote.com/doc/articles/dev_tokens.php) — request a developer token from your account settings | +| **Obsidian** | API Key | Install the [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) community plugin in Obsidian, then copy the API key from the plugin settings | +| **Fireflies** | API Key | Generate an API key from the Integrations page in your Fireflies account settings | If you rotate an API key in the external service, you'll need to update it in Sim as well. OAuth tokens are refreshed automatically, but API keys are not. @@ -59,7 +65,8 @@ Each connector has its own configuration fields that control what gets synced. S - **Notion**: Choose between syncing an entire workspace, a specific database, or a single page tree - **GitHub**: Specify a repository, branch, and optional file extension filter - **Confluence**: Enter your Atlassian domain and optionally filter by space key or content type -- **Obsidian**: Provide your vault URL and optionally restrict to a folder path +- **Obsidian**: Provide your vault URL (default: `https://127.0.0.1:27124`) and optionally restrict to a folder path +- **Fireflies**: Optionally filter by host email or limit the number of transcripts synced All configuration is validated when you save — if a repository doesn't exist or a domain is unreachable, you'll get an immediate error. @@ -137,6 +144,37 @@ You can add multiple connectors to a single knowledge base. For example, you mig Each connector manages its own documents independently. Metadata tag slots are shared across the knowledge base, so keep an eye on slot usage if you're combining several connectors that each populate tags. +## PDF Processing and OCR + +When connectors sync PDF files, Sim can use OCR (Optical Character Recognition) to extract text from scanned documents, images within PDFs, and complex layouts that standard text extraction would miss. + +### OCR Providers + +Sim supports two OCR providers. If neither is configured, PDFs fall back to a basic text parser. + +| Provider | Setup | Notes | +|----------|-------|-------| +| **Mistral OCR** | Set `MISTRAL_API_KEY` environment variable, or add a Mistral key via workspace BYOK settings | Splits large PDFs (1,000+ pages) into chunks and processes them concurrently | +| **Azure Mistral OCR** | Set `OCR_AZURE_ENDPOINT`, `OCR_AZURE_API_KEY`, and `OCR_AZURE_MODEL_NAME` environment variables | Same 1,000-page chunking behavior as Mistral OCR | + + + OCR is automatic — if the environment variables are configured, PDF processing uses OCR. No per-connector toggle is needed. + + +### Self-Hosted OCR Setup + +If you're self-hosting Sim, add the relevant environment variables to your `.env` file: + +```bash +# Option 1: Mistral OCR +MISTRAL_API_KEY=your-mistral-api-key + +# Option 2: Azure Mistral OCR +OCR_AZURE_ENDPOINT=https://your-azure-endpoint.openai.azure.com +OCR_AZURE_API_KEY=your-azure-api-key +OCR_AZURE_MODEL_NAME=your-model-name +``` + ## Common Use Cases - **Internal knowledge base**: Sync your team's Notion workspace and Confluence spaces so AI agents can answer questions about internal processes, policies, and documentation diff --git a/apps/docs/content/docs/en/knowledgebase/tags.mdx b/apps/docs/content/docs/en/knowledgebase/tags.mdx index 47b64b58b19..cd4ecfad1fe 100644 --- a/apps/docs/content/docs/en/knowledgebase/tags.mdx +++ b/apps/docs/content/docs/en/knowledgebase/tags.mdx @@ -2,6 +2,7 @@ title: Tags and Filtering --- +import { Callout } from 'fumadocs-ui/components/callout' import { Video } from '@/components/ui/video' import { FAQ } from '@/components/ui/faq' @@ -15,15 +16,37 @@ You can add custom tags to any document in your knowledgebase to organize and ca
-### Tag Management -- **Custom tags**: Create your own tag system that fits your workflow -- **Multiple tags per document**: Apply as many tags as needed to each document. Each knowledgebase has 17 tag slots total: 7 text, 5 number, 2 date, and 3 boolean slots, shared by all documents in the knowledgebase -- **Tag organization**: Group related documents with consistent tagging +### Tag Slots and Field Types + +Each knowledge base has **17 tag slots** shared across all documents. Slots are organized by field type: + +| Field Type | Slots | Accepted Values | Example | +|-----------|-------|----------------|---------| +| **Text** | 7 slots | Any string (case-insensitive matching) | `category: "engineering"` | +| **Number** | 5 slots | Any valid number | `priority: 3` | +| **Date** | 2 slots | `YYYY-MM-DD` format | `published: 2025-06-15` | +| **Boolean** | 3 slots | `true` or `false` | `reviewed: true` | + + + Tag slots are shared across all documents and connectors in a knowledge base. If a connector auto-populates 3 text tags, you have 4 text slots remaining for manual tags or other connectors. + + +### Creating Tags + +Tags are defined at the knowledge base level — you create a tag definition (e.g., "Department" of type text), and then set values on individual documents. To create a tag: + +1. Open a knowledge base and select a document +2. Click **Add Tag** in the document detail panel +3. Choose a field type and enter a display name +4. Set the tag value for that document + +Once a tag definition exists, you can set its value on any document in the knowledge base. Connectors can also auto-populate tags with metadata from the source (see [Connectors](/knowledgebase/connectors)). ### Tag Best Practices - **Consistent naming**: Use standardized tag names across your documents - **Descriptive tags**: Use clear, meaningful tag names -- **Regular cleanup**: Remove unused or outdated tags periodically +- **Plan for connectors**: If you use connectors that auto-populate tags, leave enough slots for manual tags +- **Regular cleanup**: Remove unused or outdated tags periodically — unused tag definitions can be cleaned up to free slots ## Using Tags in Knowledge Blocks @@ -66,10 +89,17 @@ When you **provide both tags and a search query**: ### Search Configuration #### Tag Filtering -- **Multiple tags**: Use multiple tags with AND or OR logic to control whether documents must match all or any of the specified tags -- **Tag combinations**: Mix different tag types for precise filtering -- **Case sensitivity**: Tag matching is case-insensitive -- **Partial matching**: Text fields support partial matching operators such as contains, starts_with, and ends_with in addition to exact matching + +Configure tag filters in the Knowledge block to narrow results before vector search runs: + +- **AND / OR logic**: Control whether documents must match all tags (AND) or any tag (OR) +- **Case-insensitive**: Tag matching ignores capitalization +- **Text operators**: `equals`, `not equals`, `contains`, `does not contain`, `starts with`, `ends with` +- **Number operators**: `equals`, `not equals`, `greater than`, `greater than or equal`, `less than`, `less than or equal`, `between` +- **Date operators**: `equals`, `after`, `on or after`, `before`, `on or before`, `between` +- **Boolean operators**: `is` / `is not` + +Mix different field types freely — for example, filter by `department = "engineering"` AND `priority >= 3` AND `reviewed = true`. #### Vector Search Parameters - **Query complexity**: Natural language questions work best diff --git a/apps/docs/content/docs/en/mcp/deploy-workflows.mdx b/apps/docs/content/docs/en/mcp/deploy-workflows.mdx index 1c031197ebb..5c5c91cfd47 100644 --- a/apps/docs/content/docs/en/mcp/deploy-workflows.mdx +++ b/apps/docs/content/docs/en/mcp/deploy-workflows.mdx @@ -17,11 +17,14 @@ MCP servers group your workflow tools together. Create and manage them in worksp
-1. Navigate to **Settings → MCP Servers** +1. Navigate to **Settings → Workflow MCP Servers** 2. Click **Create Server** 3. Enter a name and optional description -4. Copy the server URL for use in your MCP clients -5. View and manage all tools added to the server +4. Choose access: **API Key** (private, requires `X-API-Key` header) or **Public** (no authentication) +5. Optionally select deployed workflows to add as tools immediately +6. Copy the server URL for use in your MCP clients + +{/* TODO: Screenshot of the Workflow MCP Servers settings page */} ## Adding a Workflow as a Tool @@ -54,9 +57,35 @@ Your workflow's input format fields become tool parameters. Add descriptions to ## Connecting MCP Clients -Use the server URL from settings to connect external applications: +The server detail page generates ready-to-use configuration snippets for each supported client. Select your client to see the exact config. + +### Cursor + +Cursor supports direct URL configuration. Add to your Cursor MCP settings (`.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "my-sim-workflows": { + "url": "YOUR_SERVER_URL", + "headers": { "X-API-Key": "$SIM_API_KEY" } + } + } +} +``` + +Cursor also provides a one-click install button in the server detail view. + +### Claude Code + +Run this command in your terminal: + +```bash +claude mcp add "my-sim-workflows" --url "YOUR_SERVER_URL" --header "X-API-Key:$SIM_API_KEY" +``` ### Claude Desktop + Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json @@ -64,22 +93,34 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_ "mcpServers": { "my-sim-workflows": { "command": "npx", - "args": ["-y", "mcp-remote", "YOUR_SERVER_URL"] + "args": ["-y", "mcp-remote", "YOUR_SERVER_URL", "--header", "X-API-Key:$SIM_API_KEY"] } } } ``` -### Cursor -Add the server URL in Cursor's MCP settings using the same mcp-remote pattern. +### VS Code + +Add to your VS Code MCP settings (`.vscode/mcp.json`): + +```json +{ + "mcpServers": { + "my-sim-workflows": { + "command": "npx", + "args": ["-y", "mcp-remote", "YOUR_SERVER_URL", "--header", "X-API-Key:$SIM_API_KEY"] + } + } +} +``` - -Include your API key header (`X-API-Key`) for authenticated access when using mcp-remote or other HTTP-based MCP transports. + + For public servers, omit the `X-API-Key` header and `--header` arguments. Public servers don't require authentication. ## Server Management -From the server detail view in **Settings → MCP Servers**, you can: +From the server detail view in **Settings → Workflow MCP Servers**, you can: - **View tools**: See all workflows added to a server - **Copy URL**: Get the server URL for MCP clients diff --git a/apps/docs/content/docs/en/mcp/index.mdx b/apps/docs/content/docs/en/mcp/index.mdx index 4e966165dc5..15a37887c0b 100644 --- a/apps/docs/content/docs/en/mcp/index.mdx +++ b/apps/docs/content/docs/en/mcp/index.mdx @@ -26,19 +26,49 @@ MCP servers provide collections of tools that your agents can use. Configure the + + `$SIM_API_KEY` is a placeholder. For Claude Desktop and VS Code configs, replace it with your actual API key since these clients don't expand environment variables in JSON config files. Claude Code and Cursor handle variable expansion natively. + + ## Server Management From the server detail view in **Settings → Workflow MCP Servers**, you can: From 6f3d1ad9cdd24695c7002ffa5905968b72a180d4 Mon Sep 17 00:00:00 2001 From: Waleed Latif Date: Sat, 11 Apr 2026 11:44:55 -0700 Subject: [PATCH 3/3] fix(docs): replace smart quotes with straight quotes in JSX attributes --- apps/docs/content/docs/en/execution/index.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/docs/content/docs/en/execution/index.mdx b/apps/docs/content/docs/en/execution/index.mdx index 9e37105fb19..c6f07931afa 100644 --- a/apps/docs/content/docs/en/execution/index.mdx +++ b/apps/docs/content/docs/en/execution/index.mdx @@ -65,15 +65,15 @@ Each workflow maintains a rich context during execution containing: ## Deployment Snapshots -API, Chat, Schedule, and Webhook executions run against the workflow’s active deployment snapshot. Manual runs from the editor execute the current draft canvas state, letting you test changes before deploying. Publish a new deployment whenever you change the canvas so every trigger uses the updated version. +API, Chat, Schedule, and Webhook executions run against the workflow's active deployment snapshot. Manual runs from the editor execute the current draft canvas state, letting you test changes before deploying. Publish a new deployment whenever you change the canvas so every trigger uses the updated version. -
+
’Deployment
@@ -88,7 +88,7 @@ From the version table you can: - **Rename** a version to give it a meaningful label (e.g., "v2 — added error handling") - **Add a description** with notes about what changed in that deployment - **Promote to live** to roll back to an older version — this makes the selected version the active deployment without changing your draft canvas -- **Load into editor** to restore a previous version’s workflow into the canvas for editing and redeploying +- **Load into editor** to restore a previous version's workflow into the canvas for editing and redeploying - **Preview a version** by selecting a row, then toggle between viewing the live deployment and the selected version in the canvas {/* TODO: Screenshot of the version preview toggle (live vs selected) */}