Use with AI

**Invoke and execute** workflows and services.

* Execute external services via chat * Call Jinba Flow workflows easily * Auto-generate input forms from data * AI-powered via MCP integration

Hello World

This is a sample post.

: }`. Multiple keys are AND-combined | | `sortColumn` | string | No | Column display name to sort by (defaults to `__updated_at`) | | `sortDirection` | string | No | `asc` or `desc` (default: `desc`) | | `limit` | number | No | Number of records to return (1-500, default: 100) | | `offset` | number | No | Number of records to skip (default: 0) | **Output**: `result` with `items` (records as `{ __id, __created_at, __updated_at, __version, : , ... }`), `total`, `limit`, and `offset`. NUMBER columns are serialized as strings to preserve precision — coerce with `Number(value)` downstream if you need numeric arithmetic. ### JINBA\_TABLE\_UPDATE\_RECORD Update a record in a Jinba table. **Input**: | Parameter | Type | Required | Description | | - | - | - | - | | `tableId` | string | Yes | The table containing the record | | `recordId` | string | Yes | The ID of the record to update | | `fields` | object | Yes | Map of column name → new value (e.g. `{ "Status": "done" }`). Omitted columns are left unchanged; pass null to clear a column | **Output**: `result.recordId`. ### Example: Add and Update Table Records ```yaml theme={null} - id: add_record tool: JINBA_TABLE_ADD_RECORD input: - name: tableId value: "{{secrets.TABLE_ID}}" - name: fields value: '{ "Status": "pending", "Title": "New task" }' - id: get_records tool: JINBA_TABLE_GET_RECORDS input: - name: tableId value: "{{secrets.TABLE_ID}}" - name: filter value: '{ "Status": "pending" }' - name: limit value: 100 - id: update_record tool: JINBA_TABLE_UPDATE_RECORD input: - name: tableId value: "{{secrets.TABLE_ID}}" - name: recordId value: "{{steps.add_record.result.recordId}}" - name: fields value: '{ "Status": "done" }' ``` # Jinba Modules Source: https://carnot.mintlify.app/en/pages/tools/jinba/jinba_modules Advanced data extraction, parsing, and validation using Jinba Modules ## Overview Jinba Modules provide LLM-powered data processing capabilities including extraction, parsing, and rule-based checking. These tools analyze files with large language models to handle complex data transformation and validation tasks with high accuracy and flexibility. ## Key Features ### JINBA\_MODULES\_EXTRACT Uses an LLM to analyze a file and extract structured data according to a JSON Schema you define. | Parameter | Type | Required | Description | | - | - | - | - | | `name` | string | Yes | Task name | | `fileUrl` | string | Yes | The URL of the file to extract data from | | `dataSchema` | object | No | The schema of the data to extract. Must be a valid [JSON Schema](https://json-schema.org/understanding-json-schema/reference) | | `extractionMode` | string | No | `FAST`, `BALANCED` (default), or `QUALITY` | Output: `result` — the extracted data, shaped by your `dataSchema`. ### JINBA\_MODULES\_PARSE A dynamic parser in which the LLM automatically adjusts the parsing approach based on the file type and outputs the extracted content. | Parameter | Type | Required | Description | | - | - | - | - | | `fileUrl` | string | Yes | The URL of the file to parse | | `outputFormat` | string | No | `MARKDOWN` (default), `TEXT`, or `STRUCTURED` | | `extractionMode` | string | No | `FAST`, `BALANCED` (default), or `QUALITY` | Output: `result` — the parsed content as a string. ### JINBA\_MODULES\_CHECKER\_V2 An enhanced LLM-based checker that validates a target file against JSON-defined rules. v2 supports flexible rule structures, higher-precision evaluation, and detailed reasoning for each judgment. | Parameter | Type | Required | Description | | - | - | - | - | | `target_file` | string | Yes | The file to check (PDF, text, JSON, XML, CSV, or DOCX) | | `task` | string | Yes | The task name | | `description` | string | No | Task description. Use when you want to add instructions specialized for a specific task | | `rules` | array | No | JSON array of rule objects (see [Rule Format](#rule-format)) | | `references` | array | No | Up to 10 reference file URLs. To suppress hallucinations, you can embed company regulations, legal documents, RAG search results, etc. | | `additionalDataSchema` | object | No | JSON Schema describing additional data to return with each check result | Output: `result` — an array of check results, one per rule, each with `uniqueId`, `rule`, `status` (`accepted` / `rejected` / `pending`), `range`, `reason`, and optional `additionalData`. ## Authentication No authentication or tool configuration is required. The Jinba Modules API credentials are managed server-side. ## Example: Intelligent Document Extraction ```yaml theme={null} - id: upload_document name: upload_document tool: INPUT_FILE input: - name: description value: "Upload document for intelligent extraction" - id: extract_structured_data name: extract_structured_data tool: JINBA_MODULES_EXTRACT input: - name: name value: "Invoice Data Extraction" - name: fileUrl value: "{{steps.upload_document.result}}" - name: dataSchema value: | { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "invoice_number": { "type": "string", "description": "Invoice number or ID" }, "date": { "type": "string", "format": "date", "description": "Invoice date" }, "vendor": { "type": "object", "properties": { "name": {"type": "string"}, "address": {"type": "string"}, "phone": {"type": "string"}, "email": {"type": "string"} } }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": {"type": "string"}, "quantity": {"type": "number"}, "unit_price": {"type": "number"}, "total": {"type": "number"} } } }, "total_amount": { "type": "number", "description": "Total invoice amount" }, "tax_amount": { "type": "number", "description": "Tax amount if present" } }, "required": ["invoice_number", "date", "total_amount"] } - name: extractionMode value: "QUALITY" # Options: FAST, BALANCED, QUALITY - id: validate_document name: validate_document tool: JINBA_MODULES_CHECKER_V2 input: - name: target_file value: "{{steps.upload_document.result}}" - name: task value: "Invoice Validation" - name: description value: "Check that the uploaded invoice satisfies the rules below." - name: rules value: | [ { "uniqueId": "invoice-001", "name": "Invoice number present", "description": "The document must contain an invoice number or ID." }, { "uniqueId": "invoice-002", "name": "Positive total amount", "description": "The total amount must be a positive number." }, { "uniqueId": "invoice-003", "name": "Valid invoice date", "description": "The invoice date must be present and in a valid date format." }, { "uniqueId": "invoice-004", "name": "Valid vendor email", "description": "If a vendor email address is present, it must be in a valid email format." } ] - id: process_extraction_results name: process_extraction_results tool: PYTHON_SANDBOX_RUN input: - name: code value: | import json # Process extraction and check results extracted_data = json.loads('''{{steps.extract_structured_data.result}}''') check_results = json.loads('''{{steps.validate_document.result}}''') print("Document Extraction Results") print("=" * 35) # Display extracted data print("Extracted Information:") print(f"Invoice Number: {extracted_data.get('invoice_number', 'N/A')}") print(f"Date: {extracted_data.get('date', 'N/A')}") print(f"Vendor: {extracted_data.get('vendor', {}).get('name', 'N/A')}") print(f"Total Amount: ${extracted_data.get('total_amount', 0):,.2f}") if 'items' in extracted_data: print(f"Items Count: {len(extracted_data['items'])}") print("\nCheck Results:") accepted_count = sum(1 for r in check_results if r.get('status') == 'accepted') total_rules = len(check_results) print(f"Accepted: {accepted_count}/{total_rules}") # Show any rejected rules rejected = [r for r in check_results if r.get('status') == 'rejected'] if rejected: print("\nRejected Rules:") for r in rejected: print(f" - {r.get('rule', 'Unknown')}: {r.get('reason', 'No reason provided')}") else: print("All rules accepted") - id: export_processed_data name: export_processed_data tool: OUTPUT_FILE input: - name: content value: "{{steps.extract_structured_data.result}}" - name: filename value: "extracted_invoice_data_{{date | format('YYYY-MM-DD')}}.json" - name: fileType value: "json" ``` ## Example: Batch Document Processing ```yaml theme={null} - id: process_document_batch name: process_document_batch tool: JINBA_MODULES_EXTRACT input: - name: name value: "Batch Document Processing" - name: fileUrl value: "{{input.batch_file_url}}" - name: dataSchema value: | { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "document_type": {"type": "string"}, "date": {"type": "string"}, "amount": {"type": "number"}, "vendor": {"type": "string"}, "metadata": { "type": "object", "additionalProperties": true } }, "required": ["document_type", "date", "amount"] } } } } - name: extractionMode value: "BALANCED" - id: parse_document_content name: parse_document_content tool: JINBA_MODULES_PARSE input: - name: fileUrl value: "{{input.batch_file_url}}" - name: outputFormat value: "MARKDOWN" # Options: MARKDOWN, TEXT, STRUCTURED - name: extractionMode value: "BALANCED" - id: comprehensive_validation name: comprehensive_validation tool: JINBA_MODULES_CHECKER_V2 input: - name: target_file value: "{{input.batch_file_url}}" - name: task value: "Batch Document Check" - name: rules value: | [ { "uniqueId": "doc-001", "name": "Known document types only", "description": "Every document must be an invoice, a receipt, or a contract." }, { "uniqueId": "doc-002", "name": "Amount within range", "description": "Every document amount must be between 0 and 1,000,000." }, { "uniqueId": "doc-003", "name": "Date within range", "description": "Every document date must be between 2020-01-01 and 2025-12-31." }, { "uniqueId": "doc-004", "name": "Vendor name length", "description": "Every vendor name must be between 2 and 200 characters." } ] - name: additionalDataSchema value: | { "type": "object", "properties": { "documentType": { "type": "string", "description": "The type of the document the rule was evaluated against" } } } - id: generate_processing_report name: generate_processing_report tool: PYTHON_SANDBOX_RUN input: - name: code value: | import json from datetime import datetime # Compile processing report extracted = json.loads('''{{steps.process_document_batch.result}}''') parsed = '''{{steps.parse_document_content.result}}''' check_results = json.loads('''{{steps.comprehensive_validation.result}}''') report = { "processing_summary": { "timestamp": datetime.now().isoformat(), "total_documents": len(extracted.get('documents', [])), "extraction_mode": "BALANCED", "parsed_characters": len(parsed), "all_rules_accepted": all(r.get('status') == 'accepted' for r in check_results) }, "document_breakdown": {}, "check_summary": { "total_rules": len(check_results), "accepted": sum(1 for r in check_results if r.get('status') == 'accepted'), "rejected": sum(1 for r in check_results if r.get('status') == 'rejected'), "pending": sum(1 for r in check_results if r.get('status') == 'pending') }, "recommendations": [] } # Document type breakdown if 'documents' in extracted: doc_types = {} total_amount = 0 for doc in extracted['documents']: doc_type = doc.get('document_type', 'unknown') doc_types[doc_type] = doc_types.get(doc_type, 0) + 1 total_amount += doc.get('amount', 0) report['document_breakdown'] = doc_types report['processing_summary']['total_amount'] = total_amount # Add recommendations if report['check_summary']['rejected'] > 0: report['recommendations'].append("Review rejected rules and correct data issues") if report['check_summary']['pending'] > 0: report['recommendations'].append("Review pending rules manually") print(json.dumps(report, indent=2)) - id: save_processing_report name: save_processing_report tool: OUTPUT_FILE input: - name: content value: "{{steps.generate_processing_report.result.stdout}}" - name: filename value: "batch_processing_report_{{date | format('YYYY-MM-DD-HHmm')}}.json" - name: fileType value: "json" ``` ## Extraction Modes The `extractionMode` parameter is shared by `JINBA_MODULES_EXTRACT` and `JINBA_MODULES_PARSE`: * **FAST**: Extracts data quickly. Best for high-volume processing of simple documents * **BALANCED** (default): Extracts data with a balance of speed and accuracy. A good general-purpose choice * **QUALITY**: Extracts data with the highest accuracy. Best for critical documents and complex layouts ## Output Formats The `outputFormat` parameter of `JINBA_MODULES_PARSE` controls the shape of the parsed result: * **MARKDOWN** (default): Output in Markdown format, preserving headings, tables, and lists * **TEXT**: Output as plain text * **STRUCTURED**: Output in a structured format ## Data Schema Design The `dataSchema` parameter of `JINBA_MODULES_EXTRACT` accepts any valid JSON Schema. ### Basic Schema Structure ```json theme={null} { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "field_name": { "type": "string|number|object|array", "description": "Clear description of the field", "format": "date|email|uri|etc", "pattern": "regex_pattern_if_needed" } }, "required": ["list_of_required_fields"] } ``` ### Advanced Schema Features * **Nested objects**: Complex data structures * **Arrays**: Multiple items of the same type * **Conditional fields**: Fields dependent on other values * **Pattern matching**: Regex validation * **Format validation**: Date, email, URL formats ## Rule Format The `rules` parameter of `JINBA_MODULES_CHECKER_V2` is a JSON array of rule objects. Each rule is evaluated against the target file by the LLM. | Field | Type | Required | Description | | - | - | - | - | | `uniqueId` | string | Yes | Identifier echoed back in the corresponding check result | | `name` | string | Yes | Short rule name | | `description` | string | Yes | What the rule checks, written in natural language | | `references` | array | No | Rule-specific references: objects with `type` (`text` or `url`) and a matching `text` or `url` field | | `examples` | array | No | Example judgments to guide the evaluation | ### Check Results Each entry in the `result` output corresponds to one rule: * **`uniqueId`**: The rule's identifier * **`rule`**: The rule that was evaluated * **`status`**: `accepted`, `rejected`, or `pending` * **`range`**: The location in the target the judgment refers to * **`reason`**: Detailed reasoning behind the judgment * **`additionalData`**: Extra fields matching `additionalDataSchema`, when provided ## Use Cases * **Invoice Processing**: Automated invoice data extraction and validation * **Document Digitization**: Convert paper documents to structured data * **Data Migration**: Extract data from legacy systems * **Compliance Checking**: Validate documents against regulations * **Research Data**: Extract structured data from research documents * **Form Processing**: Automate form data extraction * **Contract Analysis**: Extract key terms from contracts * **Financial Processing**: Process financial statements and reports ## Best Practices ### Schema Design * Keep schemas simple and focused * Use clear, descriptive field names * Include comprehensive descriptions * Test schemas with sample data * Version your schemas for consistency ### Extraction Optimization * Choose the appropriate extraction mode for your use case * Provide high-quality input documents * Use consistent document formats when possible * Monitor extraction accuracy and adjust as needed ### Checking Strategy * Write rule descriptions in clear, unambiguous natural language * Give each rule a stable `uniqueId` so results can be traced over time * Attach `references` (regulations, legal documents, RAG search results) to suppress hallucinations * Review `pending` results manually and refine rules based on the `reason` output ### Performance Considerations * Batch similar documents together * Use FAST mode for simple, high-volume processing * Use QUALITY mode only where accuracy is critical * Implement error handling for failed extractions # Jinba Knowledge Base Source: https://carnot.mintlify.app/en/pages/tools/jinba/knowledge_base Update and manage Jinba knowledge bases for enhanced AI workflows ## Overview The Jinba Knowledge Base tools allow you to add files to and update files in knowledge bases within the Jinba ecosystem. These tools enable you to maintain up-to-date information repositories that can be accessed by other tools and workflows (such as vector search) for enhanced AI-powered operations. ## Key Features * `JINBA_KNOWLEDGE_BASE_FILE_ADD`: Add a file to a knowledge base, with configurable chunking * `JINBA_KNOWLEDGE_BASE_UPDATE`: Update an existing file in a knowledge base with new content * Integration with vector search capabilities * Synchronous or asynchronous execution (wait for chunking or return immediately) ## Authentication These tools authenticate with a workspace secret key via the `token` config, which defaults to `{{ secrets.JINBAFLOW_WS_API_KEY }}` — you usually do not need to set it explicitly. ## Tools ### JINBA\_KNOWLEDGE\_BASE\_FILE\_ADD Add a file to a knowledge base. **Input**: | Parameter | Type | Required | Description | | - | - | - | - | | `knowledgeBaseId` | string | Yes | Target knowledge base | | `file` | string | Yes | Base64 encoded file content or file URL starting with `https://` or `data:` | | `filename` | string | Yes | Name of the file (extension will be auto-detected from the file) | | `metadata` | string (JSON) | No | Optional metadata to attach to the file | | `chunkerSettings` | object | No | Chunking settings: `chunkSize` (1-8192, default: 512), `chunkOverlap` (0-2048, default: 128), `chunkingIdentifier` (default: `"\\n\\n"`) | | `executionMode` | string | No | `SYNCHRONOUS` to wait for chunking or `ASYNCHRONOUS` to return immediately (default: `ASYNCHRONOUS`) | **Output**: | Field | Type | Description | | - | - | - | | `knowledgeBaseId` | string | ID of the knowledge base | | `fileId` | string | ID of the added file | | `filename` | string | Name of the added file | | `status` | string | Processing status: `pending`, `processing`, `completed`, or `failed` | | `contentType` | string | Content type of the file | | `size` | string | File size | | `chunkCount` | number | Number of chunks created | | `createdAt` | string | Creation timestamp | ### JINBA\_KNOWLEDGE\_BASE\_UPDATE Update an existing file in a knowledge base with new content. **Input**: | Parameter | Type | Required | Description | | - | - | - | - | | `knowledgeBaseId` | string | Yes | Target knowledge base | | `knowledgeBaseFileId` | string | Yes | Existing knowledge base file ID to update | | `fileUrl` | string | Yes | URL of the file content to update with | | `updateType` | string | No | Update strategy; `FULL_REFRESH` replaces the file in the knowledge base (default: `FULL_REFRESH`) | | `executionMode` | string | No | `SYNCHRONOUS` to wait for chunking or `ASYNCHRONOUS` to return immediately (default: `SYNCHRONOUS`) | **Output**: | Field | Type | Description | | - | - | - | | `knowledgeBaseId` | string | ID of the knowledge base | | `fileId` | string | ID of the updated file | | `filename` | string | Name of the updated file | | `status` | string | Processing status: `pending`, `processing`, `completed`, or `failed` | | `chunkCount` | number | Number of chunks created | ## Examples ### Example: Add a File to a Knowledge Base ```yaml theme={null} - id: add_file_to_kb tool: JINBA_KNOWLEDGE_BASE_FILE_ADD input: - name: knowledgeBaseId value: "{{secrets.KNOWLEDGE_BASE_ID}}" - name: file value: "https://example.com/product-manual.pdf" - name: filename value: "product-manual.pdf" - name: executionMode value: "SYNCHRONOUS" - name: chunkerSettings value: chunkSize: 512 chunkOverlap: 128 chunkingIdentifier: "\\n\\n" ``` ### Example: Update an Existing Knowledge Base File ```yaml theme={null} - id: update_kb_file tool: JINBA_KNOWLEDGE_BASE_UPDATE input: - name: knowledgeBaseId value: "{{secrets.KNOWLEDGE_BASE_ID}}" - name: knowledgeBaseFileId value: "{{secrets.FILE_ID}}" - name: fileUrl value: "https://example.com/updated-product-manual.pdf" - name: updateType value: "FULL_REFRESH" - name: executionMode value: "SYNCHRONOUS" ``` ### Example: Generate a Report and Store It in a Knowledge Base ```yaml theme={null} - id: create_report tool: OUTPUT_FILE input: - name: content value: | # Weekly Support Summary {{steps.summarize_tickets.result.content}} - name: filename value: "support_summary_{{date | format('YYYY-MM-DD')}}.md" - name: fileType value: "md" - id: add_report_to_kb tool: JINBA_KNOWLEDGE_BASE_FILE_ADD input: - name: knowledgeBaseId value: "{{secrets.KNOWLEDGE_BASE_ID}}" - name: file value: "{{steps.create_report.result.url}}" - name: filename value: "support_summary_{{date | format('YYYY-MM-DD')}}.md" - name: executionMode value: "ASYNCHRONOUS" ``` ## Use Cases * Maintaining product documentation and changelogs * Building comprehensive troubleshooting guides * Creating workflow documentation repositories * Storing best practices and guidelines * Building FAQ and support knowledge bases * Keeping RAG search sources up to date automatically ## Best Practices * Use descriptive filenames so files are easy to identify later * Tune `chunkerSettings` for your content: smaller chunks (256-512) for precise retrieval, larger chunks (1024-2048) for maintaining context * Use `SYNCHRONOUS` execution when downstream steps depend on the file being searchable * Use `ASYNCHRONOUS` execution for large files to avoid blocking the flow * Check the `status` output (`pending` / `processing` / `completed` / `failed`) before relying on the file in searches * Update existing files with `JINBA_KNOWLEDGE_BASE_UPDATE` instead of adding duplicates # Vector Search Source: https://carnot.mintlify.app/en/pages/tools/jinba/vector_search Semantic search for knowledge bases using vector embeddings ## Overview Jinba Vector Search enables semantic search capabilities for knowledge bases using vector embeddings. This tool uses OpenAI's text-embedding-3-large to vectorize queries and retrieve relevant data from your knowledge base based on similarity scores, providing powerful RAG (Retrieval-Augmented Generation) functionality. ## Key Features * **Semantic Search**: Find conceptually similar content, not just exact matches * **Knowledge Base Integration**: Search across uploaded documents and files * **Similarity Scoring**: Filter results by similarity threshold * **Configurable Results**: Control the number of results returned * **RAG Support**: Perfect for building question-answering and information retrieval workflows ## Authentication This tool requires a Jinba API Token to access knowledge bases. **Required Configuration:** * `token` (string): Your Jinba API Token (stored as a secret) ## Input Parameters | Parameter | Type | Required | Default | Description | | - | - | - | - | - | | `query` | string | Yes | - | Search query for semantic search | | `knowledgeBaseId` | string | Yes | - | ID of the knowledge base to search | | `topK` | number | No | 3 | Number of top results to return (1-50) | | `threshold` | number | No | 0.3 | Similarity threshold for filtering results (0-1) | ## Output Structure Returns an array of search results with: | Field | Type | Description | | - | - | - | | `chunk` | object | Content chunk with ID, file ID, content, and metadata | | `score` | number | Similarity score (0-1, higher is more similar) | | `file` | object | File information including filename and content type | | `query` | string | The original search query | | `totalResults` | number | Total number of results found | ## Example: Document Q\&A System ```yaml theme={null} - id: search_knowledge_base name: search_knowledge_base tool: JINBA_VECTOR_SEARCH config: - name: token value: "{{secrets.JINBA_API_TOKEN}}" input: - name: query value: "What is our company's return policy?" - name: knowledgeBaseId value: "{{secrets.KNOWLEDGE_BASE_ID}}" - name: topK value: 5 - name: threshold value: 0.4 - id: generate_answer name: generate_answer tool: OPENAI_INVOKE config: - name: version value: gpt-4 input: - name: prompt value: | Based on the following search results from our knowledge base, answer the user's question about our return policy. Search Results: {{#each steps.search_knowledge_base.results}} **From: {{file.filename}}** Content: {{chunk.content}} Similarity: {{score}} {{/each}} Question: {{steps.search_knowledge_base.query}} Please provide a comprehensive answer based on the search results above. ``` ## Example: Research Assistant ```yaml theme={null} - id: research_query name: research_query tool: INPUT_TEXT input: - name: description value: "Enter your research question" - id: search_research_base name: search_research_base tool: JINBA_VECTOR_SEARCH config: - name: token value: "{{secrets.JINBA_API_TOKEN}}" input: - name: query value: "{{steps.research_query.result}}" - name: knowledgeBaseId value: "{{secrets.RESEARCH_KB_ID}}" - name: topK value: 10 - name: threshold value: 0.3 - id: analyze_findings name: analyze_findings tool: PYTHON_SANDBOX_RUN input: - name: code value: | import json results = {{steps.search_research_base.results}} print("=== Research Findings ===") print(f"Query: {results['query']}") print(f"Total Results: {results['totalResults']}") print() # Group results by source file sources = {} for result in results['results']: filename = result['file']['filename'] if filename not in sources: sources[filename] = [] sources[filename].append({ 'content': result['chunk']['content'][:200] + "...", 'score': result['score'] }) print("=== Sources Found ===") for filename, chunks in sources.items(): print(f"\n📄 {filename}") for i, chunk in enumerate(chunks[:3]): # Top 3 chunks per file print(f" {i+1}. Score: {chunk['score']:.3f}") print(f" {chunk['content']}") # Calculate average similarity avg_score = sum(r['score'] for r in results['results']) / len(results['results']) print(f"\n📊 Average Similarity: {avg_score:.3f}") - id: synthesize_response name: synthesize_response tool: ANTHROPIC_INVOKE config: - name: token value: "{{secrets.ANTHROPIC_API_KEY}}" input: - name: prompt value: | You are a research assistant. Synthesize the following search results into a comprehensive response. Original Query: {{steps.search_research_base.query}} Search Results: {{#each steps.search_research_base.results}} **Source: {{file.filename}}** (Similarity: {{score}}) {{chunk.content}} --- {{/each}} Please provide: 1. A direct answer to the question 2. Key insights from multiple sources 3. Any conflicting information found 4. Suggestions for further research ``` ## Example: Content Recommendation ```yaml theme={null} - id: get_user_interests name: get_user_interests tool: INPUT_TEXT input: - name: description value: "Describe topics or content you're interested in" - id: find_related_content name: find_related_content tool: JINBA_VECTOR_SEARCH config: - name: token value: "{{secrets.JINBA_API_TOKEN}}" input: - name: query value: "{{steps.get_user_interests.result}}" - name: knowledgeBaseId value: "{{secrets.CONTENT_KB_ID}}" - name: topK value: 8 - name: threshold value: 0.25 - id: format_recommendations name: format_recommendations tool: PYTHON_SANDBOX_RUN input: - name: code value: | results = {{steps.find_related_content.results}} print("🔍 **Content Recommendations**") print(f"Based on: *{results['query']}*\n") recommendations = [] for i, result in enumerate(results['results'][:5], 1): chunk = result['chunk'] file_info = result['file'] score = result['score'] # Extract first sentence or 100 characters content_preview = chunk['content'][:100].split('.')[0] + "..." recommendations.append({ 'rank': i, 'title': file_info['filename'], 'preview': content_preview, 'relevance': f"{score:.1%}", 'content_type': file_info['contentType'] }) for rec in recommendations: print(f"**{rec['rank']}. {rec['title']}**") print(f" 📋 {rec['preview']}") print(f" 🎯 Relevance: {rec['relevance']}") print(f" 📄 Type: {rec['content_type']}") print() if len(results['results']) == 0: print("No relevant content found. Try adjusting your search terms or lowering the threshold.") ``` ## Best Practices ### Query Optimization * **Use natural language**: Write queries as you would ask a human * **Be specific**: More specific queries often yield better results * **Include context**: Add relevant keywords and context terms ### Threshold Selection * **0.7-1.0**: Very high similarity, exact or near-exact matches * **0.4-0.7**: High similarity, closely related content * **0.2-0.4**: Moderate similarity, potentially relevant content * **0.0-0.2**: Low similarity, may include tangentially related content ### Performance Tips * **Limit topK**: Don't retrieve more results than needed * **Adjust threshold**: Higher thresholds = fewer, more relevant results * **Use metadata**: Leverage chunk metadata for additional filtering ## Knowledge Base Setup Before using vector search, ensure your knowledge base contains relevant documents: 1. **Upload Documents**: Add PDFs, text files, or other supported formats 2. **Processing**: Allow time for document chunking and vectorization 3. **Test Queries**: Start with simple queries to understand your data 4. **Iterate**: Refine queries and thresholds based on results ## Use Cases * **Customer Support**: Find relevant documentation for user questions * **Research Assistant**: Discover related research papers and documents * **Content Discovery**: Recommend similar articles or resources * **FAQ Automation**: Automatically answer common questions * **Document Analysis**: Find specific information across large document sets * **Knowledge Management**: Quick access to institutional knowledge * **Legal Research**: Search through contracts and legal documents * **Product Information**: Find technical specifications and manuals # AI Video Generation Source: https://carnot.mintlify.app/en/pages/tools/media/video_generation Create high-quality videos from text descriptions using AI ## Overview AI Video Generation tools allow you to create high-quality videos from simple text descriptions using advanced AI models. These tools support multiple video formats, aspect ratios, and durations for various use cases. ## Key Features * `LUMA_TEXT_TO_VIDEO` * Generate videos using Luma AI's advanced models (ray-2, ray-flash-2, ray-1-6) * Support for 4K resolution and multiple aspect ratios * Customizable duration (5s or 10s) with seamless looping options * `LUMA_TEXT_TO_IMAGE` * Generate high-quality images from text descriptions * `KLING_TEXT_TO_VIDEO` * Generate videos using Kling AI's enhanced models * Improved motion quality and lifelike character generation * Support for multiple aspect ratios and durations ## Authentication For further details, [click here](/en/pages/credentials/luma) and [click here](/en/pages/credentials/kling). To use video generation tools, you need API keys from the respective services: * Luma AI: Obtain from [Luma AI website](https://lumalabs.ai/) * Kling AI: Obtain from [Kling AI website](https://klingai.kuaishou.com/) **Note**: Treat API keys as sensitive information and never commit them to public repositories. ### Example: Basic Video Generation ```yaml theme={null} - id: generate_marketing_video name: generate_marketing_video tool: LUMA_TEXT_TO_VIDEO config: - name: api_key value: "{{secrets.LUMA_API_KEY}}" - name: model value: "ray-2" - name: aspect_ratio value: "16:9" - name: duration value: 10 - name: loop value: false input: - name: prompt value: | A professional product showcase video featuring a sleek smartphone rotating slowly on a white background with soft lighting. The phone displays a modern app interface. Camera slowly zooms in to highlight the premium build quality and design details. - id: generate_social_media_video name: generate_social_media_video tool: KLING_TEXT_TO_VIDEO config: - name: api_key value: "{{secrets.KLING_API_KEY}}" - name: aspect_ratio value: "9:16" - name: duration value: 5 input: - name: prompt value: | A vibrant animated scene of a person working at a coffee shop, typing on a laptop with steam rising from their coffee cup. Warm afternoon sunlight streaming through the window. Perfect for social media content about productivity and lifestyle. ``` ### Example: Video Content Creation Pipeline ```yaml theme={null} - id: get_video_brief name: get_video_brief tool: INPUT_JSON_WITH_VALIDATION input: - name: value value: { "video_type": "product_demo", "product_name": "Smart Watch", "target_audience": "fitness enthusiasts", "duration": 10, "style": "modern_minimal" } - id: generate_video_script name: generate_video_script tool: OPENAI_INVOKE config: - name: version value: gpt-4 input: - name: prompt value: | Create a detailed video description/prompt for AI video generation based on this brief: Product: {{steps.get_video_brief.result.product_name}} Target Audience: {{steps.get_video_brief.result.target_audience}} Duration: {{steps.get_video_brief.result.duration}} seconds Style: {{steps.get_video_brief.result.style}} Type: {{steps.get_video_brief.result.video_type}} Requirements: 1. Write a detailed visual description for AI video generation 2. Include camera movements, lighting, and composition details 3. Specify product positioning and key features to highlight 4. Ensure the description fits the target duration 5. Match the requested visual style Format the output as a single, detailed prompt suitable for AI video generation. - id: create_main_video name: create_main_video tool: LUMA_TEXT_TO_VIDEO config: - name: api_key value: "{{secrets.LUMA_API_KEY}}" - name: model value: "ray-2" - name: aspect_ratio value: "16:9" - name: duration value: "{{steps.get_video_brief.result.duration}}" input: - name: prompt value: "{{steps.generate_video_script.result.content}}" - id: create_social_variant name: create_social_variant tool: KLING_TEXT_TO_VIDEO config: - name: api_key value: "{{secrets.KLING_API_KEY}}" - name: aspect_ratio value: "9:16" - name: duration value: 5 input: - name: prompt value: | Vertical social media version: {{steps.generate_video_script.result.content}} Optimized for mobile viewing with close-up shots and dynamic movement. ``` ### Example: Multi-Format Content Creation ```yaml theme={null} - id: create_hero_image name: create_hero_image tool: LUMA_TEXT_TO_IMAGE config: - name: api_key value: "{{secrets.LUMA_API_KEY}}" input: - name: prompt value: | A stunning hero image for a tech startup website. Modern office space with diverse team members collaborating around a large display showing data visualizations. Professional lighting, clean design, inspiring atmosphere. High-resolution, photorealistic. - id: create_background_video name: create_background_video tool: LUMA_TEXT_TO_VIDEO config: - name: api_key value: "{{secrets.LUMA_API_KEY}}" - name: model value: "ray-flash-2" - name: aspect_ratio value: "16:9" - name: duration value: 10 - name: loop value: true input: - name: prompt value: | Subtle background video for website hero section. Gentle floating abstract particles and soft geometric shapes in corporate blue colors. Minimal motion, professional feel, seamless loop. Perfect for website background without being distracting. - id: create_product_showcase name: create_product_showcase tool: KLING_TEXT_TO_VIDEO config: - name: api_key value: "{{secrets.KLING_API_KEY}}" - name: aspect_ratio value: "1:1" - name: duration value: 5 input: - name: prompt value: | Square format product showcase for Instagram. Modern laptop computer on a clean desk setup with plants and coffee. Smooth 360-degree rotation showing all angles. Premium aesthetic with natural lighting and minimal shadows. ``` ### Example: Video Generation with Quality Control ```yaml theme={null} - id: generate_video_options name: generate_video_options tool: PYTHON_SANDBOX_RUN input: - name: code value: | import json base_prompt = "A professional presentation of a new mobile app interface" # Generate variations for A/B testing variations = [ { "name": "version_a_minimal", "prompt": f"{base_prompt} with minimal design, clean white background, subtle animations", "model": "ray-2", "aspect_ratio": "16:9" }, { "name": "version_b_dynamic", "prompt": f"{base_prompt} with dynamic camera movements, colorful gradient background, energetic transitions", "model": "ray-flash-2", "aspect_ratio": "16:9" }, { "name": "version_c_social", "prompt": f"{base_prompt} optimized for social media, vertical format, engaging visual effects", "model": "ray-2", "aspect_ratio": "9:16" } ] print(json.dumps({"variations": variations})) - id: create_version_a name: create_version_a tool: LUMA_TEXT_TO_VIDEO config: - name: api_key value: "{{secrets.LUMA_API_KEY}}" - name: model value: "{{steps.generate_video_options.result.variations[0].model}}" - name: aspect_ratio value: "{{steps.generate_video_options.result.variations[0].aspect_ratio}}" - name: duration value: 10 input: - name: prompt value: "{{steps.generate_video_options.result.variations[0].prompt}}" - id: create_version_b name: create_version_b tool: LUMA_TEXT_TO_VIDEO config: - name: api_key value: "{{secrets.LUMA_API_KEY}}" - name: model value: "{{steps.generate_video_options.result.variations[1].model}}" - name: aspect_ratio value: "{{steps.generate_video_options.result.variations[1].aspect_ratio}}" - name: duration value: 10 input: - name: prompt value: "{{steps.generate_video_options.result.variations[1].prompt}}" - id: analyze_results name: analyze_results tool: PYTHON_SANDBOX_RUN input: - name: code value: | import json # Compile results results = { "version_a": { "url": "{{steps.create_version_a.result.video_url}}", "status": "{{steps.create_version_a.result.status}}", "style": "minimal" }, "version_b": { "url": "{{steps.create_version_b.result.video_url}}", "status": "{{steps.create_version_b.result.status}}", "style": "dynamic" } } print(json.dumps({"video_results": results})) ``` ## Tips and Best Practices * Use specific, detailed prompts for better video quality * Choose the right model based on your needs (quality vs speed) * Consider aspect ratio based on intended platform (16:9 for web, 9:16 for mobile) * Test different prompt variations to find the best results * Use looping for background videos and website elements * Plan video duration based on platform requirements * Include lighting, camera movement, and composition details in prompts * Consider creating multiple versions for A/B testing * Monitor API usage and costs for high-volume generation # Netsea Source: https://carnot.mintlify.app/en/pages/tools/productivity/netsea Connect to the Netsea API ## Overview Netsea is a platform that provides access to a wide range of products and suppliers. This tool allows you to connect with the Netsea API, enabling you to retrieve product information, supplier details, and manage your inventory programmatically. This integration is useful for automating workflows and enhancing productivity within your e-commerce operations. ## Key Features * `NETSEA_GET_SUPPLIERS` * Retrieve a list of suppliers from the Netsea platform. * `NETSEA_GET_CATEGORIES` * Retrieve a list of product categories from the Netsea platform. ## Authentication For further details, [click here](/en/pages/credentials/netsea). To use the Netsea API, you need to set up an API key for buyers. You can sign up up for an account on the [Netsea website](https://netsea.jp/) and generate your API key. **Note**: Treat API keys as sensitive information and never commit them to public repositories. ### Example: Get Suppliers and Categories ```yaml theme={null} - id: get_suppliers tool: NETSEA_GET_SUPPLIERS config: - name: token value: "{{secrets.NETSEA_API_TOKEN}}" input: [] - id: get_categories tool: NETSEA_GET_CATEGORIES config: - name: token value: "{{secrets.NETSEA_API_TOKEN}}" - name: all_levels value: false input: [] ``` # Shopify Source: https://carnot.mintlify.app/en/pages/tools/productivity/shopify Manage Shopify products and orders ## Overview The Shopify tools allow you to manage products and orders in your Shopify store. You can create, update, and delete products, as well as manage orders and inventory. ## Key Features * `SHOPIFY_LIST_PRODUCTS` * Retrieve a list of products from your Shopify store. * `SHOPIFY_CREATE_PRODUCT` * Create a new product in your Shopify store. ## Authentication For further details, [click here](/en/pages/credentials/shopify). To use the Shopify API, you need to create a private app in your Shopify store. This will provide you with the necessary credentials (API key and password) to authenticate your requests. **Note**: Treat API keys as sensitive information and never commit them to public repositories. ### Example: List Products and Create a Product ```yaml theme={null} - name: Get Product List id: list_products tool: SHOPIFY_LIST_PRODUCTS config: - name: token value: "{{secrets.SHOPIFY_API_TOKEN}}" - name: api_version value: 2025-01 input: - name: shop_domain value: jinbaflow.myshopify.com - name: limit value: 5 - name: Create New Product id: create_product tool: SHOPIFY_CREATE_PRODUCT config: - name: token value: "{{secrets.SHOPIFY_API_TOKEN}}" - name: api_version value: 2025-01 input: - name: shop_domain value: gzb31e-yv.myshopify.com - name: title value: Jinba Flow Test Product - name: description value: This is a test product created from Jinba Flow. - name: vendor value: Jinba Flow - name: product_type value: Test - name: status value: DRAFT ``` # Building a RAG Chat System Source: https://carnot.mintlify.app/en/pages/tutorials/rag-chat-system A step-by-step tutorial to build a Retrieval-Augmented Generation chat system using Jinba Flow — from knowledge base setup to deploying a live chat interface Build a fully functional AI chat system that answers questions using your own documents. This tutorial walks you through every step: creating a knowledge base, building a RAG workflow, and deploying it as a chat interface. ## What You'll Build A chat system that: 1. Accepts a user question (via chat, API, or AI assistant) 2. Searches your knowledge base for relevant information 3. Uses an AI model to generate an accurate answer grounded in your documents 4. Returns the answer with source references ```mermaid theme={null} flowchart LR Q["💬 User Question"] --> S["🔍 Vector Search
Knowledge Base"] S --> C["📋 Context
Assembly"] C --> G["🤖 AI Generation
with Context"] G --> A["✅ Grounded
Answer"] ``` ## Prerequisites * A Jinba Flow account ([Sign up here](https://flow.jinba.io/)) * Documents to upload — PDFs, DOCX, or text files you want your chat to reference * Basic familiarity with [Jinba Flow concepts](/en/pages/basics/core-concepts) — Flows, Steps, and Tools No coding experience is required. You can build the entire system using the chat panel or graph editor. The YAML manifests shown below are for reference and can be copied directly. ## Architecture Overview Before we start building, here's how all the pieces fit together: ```mermaid theme={null} flowchart TB subgraph input["Chat Input"] A1["Jinba App Chat"] A2["REST API"] A3["MCP / AI Assistant"] end subgraph flow["Jinba Flow — RAG Pipeline"] B1["Receive Question
INPUT_TEXT"] B2["Search Knowledge Base
JINBA_VECTOR_SEARCH"] B3["Generate Answer
OPENAI_INVOKE or ANTHROPIC_INVOKE"] end subgraph kb["Knowledge Backend"] C1["Jinba Knowledge Base"] C2["Pinecone"] C3["Azure AI Search"] end A1 & A2 & A3 --> B1 B1 --> B2 B2 --> C1 B2 -.-> C2 B2 -.-> C3 C1 & C2 & C3 --> B3 B3 --> A1 & A2 & A3 ``` This tutorial uses **Jinba Knowledge Base** as the primary backend. For other backends, see [Alternative Backends](#alternative-backends) near the end. *** ## Part 1: Set Up Your Knowledge Base ### Step 1: Create a Knowledge Base In your workspace sidebar, click **Storage**, then select the **Knowledge Bases** tab. Storage Knowledge Bases screen

Click **Create Knowledge Base**. Enter a descriptive name (for example, "Product Documentation" or "Company FAQ"). Create knowledge base button

After creation, open your new knowledge base and confirm it appears in the list. In this tutorial, the example knowledge base is named **RAG Tutorial KB**. Knowledge base created

### Step 2: Upload Documents Click on your newly created knowledge base from the Storage page. Click **Add files** to open the upload dialog. Select your PDFs, DOCX, Markdown, or text files from your computer. Uploading files to knowledge base

Processing may take a few minutes depending on file size. Do not proceed until your files show a completed status. ### Step 3: Store Your Credentials Before building the flow, store the required secrets in your workspace. Go to your [workspace credentials](/en/pages/credentials/index) page. Add the following secrets: | Secret Name | Value | Purpose | | - | - | - | | `JINBA_API_TOKEN` | Your Jinba API token | Authenticates vector search | | `KNOWLEDGE_BASE_ID` | Your knowledge base ID from Step 1 | Identifies which knowledge base to search | | `ANTHROPIC_API_KEY` | Your Anthropic API key *(optional)* | For Claude-based generation | If you do not have an OpenAI API key, you can still use `OPENAI_INVOKE` with [Jinba API credit](/en/pages/tools/ai/openai). *** ## Part 2: Build the RAG Flow Now let's create the workflow that powers the chat system. ### The Complete Manifest You can paste this directly into the [YAML Coding Panel](/en/pages/basics/manifest): ```yaml theme={null} # Step 1: Receive the user's question - id: user_question name: Receive Question tool: INPUT_TEXT input: - name: value value: "" # Step 2: Search the knowledge base for relevant content - id: search_knowledge name: Search Knowledge Base tool: JINBA_VECTOR_SEARCH config: - name: token value: "{{secrets.JINBAFLOW_WS_API_KEY}}" input: - name: query value: "{{steps.user_question.result}}" - name: knowledgeBaseId value: YOUR_KB_ID_HERE - name: topK value: 5 - name: threshold value: 0.3 needs: - user_question # Step 3: Generate an answer using the retrieved context - id: generate_answer name: Generate Answer tool: OPENAI_INVOKE config: - name: version value: gpt-4o input: - name: prompt value: | ## Instructions You are a helpful assistant. Answer the user's question based ONLY on the provided context. If the context doesn't contain the answer, say "I don't have enough information to answer that question." Always cite which source document(s) your answer comes from. ## Context (from knowledge base) {{steps.search_knowledge.results | dump}} ## User Question {{steps.user_question.result}} Please provide a clear, concise answer based on the context above. needs: - search_knowledge # Step 4: Output the answer - id: output_answer name: Output Answer tool: OUTPUT_TEXT input: - name: value value: "{{steps.generate_answer.result.content}}" needs: - generate_answer ``` Fastest path: paste the full YAML manifest above. If you prefer building flows visually, you can also add the four nodes manually in the editor and configure them one by one. ### Alternative: Build the Flow Manually in the Editor If you want to learn how each node is assembled visually, follow this manual path instead of pasting YAML. Open the node picker, search for **Input Text**, and add it as the first node in the graph. Manual build - add input text node

After adding it, rename the node to **Receive Question** so it matches the tutorial manifest. Manual build - configure receive question

Click the **+** connector under the first node, search for **Vector Search**, and add the `JINBA_VECTOR_SEARCH` node. Manual build - add vector search node

Then configure it with: * **Token**: `JINBAFLOW_WS_API_KEY` secret * **Query**: `{{steps.user_question.result}}` * **Knowledge Base ID**: your knowledge base ID * **Top K**: `5` * **Threshold**: `0.3` Manual build - configure vector search node

Manual build - configure vector search node

Add an **Invoke** node and choose `OPENAI_INVOKE`. Manual build - add openai invoke node

Set the model version to `gpt-4o`, then paste the same prompt shown in the YAML example so the model answers only from retrieved knowledge base context. Manual build - configure openai invoke node

Manual build - configure openai invoke node

Add an **Output Text** node as the final step. Manual build - add output text node

Rename it to **Output Answer**, and set its value to: ```text theme={null} {{steps.generate_answer.result.content}} ``` Manual build - configure output text node

### Step-by-Step Walkthrough #### Step 1: Receive Question (`INPUT_TEXT`) ```yaml theme={null} - id: user_question name: Receive Question tool: INPUT_TEXT input: - name: value value: "" ``` The `INPUT_TEXT` tool creates an input parameter for the flow. When executed manually, it shows a text box. When called via API, this becomes a parameter in the request body. Learn more about [input tools](/en/pages/tools/files/input). #### Step 2: Search Knowledge Base (`JINBA_VECTOR_SEARCH`) ```yaml theme={null} - id: search_knowledge name: Search Knowledge Base tool: JINBA_VECTOR_SEARCH config: - name: token value: "{{secrets.JINBAFLOW_WS_API_KEY}}" input: - name: query value: "{{steps.user_question.result}}" - name: knowledgeBaseId value: YOUR_KB_ID_HERE - name: topK value: 5 - name: threshold value: 0.3 needs: - user_question ``` This step performs semantic search — finding content by meaning, not just keywords. | Parameter | Value | Why | | - | - | - | | `topK` | 5 | Returns the 5 most relevant chunks | | `threshold` | 0.3 | Filters out low-relevance results | The `needs: [user_question]` ensures the search waits for the user's question before executing. See [Step Module Options](/en/pages/basics/step-options) for more details. Start with `topK: 5` and `threshold: 0.3`. If answers lack context, increase `topK`. If irrelevant content appears, increase `threshold`. See the [Vector Search reference](/en/pages/tools/jinba/vector_search) for more guidance. #### Step 3: Generate Answer (LLM) ```yaml theme={null} - id: generate_answer name: Generate Answer tool: OPENAI_INVOKE config: - name: version value: gpt-4o input: - name: prompt value: | ## Instructions You are a helpful assistant. Answer the user's question based ONLY on the provided context. If the context doesn't contain the answer, say "I don't have enough information to answer that question." Always cite which source document(s) your answer comes from. ## Context (from knowledge base) {{steps.search_knowledge.results | dump}} ## User Question {{steps.user_question.result}} Please provide a clear, concise answer based on the context above. needs: - search_knowledge ``` The `| dump` filter serializes the search results into the prompt so the LLM can read all retrieved chunks and their sources. Learn more about [Variables & Templates](/en/pages/basics/variables). #### Step 4: Output Answer (`OUTPUT_TEXT`) ```yaml theme={null} - id: output_answer name: Output Answer tool: OUTPUT_TEXT input: - name: value value: "{{steps.generate_answer.result.content}}" needs: - generate_answer ``` The `OUTPUT_TEXT` step captures the final answer as the flow's output, making it available when calling the flow via API or chat. Replace the generation step with: ```yaml theme={null} - id: generate_answer name: Generate Answer tool: ANTHROPIC_INVOKE config: - name: version value: claude-3-5-sonnet-20241022 - name: token value: "{{secrets.ANTHROPIC_API_KEY}}" input: - name: prompt value: | ... (same prompt as above) needs: - search_knowledge ``` See the [Anthropic tool reference](/en/pages/tools/ai/anthropic) for details. Replace the generation step with: ```yaml theme={null} - id: generate_answer name: Generate Answer tool: GEMINI_INVOKE config: - name: version value: gemini-1.5-flash - name: token value: "{{secrets.GEMINI_API_KEY}}" input: - name: prompt value: | ... (same prompt as above) needs: - search_knowledge ``` See the [Gemini tool reference](/en/pages/tools/ai/gemini) for details. ### Test Your Flow Build the four-step flow in the editor, then click the **Run** button in the top right. RAG flow in graph editor

When prompted, enter a question that your uploaded documents should be able to answer. Run dialog with test question

Check the execution results. The answer should reference information from your knowledge base.

*** ## Part 3: Deploy as a Chat Interface Your RAG flow works. Now make it accessible to users. Best for: End users who need a ready-made chat UI Best for: Custom applications and integrations Best for: AI assistant integration ### Option A: Jinba App Chat (Recommended) Deploy your RAG flow as a chat connector in Jinba App for the simplest end-user experience. In the flow editor, click the **Publish** button. A dialog will ask **"Who will trigger this workflow?"**: Publish flow

After selecting "My team", an education screen appears explaining that **Jinba Flow** (where you build) and **Jinba App** (where your team uses it) are separate products: * **Separate products, by design** — Jinba Flow is the builder; Jinba App is the chat interface your team uses * **Enterprise-grade security** — Jinba App has its own authentication and access controls * **Simple for your team** — No code, no complexity — just a familiar chat interface Click **Got it, continue** to proceed to the MCP setup. Flow and App relationship screen

The **Create an MCP** dialog appears. This shows a preview of how your flow will appear as a chat tool: * A chat preview showing `@your_flow_name` with a description * A **Demo** button to preview the chat experience * An **Enable MCP for this flow** toggle Create MCP dialog

You **must** turn on the **Enable MCP for this flow** toggle. This is what creates the connection between Jinba Flow and Jinba App — the "Connect with Jinba App" button only appears after you enable it. Once enabled, additional options appear: * **Workspace Token** — used for authentication * **Connection Snippet** — JSON config for MCP clients (Claude Desktop, Cursor, etc.) * **Connect with Jinba App** button — click this to open the connector in Jinba App Enabling MCP also lets AI assistants (Claude, Cursor, etc.) call this flow as a tool — you get both Jinba App chat **and** MCP tool access with a single toggle. See [Publish](/en/pages/basics/publish) for details. After enabling MCP, you'll be taken to the **MCP → Connect** tab. This page has several important sections: 1. **Your Token** — your workspace authentication token (keep this secret) 2. **1-Click Connect** — click **Connect** to instantly link this flow to Jinba App 3. **Visibility** — defaults to "Unlisted" (only users in your access rules can use it). Change to "Listed" if you want all workspace members to see it 4. **Access Scope Settings** — configure who can access this tool using JWT claims (e.g., email whitelist) 5. **MCP Configuration JSON Snippet** — copy this to use the flow in external MCP clients (Claude Desktop, Cursor, etc.) MCP Connect tab

You **must** click the **1-Click Connect** button to make the flow available as a tool in Jinba App. Without this step, the tool won't appear in Jinba App even though MCP is enabled. Add your team members' emails to the **Access Scope Settings** so they can also use this tool. Click **+ Add Rule** to add more email rules. Open [Jinba App](https://app.jinba.io/) and start a new chat: 1. Click **New Chat** 2. Click the **connectors** icon (⚙️) at the bottom of the chat input 3. In the "Search agents and connectors..." dropdown, find your workspace's **MCP connector** (e.g., "Tutorial Demonstrations MCP ... 1 tool") 4. Click into the MCP connector to see your **RAG Chat Demo** tool listed 5. Select the tool — it appears as a tag in the chat input bar 6. Type your question and press Enter Connector selection

The tool runs automatically — you'll see the **Arguments** (your `user_question`) and **Result** (the RAG response content) in an expandable section, followed by the AI's formatted answer. Chat with RAG in Jinba App

You can also use **Auto Select** mode — Jinba App will automatically choose the right tool based on your question, so you don't need to manually select the connector each time. See [Jinba Flow Connectors](/en/pages/jinba_app/connectors/jinbaflow) for the full guide. You can also create a [Jinba App Agent](/en/pages/jinba_app/agents/overview) that bundles this connector with custom instructions. ### Option B: REST API Expose your RAG flow as an API endpoint for custom applications. Follow the same publish steps as above, but select **Engineers** in the "Who will trigger this workflow?" dialog instead. This optimizes the flow for API access. After publishing, navigate to your flow's settings to find the auto-generated API key. API key location

```bash theme={null} curl -X POST https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "args": [ {"name": "user_question", "value": "What is your return policy?"} ], "mode": "sync" }' ``` **Python example:** ```python theme={null} import requests response = requests.post( "https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, json={ "args": [ {"name": "user_question", "value": "What is your return policy?"} ], "mode": "sync" } ) answer = response.json() print(answer) ``` See the full [API reference](/en/pages/basics/api) for async mode, error handling, and more. ### Option C: MCP Tool (AI Assistant Integration) Make your RAG flow available as a tool for AI assistants like Claude Desktop. Publish your flow with MCP enabled. Navigate to the **MCP** tab in your workspace settings. MCP configuration

Add the Jinba Flow MCP server to your AI assistant's configuration: ```json theme={null} { "mcpServers": { "jinbaflow": { "command": "npx", "args": [ "-y", "supergateway", "--streamableHttp", "https://api.jinba.io/api/v2/workspaces/YOUR_WORKSPACE_ID/mcp", "--header", "Authorization: Bearer YOUR_TOKEN" ] } } } ``` See the [MCP guide](/en/pages/basics/mcp) for the full setup process. Your RAG flow now appears as a tool. The AI assistant can invoke it to answer questions using your knowledge base. *** ## Part 4: Advanced Patterns ### Multi-Step RAG with Query Refinement For complex questions, add a refinement step that improves search results: ```yaml theme={null} - id: user_question name: Receive Question tool: INPUT_TEXT input: - name: value value: "" - id: initial_search name: Initial Search tool: JINBA_VECTOR_SEARCH config: - name: token value: "{{secrets.JINBAFLOW_WS_API_KEY}}" input: - name: query value: "{{steps.user_question.result}}" - name: knowledgeBaseId value: YOUR_KB_ID_HERE - name: topK value: 10 needs: - user_question - id: refine_query name: Refine Query tool: OPENAI_INVOKE config: - name: version value: gpt-4o input: - name: prompt value: | Based on the initial search results, generate a more specific search query. Original Question: {{steps.user_question.result}} Initial Results: {{steps.initial_search.results | dump}} Generate a refined search query that will find more specific information. Output ONLY the refined query, nothing else. needs: - initial_search - id: refined_search name: Refined Search tool: JINBA_VECTOR_SEARCH config: - name: token value: "{{secrets.JINBAFLOW_WS_API_KEY}}" input: - name: query value: "{{steps.refine_query.result.content}}" - name: knowledgeBaseId value: YOUR_KB_ID_HERE - name: topK value: 5 - name: threshold value: 0.4 needs: - refine_query - id: final_answer name: Generate Final Answer tool: OPENAI_INVOKE config: - name: version value: gpt-4o input: - name: prompt value: | Answer the user's question using the refined search results. Question: {{steps.user_question.result}} Refined Search Results: {{steps.refined_search.results | dump}} Provide a detailed, accurate answer with source citations. needs: - refined_search - id: output_answer name: Output Answer tool: OUTPUT_TEXT input: - name: value value: "{{steps.final_answer.result.content}}" needs: - final_answer ``` ### Handling No Results Found Use [conditional execution](/en/pages/basics/step-options) to handle cases where the knowledge base has no relevant content: ```yaml theme={null} - id: check_results name: Check Results tool: PYTHON_SANDBOX_RUN input: - name: code value: | results = {{steps.search_knowledge.result}} has_results = len(results.get('results', [])) > 0 print(has_results) - name: data_type value: STRING needs: - search_knowledge - id: generate_answer name: Generate Answer tool: OPENAI_INVOKE config: - name: version value: gpt-4o input: - name: prompt value: | ... standard RAG prompt with context ... needs: - check_results when: "'{{steps.check_results.result}}' == 'True'" - id: no_results_response name: No Results Response tool: PYTHON_SANDBOX_RUN input: - name: code value: | result = "I couldn't find relevant information in the knowledge base to answer your question. Please try rephrasing your question or contact support for assistance." - name: data_type value: STRING needs: - check_results when: "'{{steps.check_results.result}}' == 'False'" ``` ### Keeping Your Knowledge Base Updated Create a scheduled flow that automatically updates your knowledge base with new documents: ```yaml theme={null} - id: fetch_new_docs name: fetch_new_docs tool: PYTHON_SANDBOX_RUN input: - name: code value: | new_docs = [ "https://example.com/updated-faq.pdf", "https://example.com/new-product-guide.pdf" ] result = new_docs - name: data_type value: STRING - id: add_to_kb name: Add to Knowledge Base tool: JINBA_KNOWLEDGE_BASE_FILE_ADD forEach: "{{steps.fetch_new_docs.result}}" config: - name: token value: "{{secrets.JINBAFLOW_WS_API_KEY}}" input: - name: knowledgeBaseId value: YOUR_KB_ID_HERE - name: file value: "{{item}}" - name: executionMode value: "SYNCHRONOUS" - name: chunkerSettings value: chunkSize: 512 chunkOverlap: 128 ``` You can [schedule this flow](/en/pages/basics/scheduling) to run daily or weekly. *** ## Alternative Backends The primary tutorial uses Jinba Knowledge Base, but two additional backends are available for teams with specific requirements. ### When to Choose Each Backend ```mermaid theme={null} flowchart TD Start["Which backend
should I use?"] --> Q1{"Enterprise with
Azure ecosystem?"} Q1 -->|Yes| Azure["☁️ Azure AI Search
Enterprise"] Q1 -->|No| Q2{"Need metadata
filtering, namespaces,
or reranking?"} Q2 -->|Yes| Pinecone["🌲 Pinecone"] Q2 -->|No| Q3{"Want simplest
possible setup?"} Q3 -->|Yes| Jinba["⚡ Jinba Knowledge Base"] Q3 -->|No| Pinecone ``` | Feature | Jinba Knowledge Base | Pinecone | Azure AI Search | | - | - | - | - | | **Setup complexity** | ⭐ Simplest | ⭐⭐ Moderate | ⭐⭐⭐ Advanced | | **External dependency** | None | Pinecone account | Azure subscription | | **Document upload** | UI + API | API only | Azure portal / ADLS | | **Metadata filtering** | ❌ | ✅ Rich filter syntax | ✅ OData filters | | **Namespace isolation** | ❌ | ✅ | ✅ Indexes | | **Reranking** | ❌ | ✅ Built-in models | ✅ Semantic ranker | | **Indexer / pipeline** | Automatic | Manual | ✅ Built-in indexers | | **Cost** | Included in Jinba plan | Separate Pinecone billing | Azure billing | | **Best for** | Most use cases, quick start | Advanced search requirements | Enterprise / Azure-native organizations | ### Alternative A: Pinecone If you need metadata filtering, namespace isolation, or reranking, use [Pinecone](/en/pages/tools/search/pinecone) as your vector backend. #### Pinecone RAG Manifest Replace the search step with Pinecone: ```yaml theme={null} - id: search_pinecone name: Search Pinecone tool: PINECONE_QUERY config: - name: apiKey value: "{{secrets.PINECONE_API_KEY}}" input: - name: indexName value: my-knowledge-base - name: query value: "{{steps.user_question.result}}" - name: topK value: 5 - name: includeMetadata value: true - name: rerankModel value: bge-reranker-v2-m3 - name: rerankTopN value: 3 needs: - user_question ``` Then adjust the generation step to use Pinecone's output format: ```yaml theme={null} - id: generate_answer name: Generate Answer tool: OPENAI_INVOKE config: - name: version value: gpt-4o input: - name: prompt value: | You are a helpful assistant. Answer based on the provided context. ## User Question {{steps.user_question.result}} ## Relevant Documentation {{steps.search_pinecone.result.matches | dump}} Answer accurately based on the documentation above. needs: - search_pinecone ``` See the full [Pinecone tool reference](/en/pages/tools/search/pinecone) for index creation and document upsert. ### Alternative B: Azure AI Search (Enterprise) For enterprise organizations already using the Azure ecosystem, Jinba Flow supports **Azure AI Search** as an external knowledge base backend. This option provides advanced indexing, semantic ranking, and integration with Azure Data Lake Storage Gen2. Azure AI Search integration is an **enterprise feature**. Contact your Jinba administrator or the Jinba sales team to enable this for your workspace. #### How It Works Azure AI Search integration operates differently from the built-in knowledge base: 1. **Documents are stored in Azure** — uploaded to Azure Data Lake Storage Gen2 2. **Indexing is handled by Azure** — Azure AI Search indexers process and index documents 3. **Search queries go through Azure** — either directly or via Azure API Management (APIM) 4. **Results flow back to Jinba Flow** — where the LLM generates answers ```mermaid theme={null} flowchart LR Upload["📄 Upload Document"] --> ADLS["Azure Data Lake
Storage Gen2"] ADLS --> Indexer["Azure AI Search
Indexer"] Indexer --> Index["Azure AI Search
Index"] Query["🔍 User Query"] --> Index Index --> Results["📋 Search Results"] Results --> LLM["🤖 LLM Generation"] ``` #### Setup Overview In your workspace settings, navigate to the **External Knowledge Base** configuration. You can connect in two modes: | Mode | When to Use | | - | - | | **APIM Mode** | Routes through Azure API Management — recommended for production | | **Direct Mode** | Connects directly to Azure AI Search — simpler for development | Ensure you have: * An Azure AI Search service with an index configured * Azure Data Lake Storage Gen2 for document storage * API keys or APIM subscription keys * An indexer configured to process uploaded documents Upload documents through the Jinba workspace UI. Files are automatically sent to Azure Data Lake Storage, and the configured indexer processes them into the search index. The search step uses the External Knowledge Base configuration from your workspace. The exact tool and parameters depend on your enterprise deployment. #### Key Configuration Options | Setting | Description | | - | - | | **Endpoint URL** | Azure AI Search or APIM endpoint | | **API Key** | Authentication key | | **Index API Path** | Path for index operations | | **Search API Path** | Path for search queries | | **ADLS API Path** | Path for file storage operations | | **Indexer Name** | Indexer to trigger after file uploads | Connection settings can be configured per workspace through the UI, with environment variables as fallbacks. #### Azure AI Search Advantages * **Semantic ranking**: Azure's built-in semantic ranker improves result relevance * **Hybrid search**: Combine vector search with keyword search * **Built-in indexers**: Automatically extract and index content from various file formats * **Enterprise compliance**: Data stays within your Azure tenant * **Azure ecosystem integration**: Works well with other Azure services such as Azure OpenAI *** ## Tuning & Best Practices ### Chunking Configuration When adding files, tune chunk parameters for your content: | Content Type | Chunk Size | Overlap | Why | | - | - | - | - | | FAQ / Short answers | 256–512 | 64 | Precise, focused retrieval | | Technical docs | 512–1024 | 128 | Balance precision and context | | Long-form content | 1024–2048 | 256 | Maintain narrative context | ### Similarity Threshold Guide | Threshold | Behavior | Use When | | - | - | - | | 0.7–1.0 | Very strict, near-exact matches only | Precise factual lookups | | 0.4–0.7 | High relevance, closely related | Most Q\&A use cases | | 0.2–0.4 | Moderate, may include tangential results | Exploratory or broad questions | | 0.0–0.2 | Very broad, many results | Not recommended for production | ### Prompt Engineering Tips 1. **Be explicit about grounding**: Tell the LLM to answer only from the provided context 2. **Request citations**: Ask the LLM to reference source filenames 3. **Handle uncertainty**: Instruct the LLM to say "I don't know" when context is insufficient 4. **Set the tone**: Add persona instructions for your use case (formal, casual, technical) *** ## What's Next? Deep dive into knowledge base management, chunking, and RAG patterns Full parameter reference and advanced search examples External vector database with filtering and reranking Complete guide to calling flows via REST API Connect flows to AI assistants via MCP Wrap your RAG flow in an agent for enhanced chat # Sandbox Providers Source: https://carnot.mintlify.app/en/pages/toolbox/advanced/sandbox Learn about the provider-agnostic sandbox architecture and how to configure E2B and Daytona execution environments ## Overview Jinba Toolbox executes tool code in **isolated sandbox environments**. The sandbox system is designed around a provider-agnostic architecture: a shared interface package (`@jinba-toolbox/sandbox-core`) defines the contract, and individual provider packages (`sandbox-e2b`, `sandbox-daytona`) implement it. This separation means you can switch providers or add new ones without modifying any business logic. ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ API Server │ │ │ │ Execution Service ──▶ SandboxProvider interface │ │ │ ├─────────────────────────────────────────────────────────────┤ │ Provider Implementations │ │ ┌────────────────┐ ┌─────────────────┐ │ │ │ sandbox-e2b │ │ sandbox-daytona │ │ │ │ (E2B Code │ │ (Daytona SDK) │ │ │ │ Interpreter) │ │ │ │ │ └────────────────┘ └─────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ sandbox-core │ │ (Interfaces & Types only) │ └─────────────────────────────────────────────────────────────┘ ``` ## Core Interface The `@jinba-toolbox/sandbox-core` package contains only interfaces and types -- no concrete implementations. All providers must conform to these contracts. ### SandboxProvider The factory that creates and resumes sandbox instances: ```typescript theme={null} interface SandboxProvider { /** Create a new sandbox instance */ create(options: SandboxCreateOptions): Promise; /** Resume an existing sandbox by ID */ resume(sandboxId: string): Promise; } ``` ### SandboxInstance A running sandbox environment with code execution, shell commands, and filesystem access: ```typescript theme={null} interface SandboxInstance { readonly sandboxId: string; readonly commands: SandboxCommands; readonly filesystem: SandboxFilesystem; executeCode( code: string, language: SandboxLanguage, options?: CodeExecutionOptions ): Promise; kill(): Promise; pause(): Promise; getHost(port: number): Promise; } ``` ### SandboxCommands Shell command execution within the sandbox: ```typescript theme={null} interface SandboxCommands { run( command: string, options?: SandboxCommandOptions ): Promise; } ``` ### SandboxFilesystem File operations within the sandbox: ```typescript theme={null} interface SandboxFilesystem { read(path: string): Promise; readBytes(path: string): Promise; write(path: string, content: string | Uint8Array): Promise; list(path: string): Promise; exists(path: string): Promise; mkdir(path: string): Promise; remove(path: string): Promise; } ``` ### Key Types ```typescript theme={null} type SandboxLanguage = "python" | "typescript"; interface SandboxCreateOptions { language: SandboxLanguage; packages?: string[]; // Packages to install envs?: Record; // Environment variables workingDirectory?: string; // Working directory inside sandbox timeoutMs?: number; // Timeout in milliseconds } interface CodeExecutionResult { success: boolean; output?: unknown; // Parsed JSON output if available stdout: string; stderr: string; durationMs: number; error?: { name: string; message: string; traceback?: string; }; } interface SandboxExecutionResult { exitCode: number; stdout: string; stderr: string; } ``` ## E2B Provider The `@jinba-toolbox/sandbox-e2b` package implements the sandbox interface using the [E2B Code Interpreter](https://e2b.dev) SDK. ### Configuration ```typescript theme={null} import { createE2BProvider } from "@jinba-toolbox/sandbox-e2b"; const provider = createE2BProvider({ apiKey: process.env.E2B_API_KEY!, templateId: "custom-template", // Optional custom sandbox template timeoutMs: 300000, // Default: 5 minutes }); ``` | Option | Type | Default | Description | | - | - | - | - | | `apiKey` | `string` | (required) | E2B API key | | `templateId` | `string` | `undefined` | Custom sandbox template ID | | `timeoutMs` | `number` | `300000` | Default timeout (5 minutes) | ### How It Works 1. **Sandbox creation**: The provider creates an E2B Code Interpreter sandbox, optionally using a custom template. 2. **Package installation**: If packages are specified, `pip install` (Python) or `npm install` (TypeScript) runs inside the sandbox. 3. **Code execution**: Tool code is executed via E2B's `runCode` API in a Jupyter-like kernel. 4. **Lifecycle**: Sandboxes can be paused, resumed, or terminated. ### TypeScript Note E2B's Code Interpreter executes TypeScript in a Jupyter kernel that does not support ESM file imports. For this reason, TypeScript tool code is **inlined** rather than loaded from files. Python tools can use filesystem imports normally. ## Daytona Provider The `@jinba-toolbox/sandbox-daytona` package implements the sandbox interface using the [Daytona](https://daytona.io) SDK. ### Configuration ```typescript theme={null} import { createDaytonaProvider } from "@jinba-toolbox/sandbox-daytona"; const provider = createDaytonaProvider({ apiKey: process.env.DAYTONA_API_KEY!, apiUrl: "https://app.daytona.io/api", // Default target: "us", // Region: "us" or "eu" timeoutMs: 300000, // Default: 5 minutes }); ``` | Option | Type | Default | Description | | - | - | - | - | | `apiKey` | `string` | (required) | Daytona API key | | `apiUrl` | `string` | `https://app.daytona.io/api` | Daytona API URL | | `target` | `string` | `us` | Target region (`us` or `eu`) | | `timeoutMs` | `number` | `300000` | Default timeout (5 minutes) | ### How It Works 1. **Sandbox creation**: The provider initializes the Daytona SDK and creates a sandbox with the specified language. 2. **Package installation**: If packages are specified, the provider runs `pip install` or `npm install` inside the sandbox. 3. **Code execution**: Tool code is executed via Daytona's `process.codeRun` API. 4. **Lifecycle**: Sandboxes can be started, stopped, and deleted. ## ToolSet Sandbox Configuration When creating a toolset, you specify which sandbox provider and settings to use: ```typescript theme={null} await client.createToolSet({ slug: "data-tools", name: { default: "Data Tools" }, description: { default: "Data processing tools" }, sandbox: { provider: "e2b", // or "daytona" language: "python", // or "typescript" packages: [ { name: "pandas", version: "2.0" }, { name: "numpy" } ], resources: { cpu: "2", memory: "4Gi", timeout: 120000 } } }); ``` The `SandboxConfig` stored on each toolset: ```typescript theme={null} interface SandboxConfig { provider: "e2b" | "daytona"; language: "python" | "typescript"; runtime?: string; packages: { name: string; version?: string }[]; resources: { cpu?: string; memory?: string; timeout?: number; }; } ``` ## Error Handling All sandbox packages use a unified `SandboxError` type: ```typescript theme={null} class SandboxError extends Error { constructor( message: string, code: SandboxErrorCode, cause?: unknown ); } type SandboxErrorCode = | "CONNECTION_FAILED" // Failed to connect to provider | "TIMEOUT" // Execution timed out | "NOT_FOUND" // Sandbox not found (resume) | "EXECUTION_FAILED" // Code execution failed | "INTERNAL"; // Unexpected internal error ``` ## Adding a New Provider The architecture is designed for extensibility. To add a new sandbox provider: Create `packages/sandbox-` with the standard package structure. Implement `create()` and `resume()` methods that return a `SandboxInstance`. Add the provider case to the API server's `getSandboxProvider` function. No changes to `sandbox-core` or business logic are needed. ## Related * [REST API](/en/pages/toolbox/developer/api) -- Endpoints for managing toolsets and running tools * [Versioning & Publishing](/en/pages/toolbox/advanced/versioning) -- How sandbox config is frozen in versions * [Security & Access Control](/en/pages/toolbox/advanced/security) -- Isolation and tenant boundaries # Security & Access Control Source: https://carnot.mintlify.app/en/pages/toolbox/advanced/security Understand RBAC, authentication methods, and organization-based isolation in Jinba Toolbox ## Overview Jinba Toolbox implements a multi-layered security model centered on **organization-based isolation**. Every resource -- toolsets, tools, versions, runs, API keys, and webhooks -- belongs to an organization and is protected by role-based access control (RBAC), authenticated sessions or API keys, and database-level tenant isolation. ## Authentication Jinba Toolbox supports two authentication methods, each designed for a different access pattern: Used by the admin web console. Powered by **Better Auth** with session cookies. * Cookie-based session management * For human users managing toolsets * Full CRUD access to organization resources Used by the SDK, AI agents, and external integrations. Passed as a Bearer token. * `Authorization: Bearer jtb_xxxxxxxxxxxx` * For automated and programmatic access * Scoped to a single organization ### API Key Management API keys are scoped to an organization and track their issuer: ``` Organization └── API Keys ├── production (issued by: alice) Last used: 2 hours ago ├── development (issued by: bob) Last used: 30 days ago └── ci-cd (issued by: alice) Last used: never ``` Key properties: * **No expiration** by default -- keys remain valid until manually deleted. * **Last-used timestamp** is recorded for each key. * **Issuer tracking** -- the member who created the key is recorded. * **Audit logging** -- key creation and deletion events are logged. If the member who issued a key leaves the organization, the key remains active to avoid breaking integrations. The admin console displays a warning, and an Owner or Admin can take over or regenerate the key. ### API Key Endpoints | Method | Endpoint | Description | | - | - | - | | GET | `/v1/orgs/:orgId/api-keys` | List API keys | | POST | `/v1/orgs/:orgId/api-keys` | Create API key | | DELETE | `/v1/orgs/:orgId/api-keys/:keyId` | Delete API key | ## Role-Based Access Control (RBAC) ### Role Hierarchy Jinba Toolbox defines roles at two levels: ``` Platform Level └── super_admin # Service-wide administration Organization Level ├── Owner # Organization owner (one per org) ├── Admin # Organization administrator └── Member # Regular member ``` ### Organization Roles | Role | Description | | - | - | | **Owner** | Full control over the organization, including transfer and deletion. One Owner per organization. | | **Admin** | Can manage members, billing, and all organization resources. Cannot delete the organization. | | **Member** | Can create and manage toolsets and tools. Cannot manage other members or billing. | ### Permission Matrix | Resource | Owner | Admin | Member | | - | - | - | - | | Organization settings | CRUD | Read / Update | Read | | Delete organization | Yes | No | No | | Member management | CRUD | CRUD | Read | | Invite members | Yes | Yes | No | | ToolSet / Tool | CRUD | CRUD | CRUD | | API keys (own) | CRUD | CRUD | CRUD | | API keys (others') | CRUD | CRUD | No | | Purchase credits | Yes | Yes | No | | View credit balance | Yes | Yes | Read | | Audit logs | Read | Read | No | ### Role Rules * Each organization has exactly **one Owner**. * Ownership can be **transferred** to another member (the original owner becomes Admin). * Only Owners and Admins can **invite** new members. * Members can manage their own API keys but cannot see or delete keys created by others. ## Organization-Based Isolation Every resource in Jinba Toolbox is scoped to an organization. The isolation is enforced at multiple layers: ### Application Layer The API server validates that the authenticated user or API key belongs to the target organization before processing any request. This ensures that even if a database query is somehow misconfigured, the application layer blocks unauthorized access. ### Database Layer (Row Level Security) PostgreSQL Row Level Security (RLS) provides an additional layer of tenant isolation at the database level: ```sql theme={null} ALTER TABLE tool_set ENABLE ROW LEVEL SECURITY; CREATE POLICY tool_set_tenant_isolation ON tool_set USING (organization_id = current_setting('app.current_org_id')); ``` **How it works:** The API server authenticates the request and determines the organization ID. Before executing any queries, the server sets the PostgreSQL session variable: ```sql theme={null} SET app.current_org_id = :orgId ``` PostgreSQL automatically filters all query results to only include rows belonging to the current organization. **Tables protected by RLS:** * `tool_set` * `tool` * `tool_set_version` * `run` * `apikey` * `webhook` * `audit_log` This multi-layer approach (application + database) provides **defense in depth** -- even if a bug bypasses the application checks, the database itself prevents cross-tenant data access. ## Audit Logging Significant actions within an organization are recorded in an audit log: | Category | Events | | - | - | | API Key | Created, deleted | | Member | Added, removed, role changed | | ToolSet | Published, published version changed | | Settings | Organization settings changed, webhook configuration changed | Tool executions are tracked separately in the `runs` table with full input/output logging. ### Audit Log Data Model ```typescript theme={null} interface AuditLog { id: string; orgId: string; userId: string; // Who performed the action action: string; // e.g., "member.added" targetType: string; // e.g., "member" targetId: string; // ID of the affected resource details: object; // Change details ipAddress: string; createdAt: Date; } ``` ### Viewing Audit Logs Audit logs are available to **Owner** and **Admin** roles in the web console at `/org/:orgId/settings/audit-log`. Logs are retained **indefinitely**. ## Sandbox Isolation Tool execution occurs in isolated sandbox environments (E2B or Daytona). Each execution runs in a fresh or resumed sandbox instance with: * **Process isolation** -- each sandbox is a separate container or VM. * **Network isolation** -- sandboxes cannot access the API server's internal network. * **Configurable environment variables** -- secrets are injected per toolset, not shared across toolsets. * **Automatic cleanup** -- sandboxes are terminated after execution completes or times out. ## Best Practices * **Use separate API keys** for different environments (production, staging, CI/CD) to limit blast radius if a key is compromised. * **Audit API key usage** -- review the last-used timestamp regularly and delete keys that are no longer needed. * **Assign the least-privilege role** -- use Member for developers who only need to create and edit tools. * **Review audit logs** periodically to detect unexpected access patterns. * **Do not share API keys** between organizations -- each key is scoped to a single organization. ## Related * [REST API](/en/pages/toolbox/developer/api) -- Authentication details and endpoint reference * [Webhooks](/en/pages/toolbox/developer/webhooks) -- Event notification security (signature verification) * [Sandbox Providers](/en/pages/toolbox/advanced/sandbox) -- Execution environment isolation # Versioning & Publishing Source: https://carnot.mintlify.app/en/pages/toolbox/advanced/versioning Understand how Jinba Toolbox manages immutable toolset versions with semantic versioning ## Overview Jinba Toolbox uses a **semver-based versioning system** with immutable snapshots. Each toolset maintains a draft (the editable working copy) and a list of published versions. When you publish, a complete snapshot of the toolset -- including all tool code, schemas, and sandbox configuration -- is frozen as an immutable version that can never be modified. This design ensures **reproducibility**: running version `1.0.0` always executes the same code, regardless of when or where it is called. ## Concepts ### Draft vs. Versions ``` ToolSet ├── Draft (editable working copy) └── Versions (immutable releases) ├── v1.2.0 [published] ├── v1.1.0 └── v1.0.0 ``` | State | Description | | - | - | | **Draft** | The editable working copy. Modified through the web UI or API. Can only be executed via the `test` endpoint. | | **Version** | An immutable release. Once published, it cannot be changed. Used by the `run` endpoint. | | **Published** | The currently active version served by the API. One published version per toolset at a time. | ### Immutable Snapshots Each version captures a complete snapshot of the toolset at the time of publishing: * All tool code and entrypoints * Input and output schemas * Tool names and descriptions * Sandbox configuration (provider, language, packages, resources) This means even if you later update the draft, existing versions remain unchanged. ## Publishing Workflow Make changes to tools in the draft through the web console or the API. Use the test endpoint to verify behavior: ```bash theme={null} curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/tools/post-message/test \ -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "input": { "channel": "#test", "text": "Testing..." } }' ``` When the draft is ready, publish it with a semver version number and optional release notes: ```bash theme={null} curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/versions \ -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "version": "1.3.0", "releaseNotes": "Added thread reply support" }' ``` Or using the SDK: ```typescript theme={null} const version = await client.publishVersion("slack-tools", { version: "1.3.0", releaseNotes: "Added thread reply support", }); ``` Choose which version the API should serve. Newly published versions do not automatically become the active version -- you must explicitly set it: ```bash theme={null} curl -X PUT https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/published-version \ -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "version": "1.3.0" }' ``` The change takes effect immediately. The draft remains intact after publishing, so you can keep iterating on the next version without affecting the live published version. ## Version Resolution When a tool is executed via the `run` endpoint, Jinba Toolbox resolves which version to use: 1. If the request body includes a `version` field, that exact version is used. 2. Otherwise, the currently published (active) version is used. ```bash theme={null} # Uses the published version curl -X POST .../tools/post-message/run \ -d '{ "input": { "channel": "#general", "text": "Hello" } }' # Uses a specific version curl -X POST .../tools/post-message/run \ -d '{ "input": { "channel": "#general", "text": "Hello" }, "version": "1.2.0" }' ``` ## Rollback Rolling back is simply a matter of changing the published version to a previous one: ```bash theme={null} # Switch back to v1.2.0 curl -X PUT https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools/published-version \ -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "version": "1.2.0" }' ``` Because versions are immutable, no data is lost during a rollback. The newer version remains available and can be re-activated at any time. ## Version API | Method | Endpoint | Description | | - | - | - | | GET | `/v1/orgs/:orgId/toolsets/:slug/versions` | List all versions | | POST | `/v1/orgs/:orgId/toolsets/:slug/versions` | Publish a new version | | GET | `/v1/orgs/:orgId/toolsets/:slug/versions/:version` | Get version details | | PUT | `/v1/orgs/:orgId/toolsets/:slug/published-version` | Set the active published version | ## Version Data Model Each published version stores a full snapshot: ```typescript theme={null} interface ToolSetVersion { id: string; toolSetId: string; version: string; // Semver string (e.g., "1.3.0") sandbox: SandboxConfig; // Frozen sandbox configuration tools: ToolSnapshot[]; // Frozen tool definitions and code releaseNotes?: string | null; publishedBy: string; // User ID of the publisher publishedAt: string; // ISO 8601 timestamp } interface ToolSnapshot { id: string; slug: string; name: LocalizedText; description: LocalizedText; inputSchema: JSONSchema; outputSchema: JSONSchema; code: string; entrypoint?: string; } ``` ## Usage Tracking Jinba Toolbox tracks API call counts per version. You can view usage statistics in the web console or retrieve run history through the API: ```typescript theme={null} const runs = await client.listRuns(); // Filter by version in your application logic ``` Usage data helps you determine when it is safe to deprecate older versions. ## Best Practices * **Follow semantic versioning** -- use major bumps for breaking schema changes, minor bumps for new tools or features, and patch bumps for fixes. * **Write release notes** -- they help your team understand what changed between versions. * **Test before publishing** -- use the `test` endpoint to validate the draft before creating an immutable version. * **Do not skip the publish step for MCP** -- MCP endpoints serve the published version, not the draft. * **Monitor per-version usage** -- before deprecating a version, verify that no consumers still depend on it. ## Related * [REST API](/en/pages/toolbox/developer/api) -- Full endpoint reference including version routes * [SDK](/en/pages/toolbox/developer/sdk) -- Programmatic version management * [Security & Access Control](/en/pages/toolbox/advanced/security) -- Who can publish versions # MCP Integration Source: https://carnot.mintlify.app/en/pages/toolbox/developer/mcp Connect AI agents to Jinba Toolbox via the Model Context Protocol (MCP) ## Overview Jinba Toolbox provides native **Model Context Protocol (MCP)** endpoints that expose your toolsets as MCP-compatible servers. This allows AI agents and LLM-based applications -- such as Claude Desktop, Cursor, and custom agent frameworks -- to discover and execute your tools through a standardized JSON-RPC interface. Each MCP-enabled toolset becomes an MCP server. The endpoint accepts JSON-RPC requests conforming to the MCP specification and returns tool definitions, executes tools, and streams results. ## MCP Endpoints Jinba Toolbox offers two types of MCP endpoints: For internal use within your organization. Requires organization-scoped API key authentication. ``` POST /v1/orgs/:orgId/toolsets/:slug/mcp ``` For external consumers accessing public toolsets. Requires an API key for usage tracking and rate limiting. ``` POST /v1/public/:orgSlug/:toolsetSlug/mcp ``` ## Enabling MCP for a ToolSet MCP must be enabled on a per-toolset basis. You can toggle it in the web console or through the API: ```bash theme={null} curl -X PATCH https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools \ -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "mcpEnabled": true }' ``` Or via the SDK: ```typescript theme={null} await client.updateToolSet("slack-tools", { mcpEnabled: true }); ``` ## Connecting AI Agents ### Claude Desktop Add a Jinba Toolbox MCP server to your Claude Desktop configuration file (`claude_desktop_config.json`): ```json theme={null} { "mcpServers": { "slack-tools": { "url": "https://toolbox-api.jinba.dev/v1/public/my-org/slack-tools/mcp", "headers": { "Authorization": "Bearer jtb_xxxxxxxxxxxx" } } } } ``` ### Cursor In Cursor's MCP settings, add a new server using the streamable HTTP transport: ```json theme={null} { "mcpServers": { "slack-tools": { "url": "https://toolbox-api.jinba.dev/v1/public/my-org/slack-tools/mcp", "headers": { "Authorization": "Bearer jtb_xxxxxxxxxxxx" } } } } ``` ### Custom Agent Integration If you are building a custom agent, connect to the MCP endpoint using any MCP-compatible client library. The endpoint supports JSON-RPC over HTTP. **Example using the MCP TypeScript SDK:** ```typescript theme={null} import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const transport = new StreamableHTTPClientTransport( new URL("https://toolbox-api.jinba.dev/v1/public/my-org/slack-tools/mcp"), { requestInit: { headers: { Authorization: "Bearer jtb_xxxxxxxxxxxx", }, }, } ); const client = new Client({ name: "my-agent", version: "1.0.0" }); await client.connect(transport); // List available tools const { tools } = await client.listTools(); console.log(tools); // Call a tool const result = await client.callTool({ name: "post-message", arguments: { channel: "#general", text: "Hello from my AI agent!", }, }); console.log(result); ``` ## How It Works The agent sends a `tools/list` JSON-RPC request to the MCP endpoint. Jinba Toolbox responds with the list of tools in the toolset, including their names, descriptions, and input schemas. When the agent needs to use a tool, it sends a `tools/call` request with the tool name and arguments. The request is validated against the tool's input schema. Jinba Toolbox executes the tool code in an isolated sandbox environment (E2B or Daytona). The published version of the tool is used. The execution result -- including output, logs, and any errors -- is returned to the agent through the MCP response. ## Organization vs. Public Endpoints | Aspect | Organization Endpoint | Public Endpoint | | - | - | - | | URL pattern | `/v1/orgs/:orgId/toolsets/:slug/mcp` | `/v1/public/:orgSlug/:toolsetSlug/mcp` | | Authentication | Org-scoped API key | API key | | Access scope | Private and public toolsets | Public toolsets only | | Use case | Internal agents, CI/CD | External consumers, shared agents | ## Authentication Both MCP endpoints require a Bearer token in the `Authorization` header: ``` Authorization: Bearer jtb_xxxxxxxxxxxx ``` The API key determines: * Which organization the request is associated with * Usage tracking and credit consumption * Rate limiting ## Best Practices * **Enable MCP selectively** -- only activate MCP on toolsets that you intend to expose to AI agents. * **Use the public endpoint** for external integrations and the organization endpoint for internal workflows. * **Monitor usage** through the run history API to track which tools agents are calling and how frequently. * **Publish a version** before exposing a toolset via MCP -- the endpoint executes the published version, not the draft. * **Provide clear tool descriptions** -- AI agents rely on tool names and descriptions to decide which tool to invoke. ## Related * [REST API](/en/pages/toolbox/developer/api) -- Full endpoint reference * [SDK](/en/pages/toolbox/developer/sdk) -- Programmatic access via the TypeScript SDK * [Versioning & Publishing](/en/pages/toolbox/advanced/versioning) -- How published versions are resolved # SDK Source: https://carnot.mintlify.app/en/pages/toolbox/developer/sdk Use the @jinba-toolbox/sdk package to interact with Jinba Toolbox from TypeScript and JavaScript applications ## Overview The `@jinba-toolbox/sdk` package provides a type-safe client library for consuming tools registered in Jinba Toolbox. It wraps the REST API with convenient methods for listing toolsets, executing tools, managing versions, and retrieving run history. **Target consumers:** * AI agents executing tools * CLI tools for automation * Third-party applications integrating with Jinba Toolbox * Developers building on Jinba Toolbox ## Installation ```bash theme={null} # npm npm install @jinba-toolbox/sdk # pnpm pnpm add @jinba-toolbox/sdk # yarn yarn add @jinba-toolbox/sdk ``` ## Quick Start ```typescript theme={null} import { createClient } from "@jinba-toolbox/sdk"; const client = createClient({ apiKey: process.env.JINBA_TB_API_KEY!, organizationId: "org-id", // optional default }); ``` ```typescript theme={null} const toolSets = await client.listToolSets(); console.log(toolSets); ``` ```typescript theme={null} const result = await client.run("slack-tools", "post-message", { channel: "#general", text: "Hello from Jinba Toolbox!", }); console.log(result.output); // { ts: "1234567890.123456", channel: "C01234567" } ``` ## Client Configuration The `createClient` function accepts a `JinbaTBClientConfig` object: ```typescript theme={null} interface JinbaTBClientConfig { /** API base URL (default: https://toolbox-api.jinba.dev) */ baseUrl?: string; /** API key for authentication */ apiKey: string; /** Default organization ID (optional, can be overridden per request) */ organizationId?: string; /** Request timeout in milliseconds (default: 30000) */ timeout?: number; } ``` **Example** with all options: ```typescript theme={null} const client = createClient({ baseUrl: "https://toolbox-api.jinba.dev", apiKey: "jtb_xxxxxxxxxxxx", organizationId: "org_abc123", timeout: 60000, }); ``` If you set `organizationId` in the constructor, you can omit it from individual method calls. Every method also accepts an optional `orgId` parameter to override the default. ## API Reference ### Organizations ```typescript theme={null} // List organizations the authenticated user belongs to const orgs = await client.listOrganizations(); // Returns: OrganizationWithRole[] // Get organization details const org = await client.getOrganization("org-id"); // Returns: Organization ``` ### ToolSets ```typescript theme={null} // List toolsets in an organization const toolSets = await client.listToolSets(); // Returns: ToolSet[] // Get a toolset by slug (includes tools) const toolSet = await client.getToolSet("slack-tools"); // Returns: ToolSet & { tools: Tool[] } // Create a new toolset const newToolSet = await client.createToolSet({ slug: "slack-tools", name: { default: "Slack Tools" }, description: { default: "Slack integration tools" }, sandbox: { provider: "e2b", language: "typescript", packages: [{ name: "@slack/web-api" }], resources: { timeout: 60000 }, }, visibility: "private", tags: ["slack"], }); // Update a toolset await client.updateToolSet("slack-tools", { visibility: "public", tags: ["slack", "messaging"], }); // Delete a toolset await client.deleteToolSet("slack-tools"); ``` ### Tools ```typescript theme={null} // List tools in a toolset const tools = await client.listTools("slack-tools"); // Returns: Tool[] // Get a tool by slug const tool = await client.getTool("slack-tools", "post-message"); // Returns: Tool // Create a new tool const newTool = await client.createTool("slack-tools", { slug: "post-message", name: { default: "Post Message" }, description: { default: "Post a message to a Slack channel" }, inputSchema: { type: "object", properties: { channel: { type: "string", description: "Channel name or ID" }, text: { type: "string", description: "Message text" }, }, required: ["channel", "text"], }, outputSchema: { type: "object", properties: { ts: { type: "string" }, channel: { type: "string" }, }, }, code: `// tool implementation code`, }); // Update a tool await client.updateTool("slack-tools", "post-message", { description: { default: "Post a message to any Slack channel" }, }); // Delete a tool await client.deleteTool("slack-tools", "post-message"); ``` ### Execution ```typescript theme={null} // Execute a published tool const result = await client.run("slack-tools", "post-message", { channel: "#general", text: "Hello!", }); // Returns: RunResult console.log(result.success); // true console.log(result.output); // { ts: "...", channel: "..." } console.log(result.durationMs); // 1234 // Execute a specific version const result = await client.run( "slack-tools", "post-message", { channel: "#general", text: "Hello!" }, { version: "1.2.0" } ); // Test a tool (runs draft code, no published version required) const testResult = await client.test("slack-tools", "post-message", { channel: "#test", text: "Testing...", }); ``` ### Versions ```typescript theme={null} // List versions of a toolset const versions = await client.listVersions("slack-tools"); // Returns: ToolSetVersion[] // Publish a new version const version = await client.publishVersion("slack-tools", { version: "1.3.0", releaseNotes: "Added thread reply support", }); // Returns: ToolSetVersion ``` ### Run History ```typescript theme={null} // List runs in an organization const runs = await client.listRuns(); // Returns: Run[] // Get run details const run = await client.getRun("run_abc123"); // Returns: Run ``` ## Key Types ### RunResult The object returned from `run()` and `test()`: ```typescript theme={null} interface RunResult { runId: string; version: string; success: boolean; output?: Record; error?: { name: string; message: string; traceback?: string }; logs?: { stdout: string[]; stderr: string[] }; durationMs?: number; } ``` ### ToolSet ```typescript theme={null} interface ToolSet { id: string; organizationId: string; slug: string; name: LocalizedText; description: LocalizedText; sandbox: SandboxConfig; visibility: "public" | "private" | "restricted"; mcpEnabled: boolean; tags: string[]; latestVersion?: string | null; publishedVersion?: string | null; createdAt: string; updatedAt: string; } ``` ### Tool ```typescript theme={null} interface Tool { id: string; toolSetId: string; slug: string; name: LocalizedText; description: LocalizedText; inputSchema: JSONSchema; outputSchema: JSONSchema; code: string; entrypoint?: string | null; createdAt: string; updatedAt: string; } ``` ## Error Handling The SDK throws `JinbaTBError` for non-2xx responses: ```typescript theme={null} import { JinbaTBError } from "@jinba-toolbox/sdk"; try { const result = await client.run("my-toolset", "my-tool", { input: "data" }); } catch (error) { if (error instanceof JinbaTBError) { console.error(`Status: ${error.statusCode}`); console.error(`Message: ${error.message}`); console.error(`Details: ${JSON.stringify(error.details)}`); } } ``` A 408 status code is thrown when a request exceeds the configured timeout. ## Best Practices * **Set a default `organizationId`** in the constructor to avoid passing it to every method. * **Use environment variables** for the API key -- never hard-code credentials. * **Handle `JinbaTBError`** to distinguish between client errors (4xx) and server errors (5xx). * **Increase `timeout`** for tool executions that run complex sandbox workloads. * **Pin a version** when calling `run()` if your application depends on deterministic behavior. ## Related * [REST API](/en/pages/toolbox/developer/api) -- Full endpoint reference * [MCP Integration](/en/pages/toolbox/developer/mcp) -- Use toolsets as MCP servers for AI agents * [Versioning & Publishing](/en/pages/toolbox/advanced/versioning) -- Understand the version lifecycle # Webhooks Source: https://carnot.mintlify.app/en/pages/toolbox/developer/webhooks Receive real-time event notifications from Jinba Toolbox via webhooks ## Overview Webhooks allow you to receive HTTP notifications whenever significant events occur in your organization. Instead of polling the API, you register a URL and Jinba Toolbox pushes event payloads to it in real time. Webhooks are configured **per organization** and can subscribe to one or more event types. ## Event Types | Event | Description | | - | - | | `tool.run.completed` | A tool execution finished successfully | | `tool.run.failed` | A tool execution failed | | `toolset.published` | A new toolset version was published | | `member.added` | A new member was added to the organization | | `member.removed` | A member was removed from the organization | ## Setting Up Webhooks Set up an HTTP endpoint on your server that can receive POST requests. The endpoint must return a `2xx` status code to acknowledge receipt. Use the API or the web console to register your endpoint URL and select the events you want to subscribe to. ```bash theme={null} curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/webhooks \ -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/jinba", "events": ["tool.run.completed", "tool.run.failed"] }' ``` When you create a webhook, a signing secret is generated. Store it securely -- you will use it to verify incoming payloads. Verify your endpoint is working by sending a test event: ```bash theme={null} curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/webhooks/{webhookId}/test \ -H "Authorization: Bearer jtb_xxxxxxxxxxxx" ``` ## Webhook Configuration Each webhook has the following properties: ```typescript theme={null} interface Webhook { id: string; orgId: string; url: string; // Destination URL events: string[]; // Subscribed event types secret: string; // HMAC signing secret enabled: boolean; // Whether the webhook is active createdAt: Date; } ``` ## Payload Format Every webhook delivery sends a JSON payload with the following structure: ```json theme={null} { "event": "tool.run.completed", "timestamp": "2026-02-01T12:00:00Z", "data": { "runId": "run_abc123", "toolSetSlug": "slack-tools", "toolSlug": "post-message", "status": "success", "durationMs": 1234 } } ``` ### Event-Specific Payloads **`tool.run.completed`** ```json theme={null} { "event": "tool.run.completed", "timestamp": "2026-02-01T12:00:00Z", "data": { "runId": "run_abc123", "toolSetSlug": "slack-tools", "toolSlug": "post-message", "status": "success", "durationMs": 1234 } } ``` **`tool.run.failed`** ```json theme={null} { "event": "tool.run.failed", "timestamp": "2026-02-01T12:05:00Z", "data": { "runId": "run_def456", "toolSetSlug": "slack-tools", "toolSlug": "post-message", "status": "failed", "error": { "name": "SlackAPIError", "message": "channel_not_found" }, "durationMs": 567 } } ``` **`toolset.published`** ```json theme={null} { "event": "toolset.published", "timestamp": "2026-02-01T10:00:00Z", "data": { "toolSetSlug": "slack-tools", "version": "1.3.0", "publishedBy": "user_abc123", "releaseNotes": "Added thread reply support" } } ``` **`member.added`** ```json theme={null} { "event": "member.added", "timestamp": "2026-02-01T09:00:00Z", "data": { "userId": "user_xyz789", "email": "newmember@example.com", "role": "member" } } ``` ## Signature Verification Every webhook request includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature of the request body, computed with your webhook's signing secret. ``` X-Webhook-Signature: sha256=a1b2c3d4e5f6... ``` **Verify the signature** on your server to ensure payloads have not been tampered with: ```typescript theme={null} import { createHmac, timingSafeEqual } from "node:crypto"; function verifyWebhookSignature( payload: string, signature: string, secret: string ): boolean { const expected = "sha256=" + createHmac("sha256", secret) .update(payload) .digest("hex"); return timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); } // In your request handler const isValid = verifyWebhookSignature( requestBody, request.headers["x-webhook-signature"], process.env.WEBHOOK_SECRET! ); if (!isValid) { return new Response("Invalid signature", { status: 401 }); } ``` ## Webhook Management API | Method | Endpoint | Description | | - | - | - | | GET | `/v1/orgs/:orgId/webhooks` | List webhooks | | POST | `/v1/orgs/:orgId/webhooks` | Create webhook | | PATCH | `/v1/orgs/:orgId/webhooks/:id` | Update webhook | | DELETE | `/v1/orgs/:orgId/webhooks/:id` | Delete webhook | | POST | `/v1/orgs/:orgId/webhooks/:id/test` | Send test event | ## Retry Behavior If your endpoint does not return a `2xx` status code, Jinba Toolbox retries the delivery: | Attempt | Delay | | - | - | | 1st retry | 1 minute | | 2nd retry | 5 minutes | | 3rd retry | 30 minutes | After 3 consecutive failures, the webhook is automatically **disabled**. You can re-enable it manually from the web console or via the API once the underlying issue is resolved. ## Best Practices * **Always verify the signature** before processing a payload to prevent tampering. * **Return a `200` status quickly** -- perform any heavy processing asynchronously after acknowledging the webhook. * **Use idempotent processing** -- webhook deliveries may arrive more than once due to retries. Use the `runId` or event timestamp to deduplicate. * **Monitor webhook health** -- re-enable disabled webhooks promptly and investigate delivery failures. * **Subscribe only to needed events** -- reduce noise by selecting only the events your integration requires. ## Related * [REST API](/en/pages/toolbox/developer/api) -- Full endpoint reference * [Security & Access Control](/en/pages/toolbox/advanced/security) -- Authentication and authorization details

Build with AI

Use with AI

Tools for AI Beta

Hello World