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

import requests

url = "https://api.getdecisional.ai/api/v1/api/v1/tool-runs"

payload = {
    "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": {}
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: {}
  })
};

fetch('https://api.getdecisional.ai/api/v1/api/v1/tool-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getdecisional.ai/api/v1/api/v1/tool-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getdecisional.ai/api/v1/api/v1/tool-runs"

	payload := strings.NewReader("{\n  \"tool\": {\n    \"type\": \"<string>\",\n    \"model\": \"<string>\",\n    \"knowledge_engine_id\": \"<string>\",\n    \"tagged_data_sources\": [\n      {\n        \"id\": \"<string>\",\n        \"page_range\": \"<string>\"\n      }\n    ],\n    \"fields\": [\n      {\n        \"field_name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"type\": \"<string>\",\n        \"options\": [\n          {}\n        ]\n      }\n    ],\n    \"include_confidence_scores\": true\n  },\n  \"stream_response\": true,\n  \"async_response\": true,\n  \"notes\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getdecisional.ai/api/v1/api/v1/tool-runs")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool\": {\n    \"type\": \"<string>\",\n    \"model\": \"<string>\",\n    \"knowledge_engine_id\": \"<string>\",\n    \"tagged_data_sources\": [\n      {\n        \"id\": \"<string>\",\n        \"page_range\": \"<string>\"\n      }\n    ],\n    \"fields\": [\n      {\n        \"field_name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"type\": \"<string>\",\n        \"options\": [\n          {}\n        ]\n      }\n    ],\n    \"include_confidence_scores\": true\n  },\n  \"stream_response\": true,\n  \"async_response\": true,\n  \"notes\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getdecisional.ai/api/v1/api/v1/tool-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tool\": {\n    \"type\": \"<string>\",\n    \"model\": \"<string>\",\n    \"knowledge_engine_id\": \"<string>\",\n    \"tagged_data_sources\": [\n      {\n        \"id\": \"<string>\",\n        \"page_range\": \"<string>\"\n      }\n    ],\n    \"fields\": [\n      {\n        \"field_name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"type\": \"<string>\",\n        \"options\": [\n          {}\n        ]\n      }\n    ],\n    \"include_confidence_scores\": true\n  },\n  \"stream_response\": true,\n  \"async_response\": true,\n  \"notes\": {}\n}"

response = http.request(request)
puts response.read_body

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

POST

api

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

import requests

url = "https://api.getdecisional.ai/api/v1/api/v1/tool-runs"

payload = {
    "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": {}
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: {}
  })
};

fetch('https://api.getdecisional.ai/api/v1/api/v1/tool-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getdecisional.ai/api/v1/api/v1/tool-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getdecisional.ai/api/v1/api/v1/tool-runs"

	payload := strings.NewReader("{\n  \"tool\": {\n    \"type\": \"<string>\",\n    \"model\": \"<string>\",\n    \"knowledge_engine_id\": \"<string>\",\n    \"tagged_data_sources\": [\n      {\n        \"id\": \"<string>\",\n        \"page_range\": \"<string>\"\n      }\n    ],\n    \"fields\": [\n      {\n        \"field_name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"type\": \"<string>\",\n        \"options\": [\n          {}\n        ]\n      }\n    ],\n    \"include_confidence_scores\": true\n  },\n  \"stream_response\": true,\n  \"async_response\": true,\n  \"notes\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getdecisional.ai/api/v1/api/v1/tool-runs")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool\": {\n    \"type\": \"<string>\",\n    \"model\": \"<string>\",\n    \"knowledge_engine_id\": \"<string>\",\n    \"tagged_data_sources\": [\n      {\n        \"id\": \"<string>\",\n        \"page_range\": \"<string>\"\n      }\n    ],\n    \"fields\": [\n      {\n        \"field_name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"type\": \"<string>\",\n        \"options\": [\n          {}\n        ]\n      }\n    ],\n    \"include_confidence_scores\": true\n  },\n  \"stream_response\": true,\n  \"async_response\": true,\n  \"notes\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getdecisional.ai/api/v1/api/v1/tool-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tool\": {\n    \"type\": \"<string>\",\n    \"model\": \"<string>\",\n    \"knowledge_engine_id\": \"<string>\",\n    \"tagged_data_sources\": [\n      {\n        \"id\": \"<string>\",\n        \"page_range\": \"<string>\"\n      }\n    ],\n    \"fields\": [\n      {\n        \"field_name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"type\": \"<string>\",\n        \"options\": [\n          {}\n        ]\n      }\n    ],\n    \"include_confidence_scores\": true\n  },\n  \"stream_response\": true,\n  \"async_response\": true,\n  \"notes\": {}\n}"

response = http.request(request)
puts response.read_body

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

object

required

Configuration for the extraction tool

Show Tool Properties

string

required

Type of tool to run. Currently supports extract_fields_from_data_sources

string

required

The AI model to use for extraction. Currently supports gemini-1.5-pro

string

required

ID of the knowledge engine containing the data sources

array

required

List of data sources to extract fields from

Show Data Source Properties

string

required

ID of the data source

string

Range of pages to analyze (e.g., “1-5”)

array

required

List of fields to extract

Show Field Properties

string

required

Name identifier for the field

string

required

Description of what the field represents

string

required

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

array

Required for single_select and multi_select types. List of possible values.

boolean

Whether to include confidence scores for each extraction (default: true)

boolean

Whether to stream the response (default: false)

boolean

Whether to process the request asynchronously (default: false)

object

Custom metadata for the tool run

Response

string

Unique identifier for the tool run

string

Status of the tool run. Possible values: queued, processing, completed, failed

integer

Unix timestamp when the tool run was created

object

The tool configuration used for this run (same as request)

object

Results of the extraction

Show Result Properties

object

Object containing all extracted fields

Show Extracted Field Format

object

For each field defined in the request

any

The extracted value

string

The type of the extracted field

number

Confidence score (0-1) for the extraction

array

For single_select and multi_select types, the available options

object

Processing metadata for the extraction

number

Processing time in milliseconds

number

Number of data sources analyzed

number

Number of fields successfully extracted

number

Average confidence score across all extractions

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

Knowledge Engines

Data Sources

Workflows

Tool Runs

Create Tool Run

Extract Fields from Data Sources

Request

Response

Example

Request Example

Response Example

​Extract Fields from Data Sources

​Request

​Response

​Example

​Request Example

​Response Example

Extract Fields from Data Sources

Request

Response

Example

Request Example

Response Example