Execute a query builder configuration

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/query/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "queryConfig": {},
  "options": {}
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/query/execute"

payload = {
    "queryConfig": {},
    "options": {}
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({queryConfig: {}, options: {}})
};

fetch('https://api.orion.file.ai/prod/v1/query/execute', 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.orion.file.ai/prod/v1/query/execute",
  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([
    'queryConfig' => [
        
    ],
    'options' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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.orion.file.ai/prod/v1/query/execute"

	payload := strings.NewReader("{\n  \"queryConfig\": {},\n  \"options\": {}\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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.orion.file.ai/prod/v1/query/execute")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"queryConfig\": {},\n  \"options\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orion.file.ai/prod/v1/query/execute")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"queryConfig\": {},\n  \"options\": {}\n}"

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

{
  "data": [
    {}
  ],
  "headers": {},
  "executionTimeMs": 123,
  "rowCount": 123,
  "errors": [
    {}
  ]
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

POST

prod

query

execute

Execute a query builder configuration

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/query/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "queryConfig": {},
  "options": {}
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/query/execute"

payload = {
    "queryConfig": {},
    "options": {}
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({queryConfig: {}, options: {}})
};

fetch('https://api.orion.file.ai/prod/v1/query/execute', 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.orion.file.ai/prod/v1/query/execute",
  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([
    'queryConfig' => [
        
    ],
    'options' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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.orion.file.ai/prod/v1/query/execute"

	payload := strings.NewReader("{\n  \"queryConfig\": {},\n  \"options\": {}\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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.orion.file.ai/prod/v1/query/execute")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"queryConfig\": {},\n  \"options\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orion.file.ai/prod/v1/query/execute")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"queryConfig\": {},\n  \"options\": {}\n}"

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

{
  "data": [
    {}
  ],
  "headers": {},
  "executionTimeMs": 123,
  "rowCount": 123,
  "errors": [
    {}
  ]
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

Run a query builder configuration against your extracted document data and get tabular rows back. The workspace and organization are taken from the API key, so the configuration itself carries no tenancy.

Use Cases

Reporting

Pull aggregated figures across document types for dashboards and reports

Reconciliation

Join related documents (for example purchase orders and invoices) and compare fields

Data export

Select and order specific fields for downstream systems

Validation

Filter for documents that fail a business rule

Request Parameters

Request Body

Property	Type	Required	Description
queryConfig	object	Yes	The query builder configuration
options	object	No	Execution settings such as `limit` and `offset`

queryConfig

All properties are optional; combine the ones your query needs.

Property	Type	Description
documentTypes	array	Document type (file type) ids to query over
foldersContext	array	Directory ids to scope the query to
filters	array	Filter conditions applied to the selected documents
filterGroups	array	Grouped filter conditions for nested AND/OR logic
selectedFields	array	Fields to return, each with its alias
aggregations	array	Aggregations (for example count, sum, average) to compute
joins	array	Joins between document types
orderBy	array	Ordering clauses
virtualColumns	array	Computed columns derived from other fields
queryConfigs	array	Chained sub-configurations, each with an `id` and a nested `config`
directoryValidation	object	Directory-level validation configuration
headerOrder	array	Explicit ordering of the returned headers

options

Property	Type	Description
limit	number	Maximum number of rows to return
offset	number	Number of rows to skip
fieldMetadata	object	Field metadata passed through to execution
skipCache	boolean	Bypass cached results and execute the query fresh

queryConfig mirrors the query builder in the fileAI app. The most reliable way to author one is to build the query in the UI and reuse its configuration here.

Response

Field	Type	Description
data	array	Rows returned by the query
headers	object	Header metadata keyed by the selected field aliases
rowCount	number	Number of rows returned
executionTimeMs	number	Server-side execution time in milliseconds
errors	array	Validation errors, present when the query config is invalid

A 200 response can still carry errors when the query configuration is invalid. Check errors before treating data as complete.

Idempotency

Idempotency-Key is accepted for client uniformity but ignored here: the endpoint has no side effects, and a retry can legitimately return different rows, so replaying a cached response would hand back stale data. See Idempotent requests.

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

Accepted for client uniformity but IGNORED on this endpoint. It has no side effects, and a retry can legitimately return different results, so replaying a cached response would hand back stale data. Every request executes fresh: no 24h window, no replay, no Idempotent-Replayed header, and no key-reuse 422.

Body

application/json

queryConfig

object

required

Query builder configuration payload

options

object

Optional execution settings such as limit and offset

Response

Query executed successfully

data

object[]

required

Rows returned by the query

headers

object

required

Headers metadata keyed by selected field aliases

executionTimeMs

number

required

Execution time in milliseconds

rowCount

number

required

Number of rows returned

errors

object[]

Validation errors when query config is invalid

⌘I

fileAI API

Key Functions

Endpoints

Execute a query builder configuration

Use Cases

Reporting

Reconciliation

Data export

Validation

Request Parameters

Request Body

queryConfig

options

Response

Idempotency

Authorizations

Headers

Body

Response

​Use Cases

Reporting

Reconciliation

Data export

Validation

​Request Parameters

​Request Body

​queryConfig

​options

​Response

​Idempotency

Authorizations

Headers

Body

Response

Use Cases

Request Parameters

Request Body

queryConfig

options

Response

Idempotency