Create Tool Run

Creates a new tool run to extract fields from data sources

POST /api/v1/tool-runs

Create Tool Run

cURL

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

200

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

Show Tool Properties

type · string · required

Type of tool to run. Currently supports extract_fields_from_data_sources

model · string · required

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

knowledge_engine_id · string · required

ID of the knowledge engine containing the data sources

tagged_data_sources · array · required

List of data sources to extract fields from

Show Data Source Properties

id · string · required

ID of the data source

page_range · string

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

fields · array · required

List of fields to extract

Show Field Properties

field_name · string · required

Name identifier for the field

description · string · required

Description of what the field represents

type · 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

options · array

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

include_confidence_scores · boolean

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

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

Show Result Properties

extracted_fields · object

Object containing all extracted fields

Show Extracted Field Format

[field_name] · object

For each field defined in the request

value · any

The extracted value

type · string

The type of the extracted field

confidence · number

Confidence score (0-1) for the extraction

options · array

For single_select and multi_select types, the available options

metadata · object

Processing metadata for the extraction

processing_time · number

Processing time in milliseconds

sources_analyzed · number

Number of data sources analyzed

fields_extracted · number

Number of fields successfully extracted

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