POST
/
api
/
v1
/
tool-runs
Create Tool Run
curl --request POST \
  --url https://api.getdecisional.ai/api/v1/api/v1/tool-runs \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "tool": {
    "type": "<string>",
    "model": "<string>",
    "knowledge_engine_id": "<string>",
    "tagged_data_sources": [
      {
        "id": "<string>",
        "page_range": "<string>"
      }
    ],
    "fields": [
      {
        "field_name": "<string>",
        "description": "<string>",
        "type": "<string>",
        "options": [
          {}
        ]
      }
    ],
    "include_confidence_scores": true
  },
  "stream_response": true,
  "async_response": true,
  "notes": {}
}'
{
  "id": "<string>",
  "status": "<string>",
  "created_at": 123,
  "tool": {},
  "result": {
    "extracted_fields": {
      "[field_name]": {
        "value": "<any>",
        "type": "<string>",
        "confidence": 123,
        "options": [
          {}
        ]
      }
    },
    "metadata": {
      "processing_time": 123,
      "sources_analyzed": 123,
      "fields_extracted": 123,
      "average_confidence": 123
    }
  }
}

​
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

​
tool
object
required
Configuration for the extraction tool
​
stream_response
boolean
Whether to stream the response (default: false)
​
async_response
boolean
Whether to process the request asynchronously (default: false)
​
notes
object
Custom metadata for the tool run

​
Response

​
id
string
Unique identifier for the tool run
​
status
string
Status of the tool run. Possible values: queued, processing, completed, failed
​
created_at
integer
Unix timestamp when the tool run was created
​
tool
object
The tool configuration used for this run (same as request)
​
result
object
Results of the extraction

​
Example

​
Request Example

{
  "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

{
  "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
    }
  }
}