# Create Data Source Batch Source: https://docs.getdecisional.ai/api-reference/data-sources/batch POST /api/v1/data-sources/batch Creates multiple data sources in a single request # Delete Data Sources Batch Source: https://docs.getdecisional.ai/api-reference/data-sources/batch-delete DELETE /api/v1/data-sources/batch Deletes multiple data sources in a single request # Create Data Source Source: https://docs.getdecisional.ai/api-reference/data-sources/create POST /api/v1/data-sources Creates a new data source and associates it with a knowledge engine # Delete Data Source Source: https://docs.getdecisional.ai/api-reference/data-sources/delete DELETE /api/v1/data-sources/{id} Deletes an existing data source # Get Data Source Source: https://docs.getdecisional.ai/api-reference/data-sources/get GET /api/v1/data-sources/{id} Returns a single data source by ID # Get Presigned URL for Data Source Source: https://docs.getdecisional.ai/api-reference/data-sources/presigned-url GET /api/v1/data-sources/{id}/presigned-url Returns a presigned URL for a data source # Introduction Source: https://docs.getdecisional.ai/api-reference/introduction This is an overview of the Decisional APIs Decisional is an AI Agent for Deep Financial Work. It supports processing workflows on top of collections of unstructured data i.e `data_sources` which are called as `knowledge_engines`. The Knowledge Engine API provides endpoints for creating and managing knowledge engines. All API endpoints are under the `/v1` path. In order to support deep work optimized for domains of higher complexity, accuracy and transparency, Decisional supports the following unique features: ## Features * Query answering on collections of unstructured data in multiple file formats (pdf, xlx, docx, ppt) * Citations that link back to original sources on the respective pages * Support multiple models with a RAG architecture tuned to perform better on complex documents * Proprietary ingestion that supports not just text layer parsing but also vision layer parsing through VLMs ## Authentication The Knowledge Engine, Data Sources and Workflows API uses HTTP Basic Authentication. Include an Authorization header with your API key encoded in Base64 format. API keys are provided when you register for the Decisional platform and follow the format 'dcl-\[unique-identifier]'. All API requests must include this authentication header. ## Generate your API Key * Login to [https://app.decisional.com](https://app.decisional.com) * Enter your userid and password * Go to the API Console section and "Create a New Key"

## Base URL ```bash theme={null} https://api.getdecisional.ai/api/v1 ``` ## Response Codes | Code | Description | | ---- | ------------ | | 200 | Success | | 201 | Created | | 400 | Bad Request | | 404 | Not Found | | 500 | Server Error | # Create Knowledge Engine Source: https://docs.getdecisional.ai/api-reference/knowledge-engines/create POST /api/v1/knowledge-engines Creates a new public knowledge engine # Delete Knowledge Engine Source: https://docs.getdecisional.ai/api-reference/knowledge-engines/delete DELETE /api/v1/knowledge-engines/{id} Deletes an existing knowledge engine # Get Knowledge Engine Source: https://docs.getdecisional.ai/api-reference/knowledge-engines/get GET /api/v1/knowledge-engines/{id} Returns a single knowledge engine by ID # List Knowledge Engines Source: https://docs.getdecisional.ai/api-reference/knowledge-engines/list GET /api/v1/knowledge-engines Returns a list of all public knowledge engines # List Data Sources for Knowledge Engine Source: https://docs.getdecisional.ai/api-reference/knowledge-engines/list-data-sources GET /api/v1/knowledge-engines/{id}/data-sources Returns a list of all data sources associated with a knowledge engine # Query Knowledge Engine Source: https://docs.getdecisional.ai/api-reference/knowledge-engines/query POST /api/v1/knowledge-engines/{id}/query Streams a response to a natural language query using Server-Sent Events Query a knowledge engine with a natural language question. This endpoint uses Server-Sent Events (SSE) to stream the response back to the client. ### Request Format The natural language query to ask the knowledge engine A name for this query workflow Context ID used in case of thread mode for chat based workflows Flag to enable advanced reasoning for the query The model to use for the query ### Example Request ```json theme={null} { "query": "What were the company's revenue figures for 2023?", "name": "Revenue Analysis", "advanced_reasoning": true, "model": "llama-v3-70b" } ``` ### Response Format The response is streamed using Server-Sent Events (SSE) with the following event types: * `message`: Contains intermediate response chunks as they are generated * `error`: Contains error messages if something goes wrong * `done`: Final event containing the complete response with metadata ### Example Response Stream ```javascript theme={null} // Intermediate messages event: message data: "Based on the available information, " event: message data: "the company's revenue in 2023 was " event: message data: "$1.2 billion, representing a 15% increase from 2022." // Final response with complete result event: done data: { "id": "wf_abc123xyz789", "name": "Revenue Analysis", "query": "What were the company's revenue figures for 2023?", "type": "query", "knowledge_engine_id": "kng_abc123xyz789", "status": "processed", "response": "Based on the available information, the company's revenue in 2023 was $1.2 billion, representing a 15% increase from 2022.", "citations": [ { "text": "In fiscal year 2023, total revenue reached $1.2B, up 15% YoY", "source": "Annual Report 2023", "page": 45 } ], "created_at": 1679644800 } ``` ### Notes * The streaming response allows for real-time display of the AI's response as it's being generated * The final `done` event includes the complete response along with metadata and citations * If an error occurs, the stream will emit an `error` event and close the connection * Clients should handle connection closure appropriately using the `close` event The streaming response requires a client that supports Server-Sent Events (SSE). Most modern browsers and HTTP clients support this feature. ### Response Object Unique identifier for the workflow Name of the workflow The original query that was asked Type of workflow (always "query") ID of the knowledge engine that was queried Status of the workflow ("processed" when complete) The complete response text Array of citations supporting the response The relevant text from the source Name of the source document Page number in the source document Unix timestamp when the workflow was created # Retrieve Chunks Source: https://docs.getdecisional.ai/api-reference/knowledge-engines/retrieve POST /api/v1/knowledge-engines/{id}/retrieve Returns raw retrieved chunks from a knowledge engine without streaming or workflow creation Retrieve raw chunks from a knowledge engine without creating a workflow or generating a synthesized LLM answer. ### Request Format The knowledge engine ID to search. The natural language query used to retrieve the most relevant chunks. Optional. Restrict retrieval to a single data source. Maximum chunks to return. Defaults to `5`; values above `20` are clamped to `20`. ### Response Format The original query string. The queried knowledge engine ID. Returned when a single `data_source_id` was provided in the request. Ranked chunks retrieved from the knowledge engine. The raw chunk text. The source filename, when available. The chunk identifier returned by the retrieval system. The source data source public ID for this chunk. Source page number for this chunk. Returns `-1` when not page-backed (for example, spreadsheet rows). Number of chunks returned. # Update Knowledge Engine Source: https://docs.getdecisional.ai/api-reference/knowledge-engines/update PUT /api/v1/knowledge-engines/{id} Updates an existing knowledge engine # Supported Models Source: https://docs.getdecisional.ai/api-reference/models Foundation models supported on the Decisional platform | Model | Provider | Best for | | ------------------- | ---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto` | Decisional | Automatically selects the most appropriate model based on query requirements | | `claude-4.5-sonnet` | Anthropic | Conversational tasks, summarization, and natural language generation.- Scenarios requiring balanced performance and clarity. | | `llama-v3-70b` | Meta | **Fastest** model with strong performance for high-volume queries.- Ideal for applications needing lower latency and an open-source foundation (hosted on Groq). | | `llama-4-scout` | Meta | **Efficient** processing while maintaining strong performance - Ideal for deployments where resources are limited but quality can't be compromised. | | `llama-4-maverick` | Meta | **High-performance** model that outperforms GPT-4o and Gemini 2.0 on various benchmarks - Best for complex tasks requiring advanced capabilities with its 400B total parameters (17B active). Requires more than a single GPU. | | `gemini-2.5` | Google | **Long context processing** with multimodal capabilities - Excels at handling complex reasoning tasks with a massive 1 million token context window (expanding to 2 million). Particularly strong at mathematical reasoning, scientific problem-solving, and advanced coding applications where deep reasoning is required. | | `gpt-5.4` | OpenAI | **Deep** **reasoning** for highly complex workflows or queries.- when combined with advanced\_reasoning it will deliver the most thorough analysis. | | `claude-4.6-haiku` | Anthropic | **Lightweight**, cost-effective model for simpler queries.- Good for prototyping or quick interactions where complexity is minimal. | | `gpt-4.1` | OpenAI | **Simple** tasks requiring basic language understanding.- Strong general-purpose performance | Decisional offers multiple AI models with varying capabilities and performance profiles. You can rely on the default `auto` setting or explicitly choose a model to tailor performance, speed, and cost to your requirements. ### Default * Let Decisional automatically choose the best-suited model based on your query. This is recommended if you’re unsure which model fits your use case or want a balanced approach without manually tuning. ### Warning **Combining reasoning models with advanced reasoning:** `model = "gpt-5.4"`, `advanced_reasoning = true` Higher-level models with advanced reasoning can significantly slow down response times. Use this combo only when you need the deepest analysis possible. ## Selecting a Model You can specify which model to use when making a query by including the `model` parameter in your request: **Query API Example** ```powershell theme={null} curl -X POST https://api.getdecisional.ai/api/v1/knowledge-engines/{id}/query \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "Complex analysis question?", "advanced_reasoning": true, "model": "llama-v3-70b" }' ``` **Workflow API Example** ```powershell theme={null} curl -X POST https://api.getdecisional.ai/api/v1/workflows \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "value": { "name": "Analysis Workflow", "query": "Comprehensive analysis of revenue growth over past 5 years?", "advanced_reasoning": true, "model": "gpt-5.4" } }' ``` # Create Tool Run Source: https://docs.getdecisional.ai/api-reference/tool-runs/create POST /api/v1/tool-runs Creates a new tool run to extract fields from data sources ## Extract Fields from Data Sources The Extract Fields tool allows you to automatically extract structured information from documents in your knowledge engine. This is useful for: * Pulling specific data points from contracts, invoices, or reports * Extracting consistent information across multiple documents * Converting unstructured document data into structured format The tool uses AI to identify and extract the specific fields you define, with confidence scores for each extraction. ### Request Configuration for the extraction tool Type of tool to run. Currently supports `extract_fields_from_data_sources` The AI model to use for extraction. Currently supports `gemini-1.5-pro` ID of the knowledge engine containing the data sources List of data sources to extract fields from ID of the data source Range of pages to analyze (e.g., "1-5") List of fields to extract Name identifier for the field Description of what the field represents Type of data to extract. Supported types: * `text` - Generic text * `id_alphanumeric` - Alphanumeric identifiers * `verbatim` - Exact text passages * `number` - Numeric values * `percentage` - Percentage values * `currency` - Monetary amounts * `currency_symbol` - Currency codes * `date` - Date values * `single_select` - Single selection from options * `multi_select` - Multiple selections from options * `url` - Website URLs Required for `single_select` and `multi_select` types. List of possible values. Whether to include confidence scores for each extraction (default: true) Whether to stream the response (default: false) Whether to process the request asynchronously (default: false) Custom metadata for the tool run ### Response Unique identifier for the tool run Status of the tool run. Possible values: `queued`, `processing`, `completed`, `failed` Unix timestamp when the tool run was created The tool configuration used for this run (same as request) Results of the extraction Object containing all extracted fields For each field defined in the request The extracted value The type of the extracted field Confidence score (0-1) for the extraction For `single_select` and `multi_select` types, the available options Processing metadata for the extraction Processing time in milliseconds Number of data sources analyzed Number of fields successfully extracted Average confidence score across all extractions ## Example ### Request Example ```json theme={null} { "tool": { "type": "extract_fields_from_data_sources", "model": "gemini-1.5-pro", "knowledge_engine_id": "kng_abc123def456", "tagged_data_sources": [ { "id": "dsc_abc123asdhas", "page_range": "1-5" }, { "id": "dsc_def456qwerty", "page_range": "7-9" } ], "fields": [ { "field_name": "customer_full_name", "description": "The full name of the customer as it appears on the document", "type": "text" }, { "field_name": "contract_id", "description": "The unique alphanumeric identifier of the contract", "type": "id_alphanumeric" }, { "field_name": "exact_statement", "description": "The exact statement of work as written in the document", "type": "verbatim" }, { "field_name": "quantity_ordered", "description": "The number of items ordered", "type": "number" }, { "field_name": "discount_rate", "description": "The percentage discount applied to the order", "type": "percentage" }, { "field_name": "total_amount", "description": "The total amount to be paid", "type": "currency" }, { "field_name": "currency_code", "description": "The currency symbol used in the transaction", "type": "currency_symbol" }, { "field_name": "delivery_date", "description": "The date when the items will be delivered", "type": "date" }, { "field_name": "payment_method", "description": "The method of payment selected by the customer", "type": "single_select", "options": ["Credit Card", "Wire Transfer", "ACH", "Check", "PayPal"] }, { "field_name": "applicable_taxes", "description": "All types of taxes applied to this transaction", "type": "multi_select", "options": ["State Sales Tax", "Federal Excise Tax", "VAT", "Environmental Fee", "Import Duty", "Luxury Tax"] }, { "field_name": "company_website", "description": "The URL of the company's website", "type": "url" } ] }, "stream_response": false, "async_response": true, "notes": { "custom_field": "value", "priority": "high" } } ``` ### Response Example ```json theme={null} { "id": "trun_ab7321xyw890", "status": "completed", "created_at": 1705487200, "tool": { "type": "extract_fields_from_data_sources", "model": "gemini-1.5-pro", "knowledge_engine_id": "kng_abc123def456", "tagged_data_sources": [ { "id": "dsc_abc123asdhas", "page_range": "1-5" }, { "id": "dsc_def456qwerty", "page_range": "7-9" } ], "fields": [ { "field_name": "customer_full_name", "description": "The full name of the customer as it appears on the document", "type": "text" }, { "field_name": "contract_id", "description": "The unique alphanumeric identifier of the contract", "type": "id_alphanumeric" }, { "field_name": "exact_statement", "description": "The exact statement of work as written in the document", "type": "verbatim" }, { "field_name": "quantity_ordered", "description": "The number of items ordered", "type": "number" }, { "field_name": "discount_rate", "description": "The percentage discount applied to the order", "type": "percentage" }, { "field_name": "total_amount", "description": "The total amount to be paid", "type": "currency" }, { "field_name": "currency_code", "description": "The currency symbol used in the transaction", "type": "currency_symbol" }, { "field_name": "delivery_date", "description": "The date when the items will be delivered", "type": "date" }, { "field_name": "payment_method", "description": "The method of payment selected by the customer", "type": "single_select", "options": ["Credit Card", "Wire Transfer", "ACH", "Check", "PayPal"] }, { "field_name": "applicable_taxes", "description": "All types of taxes applied to this transaction", "type": "multi_select", "options": ["State Sales Tax", "Federal Excise Tax", "VAT", "Environmental Fee", "Import Duty", "Luxury Tax"] }, { "field_name": "company_website", "description": "The URL of the company's website", "type": "url" } ], "include_confidence_scores": true, "stream_response": false, "async_response": true, "notes": { "custom_field": "value", "priority": "high" } }, "result": { "extracted_fields": { "customer_full_name": { "value": "Jonathan Michael Rodriguez", "type": "text", "confidence": 0.96 }, "contract_id": { "value": "CTR-2025-XZ793", "type": "id_alphanumeric", "confidence": 0.99 }, "exact_statement": { "value": "Client agrees to pay all invoices within 30 days of receipt and acknowledges late payments are subject to a 2.5% monthly fee.", "type": "verbatim", "confidence": 0.97 }, "quantity_ordered": { "value": 375, "type": "number", "confidence": 0.98 }, "discount_rate": { "value": 15.5, "type": "percentage", "confidence": 0.93 }, "total_amount": { "value": 15782.50, "type": "currency", "confidence": 0.99 }, "currency_code": { "value": "USD", "type": "currency_symbol", "confidence": 0.99 }, "delivery_date": { "value": "2025-04-15", "type": "date", "confidence": 0.95 }, "payment_method": { "value": "Wire Transfer", "type": "single_select", "options": ["Credit Card", "Wire Transfer", "ACH", "Check", "PayPal"], "confidence": 0.92 }, "applicable_taxes": { "value": ["State Sales Tax", "Environmental Fee", "Import Duty"], "type": "multi_select", "options": ["State Sales Tax", "Federal Excise Tax", "VAT", "Environmental Fee", "Import Duty", "Luxury Tax"], "confidence": 0.91 }, "company_website": { "value": "https://www.acmetechnologies.com", "type": "url", "confidence": 0.97 } }, "metadata": { "processing_time": 2350, "sources_analyzed": 2, "fields_extracted": 11, "average_confidence": 0.96 } } } ``` # Create Workflow Source: https://docs.getdecisional.ai/api-reference/workflows/create POST /api/v1/workflows Creates a new workflow associated with a knowledge engine ## Overview Create a new workflow to process queries against a knowledge engine. Workflows represent individual question-answer sessions that leverage your uploaded documents and data sources. ## Error Handling This endpoint can return various error responses. For comprehensive error handling information, see the [Workflows Error Handling Guide](/api-reference/workflows/error-handling). ### Common Error Scenarios ```json theme={null} { "error": "knowledge engine is not ready, current status: processing" } ``` **Resolution**: Wait for the knowledge engine to finish processing uploaded documents before creating workflows. ```json theme={null} { "error": "knowledge engine has no active data sources" } ``` **Resolution**: Upload at least one document to the knowledge engine before creating workflows. ```json theme={null} { "error": "Model unsupported-model not supported" } ``` **Resolution**: Use a supported model name or omit the field to use the default model. ```json theme={null} { "error": "Model Claude 3.5 Sonnet is not enabled" } ``` **Resolution**: Contact support to enable the model or use a different enabled model. ## Best Practices ### Pre-flight Validation Always validate the knowledge engine status before creating workflows: ```javascript theme={null} // Check knowledge engine status first const keResponse = await fetch(`/api/v1/knowledge-engines/${knowledgeEngineId}`, { headers: { 'Authorization': 'Basic ' + btoa(apiKey + ':') } }); const ke = await keResponse.json(); if (ke.status !== 'ready') { throw new Error(`Knowledge engine not ready: ${ke.status}`); } if (ke.data_source_count === 0) { throw new Error('No data sources available'); } // Now create the workflow const workflowResponse = await fetch('/api/v1/workflows', { method: 'POST', headers: { 'Authorization': 'Basic ' + btoa(apiKey + ':'), 'Content-Type': 'application/json' }, body: JSON.stringify({ type: 'query', name: 'Revenue Analysis', query: 'What was the revenue growth in Q4?', knowledge_engine_id: knowledgeEngineId }) }); ``` ### Error Handling Implement proper error handling with retry logic for transient failures: ```javascript theme={null} async function createWorkflowWithRetry(workflowData, maxRetries = 3) { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { const response = await fetch('/api/v1/workflows', { method: 'POST', headers: { 'Authorization': 'Basic ' + btoa(apiKey + ':'), 'Content-Type': 'application/json' }, body: JSON.stringify(workflowData) }); if (response.ok) { return await response.json(); } const errorData = await response.json(); // Don't retry client errors (4xx) if (response.status >= 400 && response.status < 500) { throw new Error(errorData.error); } // Retry server errors (5xx) with exponential backoff if (attempt < maxRetries) { await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000) ); continue; } throw new Error(errorData.error); } catch (error) { if (attempt === maxRetries) throw error; } } } ``` # Workflows Error Handling Source: https://docs.getdecisional.ai/api-reference/workflows/error-handling Comprehensive guide to error handling for the Workflows API This guide covers all possible error scenarios when working with the Workflows API, including HTTP status codes, error messages, causes, and resolution steps. ## Error Response Format All workflow API errors follow a consistent JSON format: ```json theme={null} { "error": "Error message describing what went wrong" } ``` For streaming endpoints (like the query endpoint), errors are sent as Server-Sent Events: ``` event: error data: {"error": "Error message describing what went wrong"} ``` ## Authentication & Authorization Errors ### HTTP 401 - Unauthorized **Missing API Key** ```json theme={null} { "error": "Unauthorized" } ``` * **Cause**: No Authorization header provided or invalid API key format * **Resolution**: Include a valid API key in the Authorization header using HTTP Basic Authentication **Invalid API Key** ```json theme={null} { "error": "Unauthorized" } ``` * **Cause**: API key is invalid or has been revoked * **Resolution**: Verify your API key is correct and active in your Decisional account settings ## Validation Errors ### HTTP 400 - Bad Request **Invalid Knowledge Engine ID** ```json theme={null} { "error": "Invalid knowledge engine ID" } ``` * **Cause**: The knowledge engine ID format is invalid or doesn't match expected pattern * **Resolution**: Ensure the knowledge engine ID follows the format `ke_[alphanumeric]` and exists in your account **Missing Required Fields** ```json theme={null} { "error": "Key: 'WorkflowRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag" } ``` * **Cause**: Required fields like `name`, `query`, `type`, or `knowledge_engine_id` are missing * **Resolution**: Include all required fields in your request body **Invalid Model** ```json theme={null} { "error": "Model unsupported-model not supported" } ``` * **Cause**: The specified model name is not supported by the platform * **Resolution**: Use a supported model name or omit the field to use the default model **Model Not Enabled** ```json theme={null} { "error": "Model Claude 3.5 Sonnet is not enabled" } ``` * **Cause**: The specified model exists but is not enabled for your account * **Resolution**: Contact support to enable the model or use a different enabled model **Invalid JSON** ```json theme={null} { "error": "invalid character '}' looking for beginning of object key string" } ``` * **Cause**: Request body contains malformed JSON * **Resolution**: Validate your JSON syntax and ensure proper formatting ## Knowledge Engine State Errors ### HTTP 400 - Bad Request **Knowledge Engine Not Ready** ```json theme={null} { "error": "knowledge engine is not ready, current status: processing" } ``` * **Cause**: Knowledge engine is still processing uploaded documents and not ready for queries * **Resolution**: Wait for the knowledge engine status to become "ready" before creating workflows * **Check Status**: Use the GET `/api/v1/knowledge-engines/{id}` endpoint to monitor status **No Active Data Sources** ```json theme={null} { "error": "knowledge engine has no active data sources" } ``` * **Cause**: Knowledge engine exists but has no uploaded documents or all data sources have been deleted * **Resolution**: Upload at least one document to the knowledge engine before creating workflows **Knowledge Engine Not Found** ```json theme={null} { "error": "record not found" } ``` * **Cause**: Knowledge engine with the specified ID doesn't exist or you don't have access to it * **Resolution**: Verify the knowledge engine ID and ensure you have proper access permissions ## Processing Errors ### HTTP 500 - Internal Server Error **RAG Service Failure** ```json theme={null} { "error": "Failed to process query: connection timeout" } ``` * **Cause**: Internal AI processing service is unavailable or experiencing issues * **Resolution**: Retry the request after a few moments. If the issue persists, contact support **Database Transaction Error** ```json theme={null} { "error": "Failed to create workflow: database connection lost" } ``` * **Cause**: Database connectivity issues during workflow creation * **Resolution**: Retry the request. If the issue persists, contact support **Document Retrieval Error** ```json theme={null} { "error": "Failed to retrieve documents: vector database unavailable" } ``` * **Cause**: Vector database service is temporarily unavailable * **Resolution**: Retry the request after a few moments ## Streaming Query Errors The `/api/v1/knowledge-engines/{id}/query` endpoint uses Server-Sent Events and can return errors during streaming: **Connection Errors** ``` event: error data: {"error": "knowledge engine is not ready, current status: processing"} ``` **Processing Errors** ``` event: error data: {"error": "Failed to process query: model service unavailable"} ``` **Client Disconnection** * **Cause**: Client disconnects before query completion * **Resolution**: Ensure stable network connection and implement proper reconnection logic ## Error Handling Best Practices ### 1. Implement Retry Logic For transient errors (5xx status codes), implement exponential backoff retry logic: ```javascript theme={null} async function createWorkflowWithRetry(workflowData, maxRetries = 3) { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { const response = await fetch('/api/v1/workflows', { method: 'POST', headers: { 'Authorization': 'Basic ' + btoa(apiKey + ':'), 'Content-Type': 'application/json' }, body: JSON.stringify(workflowData) }); if (response.ok) { return await response.json(); } if (response.status < 500) { // Client error, don't retry throw new Error(await response.text()); } // Server error, retry with backoff if (attempt < maxRetries) { await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000)); } } catch (error) { if (attempt === maxRetries) throw error; } } } ``` ### 2. Validate Knowledge Engine Status Always check knowledge engine status before creating workflows: ```javascript theme={null} async function ensureKnowledgeEngineReady(knowledgeEngineId) { const response = await fetch(`/api/v1/knowledge-engines/${knowledgeEngineId}`, { headers: { 'Authorization': 'Basic ' + btoa(apiKey + ':') } }); const ke = await response.json(); if (ke.status !== 'ready') { throw new Error(`Knowledge engine not ready. Current status: ${ke.status}`); } if (ke.data_source_count === 0) { throw new Error('Knowledge engine has no data sources'); } return ke; } ``` ### 3. Handle Streaming Errors For the query endpoint, implement proper error handling for Server-Sent Events: ```javascript theme={null} function queryKnowledgeEngine(knowledgeEngineId, query) { return new Promise((resolve, reject) => { const eventSource = new EventSource(`/api/v1/knowledge-engines/${knowledgeEngineId}/query`); eventSource.addEventListener('error', (event) => { const errorData = JSON.parse(event.data); eventSource.close(); reject(new Error(errorData.error)); }); eventSource.addEventListener('done', (event) => { const result = JSON.parse(event.data); eventSource.close(); resolve(result); }); eventSource.onerror = (error) => { eventSource.close(); reject(new Error('Connection error during streaming')); }; }); } ``` ## Common Resolution Steps ### Check Knowledge Engine Status 1. Use GET `/api/v1/knowledge-engines/{id}` to check status 2. Ensure status is "ready" before creating workflows 3. Verify `data_source_count > 0` ### Verify API Authentication 1. Check API key format: should be `dcl-[unique-identifier]` 2. Ensure proper Base64 encoding in Authorization header 3. Verify API key is active in your account settings ### Monitor Rate Limits While not explicitly documented in error responses, implement reasonable request spacing to avoid potential rate limiting. ### Contact Support For persistent 5xx errors or unexpected behavior, contact support with: * Request ID (if available in response headers) * Timestamp of the error * Complete error message * Steps to reproduce the issue # Airtable Integration Source: https://docs.getdecisional.ai/welcome/airtable-integration All you need to know about connecting your Magic Table to Airtable ## Quick Overview `magic_tables` can be synced with a tables of a base in [Airtable](https://airtable.com/appFxSjuUjxzkgTOY?). This allows you to use Decisional to upload sources and generate a `magic_table` which can then be synced with a corresponding table in airtable. Here is how you can sync your `magic_table` to a table in Airtable. Open the `knowledge_engine` that holds the `magic_table` that you would like to have synced, open this the the workspace. Click on the in the top right of the `magic_table` you will find the option to "Manage Columns" click on this and then select the "Connectors" tab. This will allow you to choose an option to fill in your Airtable personal access token and click on the "Connect to Airtable" button (you can create the token [here](https://airtable.com/create/tokens/new) in Airtable; you need to remember to provide the right scope and access to tables) Now you must choose the appropriate Airtable "Base" and "Table" from the drop downs. Once you have selected those, map each column in the `magic_table` to the column in the Airtable "Table". After you are donw with the mappings click on the "Update Mappings Button" Column Mappings must have the same type on Decisional as it is in Airtable or it will lead an inconsistent column mapping. Additionally, linked records type of column mappings need to be configured to the right linked record table. These are populated as single select fields and are updated every 15 mins. Now that the Airtable columns, table and base is mapped, you can click on the "Sync Airtable" button found on the bottom right corner of the `magic_table` ## State Visibility of the Cell Values During the syncing process, each cell will start showing a line on the right hand side of each cell. As the the syncing takes place, each cell will be going through the following states: * GREY - the cell value is mapped but not picked up for processing yet * YELLOW - the cell value is mapped and has been picked up for processing * GREEN - the cell value is synced to the corresponding cell value in Airtable # Setup a Knowledge Engine Source: https://docs.getdecisional.ai/welcome/first-knowledge-engine Describes how to create a knowledge engine and start using it. First, identify the goal of your workflow that you need to do. Identify sources that would be helpful to assist in that task and then gather them. Once you have atleast one source you can get started by using Decisional. / ## Login to the app Visit [https://app.decisional.com/sign-in](https://app.decisional.com/sign-in) to login ## images/login.gif

Select the Create a Knowledge Engine Button On clicking Create a Knowledge Engine button, you will be taken to an empty knowledge engine. images/create_new_knowledge_engine.gif

## Adding Sources Click on the "Upload source file" button to get started and add the sources you need. You can always add more sources later. You will see an overlay that shows you the different types of sources supported. Once you upload the sources and hit the continue button, you will now see all the sources you uploaded on the left hand side of the screen on the source explorer. The status indicator will show you the progress in analysing the source that will display the following states: * Document uploaded * Processing initiated * Text Layer Analysis * Vision Layer Analysis Decisional analyzes not just the text layer of documents but also the vision layer, allowing it to understand complex charts, diagrams and other visual information images/source_visbility.gif

Learn about the various types of sources that are supported on Decisional Apart from uploading sources manually using the Decisional web app you can also use our APIs to create and upload sources to a Knowledge Engine. Read our [API Reference](https://docs.getdecisional.ai/api-reference/introduction) here to learn how to do that. ## Create AI Workups Once all the sources are processed, you are now ready to start using the `knowledge_engine` to create or edit AI Workups (Magic Tables & Memos). Every knowledge engine by default has a Magic Table called `Default Magic Table` and a memo called as the `Scratchpad` . `The Default Magic Table` is a special kind of Magic Table that shows each source as a primary key (more information on this in Magic Tables section). The `Scratchpad` is meant to capture notes for your reference. Learn more about Memos Learn more about Magic Tables # Welcome Source: https://docs.getdecisional.ai/welcome/introduction All you need to know about Decisional and its core capabilities # Overview Decisional is an AI Agent for financial work that is grounded on your data sources. Decisional is designed for serious knowledge work by emphasizing features that make collaborating with AI more **transparent**, **controllable** and **accurate**. ## How it works Decisional helps you generate documents (memos) or tables (magic tables) by using data sources you provide. This can help you speed up all kinds of knowledge work but is particularly useful for: * **Research** on data you provide to it (supported file types include web, pdf, docx, ppt, xlx) that is not limited by any number of sources * **Data Extraction** into an AI spreadsheet called a **Magic Table** in ANY format and schema * **Writing** narrative driven rich formatted documents called **Memos** which are focused on information you specify Decisional lets you specify sources you deem trustworthy, using it to power content generated within the application with reduced hallucinations. ## Getting Started You can make use of Decisional through `knowledge_engines`. Each `knowledge_engine` is a collection of `data_sources` that you provide. Every answer generated by Decisional in the knowledge engine is grounded on the `data_sources` provided to the `knowledge_engine` along with `citations` that link back to the original `data_source` In order to create a `knowledge_engine` you need to login to the Decisional web app 1. Login or Sign Up by visiting [https://app.decisional.com/sign-in](https://app.decisional.com/sign-in) 2. Login to go to [https://app.decisional.com/knowledge-engines](https://app.decisional.com/knowledge-engines) Learn more about Knowledge Engines and what they are used for You can also add new sources through the upload `data_sources` API in the API reference # Knowledge Engines Source: https://docs.getdecisional.ai/welcome/knowledge-engines The Knowledge Engine is the core entity in Decisional that helps you use AI to understand, process and analyze unstructured sources. images/image-Photoroom.png

This diagram represents how you can take scattered information and sources and convert them into AI embedded outputs called `ai_workups` using the `knowledge_engine` Each `knowledge_engine` is **grounded** in the sources you provide. Grounding is a process that ensures AI focuses specifically on your provided data rather than relying on its pre-existing training knowledge (which includes information from the internet and other sources). While large language models like ChatGPT depend on their original training data, Decisional combines multiple AI models to summarize and understand your specific sources. This approach enhances the AI model's capabilities while significantly reducing hallucinations. This grounding results in hallucination reduction, increased accuracy and trustworthiness This allows `knowledge_engines` to gain some key capabilities: * **Near Infinite Context:** The `knowledge_engine` can hold as many sources as you require (we can hold tens of thousands of sources within a knowledge engine) and perform up to the same level of accuracy with minimal degredation in being able to fetch the right context * **Deep Citations:** Each answer generated by the `knowledge_engine` can be linked back to one of the original sources you have provided through `citations` . Decisional even highlights the relevant piece of information so that you can check facts for yourself. * **Superior Accuracy**: Decisional is able to tailor the models to perform better and be more accurate by making customisations for fine tuning AI models to perform better on Financial Services use cases. Decisional performs up to 4X the accuracy of base foundation models. Detailed blog about this [here](https://www.neuralmarkets.decisional.com/p/ragnarok-how-ai-agents-are-transforming). ## Near Infinite Context Since Decisional is pre-processing and analysing when you upload your sources, it has already learned from the knowledge you have provided. Additionally, Decisional uses vision models to understand logos, charts and images so that when you run AI workloads we can find the relevant context and use it appropriately. images/upload_experience_2.gif

## Transparent Citations Every finding or information presented on Decisional is tied back to the original source through citations as illustrated below. This allows you to have an audit trail that substantiates facts and metrics.

## Superior Accuracy Decisional measures accuracy on a popular benchmark called [financebench](https://github.com/patronus-ai/financebench) and delivers industry leading accuracy. Finance bench is an open source benchmark for measuring performance of AI systems of financial queries like: * *Given Company D’s recent expansion into Europe, what impact has this had on its revenue growth?* * *How has Company E managed its debt levels relative to competitors in the same sector?* * *What are the key factors contributing to Company F’s higher-than-average research and development expenses?* # images/measured_on_financebench-20250318T234957.png

images/measured_on_financebench-20250318T234957.png

AI Workups The `knowledge_engine` uses `sources` that you provide to generate AI embedded documents called `ai_workups` An `ai_workup` is a type of document generated on the Decisional app that has an AI Agent embedded into it trained on the sources you provide that helps you write, find insights, generate tables, etc Decisional allows you to produce two types of AI Workups * Magic Tables * [Memos](https://docs.getdecisional.ai/welcome/memos) A `magic_table` is an AI powered spreadsheet which can generate cells based on all the sources you have provided to the knowledge engine. This is suited for more numerical workflows like compiling a table or quickly finding some information to screen a data room or a set of documents. A `memo` is a long form document that can be used to write narrative driven research notes, thesis documents or reports typically suited for more qualitative work. # The Knowledge Engine Interface When you view a `knowledge_engine` there are three parts of the interface that you can see: * Source Explorer * Workspace * Decisional Assistant ## Source Explorer The source explorer is visible on the left hand side of the `knowledge_engine` and titled as **Sources**. This lists all the the sources and the AI workups in the `knowledge_engine` including the ones you provide i.e documents, files or links. You can also add new sources by clicking on the "+" button or clicking on the "Upload more" CTA. The source explorer has a search bar that you can use to search throught all the sources and AI workups. Additionally clicking on one of the AI workups will change the editor experience in the Workspace. You can collapse or uncollapse the source explorer by clicking on the collapse / uncollapse button or using the following command - ### images/sources_2.gif

Source Explorer - Viewer Along with listing the `sources` and `ai_workups` , the source explorer can also open up PDFs in the source explorer panel. This can be then used to navigate through a document or seach through it. If you need to view the whole document you can click on the "view" button or click on download from here to download the file to your computer. Source Viewer Gi

## Workspace The workspace allows you to create and edit `ai_workups` like a `memo` or a `magic_table` . You can use the workspace to switch between different `ai_workups` through the workspace selector dropdown that shows you the current `ai_workups` that is being viewed along with an icon that indicates that type of workup it is. Add A New Memo Block Gi

Create your first knowledge engine and add a source to it # Magic Tables Source: https://docs.getdecisional.ai/welcome/magic-tables Everything you need to know about Magic Tables Magic Tables are a kind of AI workup in Decisional `knowledge_engines`. You can use Magic Tables to generate *any kind of table* from the underlying sources in the `knowledge_engine`. Every cell in the Magic Table has its own AI Agent that is used to read sources and generate cell values in a specific format defined. # Types of Magic Tables There are two kinds of Magic Tables depending on what the **primary column / key** in the table is. For a default table the primary key / column is a source. For a custom table the primary key / column is any value that you provide it. The **primary column / key** is the first column in the table from the left. It is a column of special importance since it, along with the column headers allow define the table structure ## Default Magic Table In the default magic table the primary column / key is composed of the sources added to the `knowledge_engine` Screnshot Pn

## Custom Magic Table In a custom magic table, the primary column / key is a text value that is added by clicking on the + add row button on the bottom of the table. In order to add a row click on the Add new row and hit enter after typing it out. # Screnshot 2 Pn

Adding or configuring a Column Once you have decided what kind of table you want to generate (default or custom), you can use AI to generate cell values by using the `Add new column` button found on the top right of the table. Clicking on this opens up a form where you can modify the configurations of the column. Screnshot 3 Pn

## Column types You can choose from options `LLM` or `Metadata` that allow you to specify what kind of column type you want to generate. ## AI Prompt An AI prompt is the specific instruction you provide to guide the AI agents responsible for generating content in each cell of your Magic Table. Think of it as the question or directive that tells the AI exactly what information to extract or analyze from your knowledge sources. An effective AI prompt should be: * **Clear and specific**: "What was the annual revenue for this company in fiscal year 2023?" is better than "Tell me about money." * **Contextual**: The prompt should acknowledge that the AI needs to find information related to the primary key. * **Format-aware**: Consider the output type you've selected (text, currency, percentage, etc.) when writing your prompt. When you create a column in a Magic Table, the AI prompt serves as the blueprint for what should appear in every cell of that column. The AI will: 1. Consider the primary key (either a source document or your custom row value) 2. Apply your specific prompt to that context 3. Search through relevant information in the Knowledge Engine 4. Generate an appropriate response in the format you've specified ## Output types When creating a new column you can choose from a list of column types. This allows you to control the format in which AI is outputting values. For eg. `Text` is a general purpose output type where you will get the output in a text format. `Currency` will output values in a particular currency. A general-purpose field that accepts any alphanumeric characters, spaces, and special symbols. Ideal for names, descriptions, and other textual information. A field that preserves exact formatting, spacing, and special characters as entered. Perfect for quotes or when searching for exact text in the underlying sources. A unique identifier field that only accepts letters and numbers without spaces. Commonly used for reference codes, product IDs, or database keys. A field that accepts only numerical values (integers or decimals). Suitable for quantities, measurements, and mathematical calculations. A numerical field that represents a proportion out of 100. Displayed with a % symbol and often used for rates, discounts, or statistical values. A numerical field formatted to display monetary values with appropriate decimals. Automatically applies your system's default currency symbol. A specialized currency field that allows selection of different currency symbols (€, \$, £, ¥, etc.) alongside the numerical value. A field that captures calendar dates in a standardized format. A field that allows the AI to choose exactly one option from a predefined list of values. Similar to radio buttons or dropdown menus. A field that allows the AI to choose multiple options from a predefined list of values. Similar to checkboxes or multi-select dropdowns. A field designed specifically for web addresses. Includes validation to ensure proper URL format and may render as clickable links. # Cell states Once you add a column to a magic table, you will start to see values being generated. Initially, each cell is in the `queued` state and then progresses into the `generating` state followed by the terminal state of `failed`, `not found` or alternatively, the cell value is loaded into the cell. Here is a bried description on what each of these states mean: * `queued` means that the AI Agent is yet to pick this up for processing * `generating` means that an AI Agent has begun to process the cell value * `failed` means that an error was encountered and the Agent was unable to generate the answer * `not found` indicates that the AI Agent completed its task but was unable to find a relevant answer and decided to flag that the value was not found. # Cell Values Once the AI Agent has generated an answer, the value will be visible on hovering over the cell with your mouse. There are multiple sections that can be found within the cell value hover. * `Cell Value `- this is visible at the top * `Context` - this is a trace that captures the reasoning or thinking behind how the cell value was generated Screnshot 4 Pn

# Memos Source: https://docs.getdecisional.ai/welcome/memos All you need to know about Decisional AI Memos Memos are a kind of AI workup (AI embedded document) produced within the Decisional `knowledge_engine`. Whenever you produce a `memo` you can use AI and non AI content to produce documents. The `memo` is text editor where you can collaborate with an AI Agent that is trained on all the sources you have provided. ## The Scratchpad Each `knowledge_engine` by default has two AI Workups - a `memo` called as a **Scratchpad** and a `magic_table` called the **Default Magic Table**. These cannot be deleted and exist inside each `knowledge_engine` . The scatchpad is meant to be a temporary note taking tool or a sandbox for you to play around with. In case you want to save a note you can create a `Memo` ## Blocks The memo is composed of a series of blocks. You can add a new block by clicking on the (+) button or simply typing enter when you are on an existing block. images/add_a_new_memo_block.gif

## Using Commands and AI When your cursor is on a new block, you can type `/` to bring up a list of commands that are supported by Decisional to write edits into the Memo. Currently, typing `/` will bring up the AI prompt box. You can enter a question or ask AI to write an answer based on all the information available in the sources of the `knowledge_engine` ### The Prompt Box images/image2.png

The prompt box allows you to type in the prompt that you would like AI to generate but also has the following capabilities in order to allow you to control the output. It has the following capabilities from left to right: * **Block Picker** (drop down) - Allows you to control the kind of output you would require from AI. * **Attachments** (upload) - Allows you at attach context that will be used in order to generate an answer. * **Tagging** `@` - Typing "@" within the prompt box will allow you to choose specific files that you want to use while generating the output in order to focus the attention of AI * **Model Picker** (drop down) - Allows you to choose from a list of [supported AI models](https://docs.getdecisional.ai/api-reference/models) that will be used to power the output. By default this is set to `Auto` and Decisional will decide for you which model is best used to serve your answer. * \*\*Advanced Reasoning \*\*(toggle) - Enables deep reasoning so that the AI will take some time to think about the possible answers and come up with relevant summary. Advanced Reasoning is best used for more complex queries which involve multi-step thinking. For example "Fetch me the latest revenue for company X" would not require advanced reasoning whereas "Compare the revenues of all the companies similar to X" would involve multi step thinking and reasoning. ## Simple Query Just click on the `memo` , start editing a block and type `/` to fetch AI commands. Enter your prompt to get content generated in your memo. You can also choose the model used to generate the answer to avoid switching between multiple models. images/normal_memoblock_gif.gif

The model picker allows you to choose which model you would want to opt for during the time of inference. Choosing "Auto" will allow Decisional to decide the best model automatically without any intervention from your side. ## Advanced Query When you want a more comprehensive answer enable the `advanced` toggle that will give the AI more time to think and come up with a comprehensive answer using charts and figures. images/agent_block_generation.gif

When you choose to enable the advanced toggle - the query is taken up by an AI Agent that plans and executes a research plan and task while dynamically understanding information and reasoning. When it performs reasoning and understanding of information it may chain a multiple combination of models from Anthropic, OpenAI, Google, etc in order to drive the best performance. As such it is not possible to pick the model that is being used for an advanced query and it is automatically done through the Agent. # Supported Sources Source: https://docs.getdecisional.ai/welcome/supported-sources Covers the list of sources that are supported on Decisional. # Sources In order to use a Decisional Knowledge engine you need to provide it sources on which it can be grounded on. This process of `grounding` ensures that you do not get any hallucinations when we generate an AI workup. To learn more about creating a knowledge engine, visit the section [Setup your first knowledge engine](https://docs.getdecisional.ai/welcome/first-knowledge-engine). The following table outlines various information source types and indicates whether decisional knowledge engines can effectively support them: ### Supported Source Table | Source | Extension | Status | Info | | ------- | --------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | File | PDF | Supported | | | File | docx | Supported | `docx` will be automatically converted to PDF formats in order to support vision analysis. | | File | doc | Supported | `doc` will be automatically converted to PDF formats in order to support vision analysis. | | File | xls | Partially Supported | Single worksheet files supported where the the header rows and header columns are in the first row and first column of the spreadsheet respectively | | File | xlsx | Partially Supported | Single worksheet files supported where the the header rows and header columns are in the first row and first column of the spreadsheet respectively | | File | csv | Partially Supported | Single worksheet files supported where the the header rows and header columns are in the first row and first column of the spreadsheet respectively | | File | text | Supported | `txt` will be automatically converted to PDF formats in order to support vision analysis. | | File | ppt | Supported | `ppt` will be automatically converted to PDF formats in order to support vision analysis. | | File | pptx | Supported | `pptx` will be automatically converted to PDF formats in order to support vision analysis. | | Email | | Supported | Emails forwarded to the knowledge engine are uploaded with the body of the email along with attachments as a PDF to support vision analysis. To learn how to upload - click on upload sources and choose the "Upload through emails" option | | Website | | Coming Soon | | ### Sample Spreadsheet supported File formats like `xls` , `xlsx`, `csv` can be supported in when the spreadsheet has a certain structure, i.e header rows and header columns are the same as the first row & column. Sample spreadsheet that is supported on Decisional can be seen [here](https://docs.google.com/spreadsheets/d/1NGnEhR37FP70fCySkgHzmiha1pTzCH1gfvfieDp91b4/edit?gid=0#gid=0). Screenshot2025 04 12at13 14 12 Pn

# Templates Source: https://docs.getdecisional.ai/welcome/templates Use templates in Decisional to save time and automate repeatable workflows. Decisional allows you to create [memos](https://docs.getdecisional.ai/welcome/memos) and [magic tables](https://docs.getdecisional.ai/welcome/magic-tables) using unstructured data connected to a knowledge engine called sources. You can use AI to generate cell values in a magic table or blocks in a memo manually or by using AI. You can visit the templates section by going to `Templates` on the left navigation bar. Screenshot2025 04 15at11 26 26 Pn

# Memo Templates A memo template is useful when you have an outline or a format of the document you need. You can create and save this in a template that can be re-used inside any [knowledge engine](https://docs.getdecisional.ai/welcome/knowledge-engines). ## Creating a memo template Steps to follow for **creating a Memo Template:** 1. Visit [https://app.decisional.com/templates](https://app.decisional.com/templates) or use `Templates` in the left navigation on the home page 2. Choose the Build from Scratch option 3. Select Memo 4. Name your template and choose the `Add Prompt` option 5. Enter a prompt that covers the format, sections and how you would like the memo template to be generated 6. Select Preview Result and wait for the outline of the memo template ### Naming the template ### Screenshot2025 04 15at10 58 21 Pn

### Adding your Prompt ### Screenshot2025 04 15at11 01 35 Pn

### Preview & save the memo outline Screenshot2025 04 15at11 03 35 Pn

## Generating a memo from a memo template 1. Steps to follow for **generating** **a memo from a template:** 2. Visit the knowledge engine that has the sources on which you want to run the template 3. Choose Create New on the top right corner 4. Choose Memo and select the template from the drop down ### Choose the template Screenshot2025 04 15at11 05 25 Pn

### Generate the memo While the memo is being generated the outline will show up on screen. It will take a few minutes so you can view the progress as the blocks get loaded. Screenshot2025 04 15at11 16 04 Pn