Query Operations#

Execute queries across tables using full-text search, vector similarity search, or hybrid approaches combining both with Reciprocal Rank Fusion (RRF).

Query Types#

Full-Text Search#

Uses Antfly query syntax for powerful text searching:

Field-specific queries: body:computer
Boolean operators: AND, OR, NOT
Range queries: year:>2020
Phrase queries: "exact phrase"

Semantic Search#

Natural language queries using vector similarity:

Searches across specified embedding indexes
Returns semantically similar documents
Supports multiple embedding models

Hybrid Search (RRF)#

Combines full-text and semantic search using Reciprocal Rank Fusion:

{
  "full_text_search": {"query": "body:computer"},
  "semantic_search": "artificial intelligence",
  "indexes": ["title_body_nomic"]
}

Filtering and Exclusion#

Refine results with powerful filtering:

Filter Prefix#

Only return documents whose keys start with a specific string:

{"filter_prefix": "user:"}

Returns only keys like "user:123", "user:456"

Filter Query#

Apply an Antfly query as an AND condition:

{"filter_query": {"query": "+category:technology +year:>2020"}}

Documents must match both the main query and filter query.

Exclusion Query#

Exclude documents matching an Antfly query (NOT condition):

{"exclusion_query": {"query": "category:deprecated OR status:archived"}}

Performance Note: All filters are applied before scoring and ranking, improving query performance.

RAG (Retrieval-Augmented Generation)#

Execute queries and generate summaries using LLMs:

Supports multiple retrieval queries
Streams results as Server-Sent Events (SSE)
Returns markdown summaries with inline citations
Combines results from multiple tables

Retrieval Agent#

Intelligent query routing with automatic query generation:

Classifies queries as "question" or "search"
Generates optimal search queries across tables
Returns generated responses (for questions) or document IDs (for searches)
Streams classification, keywords, queries, and results

Improving Search Relevance#

Antfly provides several techniques to improve search result quality:

1. Hybrid Search (Combine Full-Text + Semantic)#

Use both full_text_search and semantic_search together. Results are merged using Reciprocal Rank Fusion (RRF) to balance keyword matching and semantic similarity.

2. Reranking#

Apply a cross-encoder model to re-score results based on query-document relevance. Rerankers are more accurate than embedding models but slower, so use them on already-filtered results (e.g., top 50-100).

{
  "semantic_search": "gaming laptops",
  "limit": 10,
  "reranker": {
    "provider": "antfly",
    "model": "mixedbread-ai/mxbai-rerank-base-v1",
    "field": "description",
    "candidate_count": 100
  }
}

3. Result Pruning#

Filter out low-quality results by detecting score gaps or setting minimum thresholds:

{
  "semantic_search": "machine learning",
  "pruner": {
    "min_score_ratio": 0.5,
    "max_score_gap_percent": 30.0
  }
}

min_score_ratio: Keep only results scoring at least X% of the top result
max_score_gap_percent: Stop when a consecutive score gap exceeds X% of the total score range

4. Merge Strategies#

Choose how full-text and semantic results are combined:

rrf (default): Reciprocal Rank Fusion - balanced, works well in most cases
rsf: Relative Score Fusion - normalizes and weights scores differently

5. Query Filtering#

Use filter_query and filter_prefix to pre-filter before scoring, improving both performance and relevance by removing irrelevant documents early.

Best Practice: Combine techniques for optimal results:

Start with hybrid search (full-text + semantic)
Apply filters to narrow the domain
Use reranker on top results
Apply pruner to remove outliers

Common questions about this section

What's the difference between full-text and semantic search?
How does hybrid search with RRF work?
How do I improve search relevance?
What's the difference between RAG and Retrieval Agent?

Perform a global query#

POST/query

Executes a query across all relevant tables and shards based on the query content.

Query Examples#

Full-text search:

{
  "table": "wikipedia",
  "full_text_search": {"query": "body:computer"},
  "limit": 10
}

Semantic search:

{
  "table": "articles",
  "semantic_search": "artificial intelligence applications",
  "indexes": ["title_body_embedding"],
  "limit": 20
}

Hybrid search (RRF):

{
  "table": "products",
  "full_text_search": {"query": "laptop gaming"},
  "semantic_search": "high performance gaming computers",
  "indexes": ["product_embedding"],
  "filter_query": {"query": "+price:<2000 +in_stock:true"},
  "fields": ["name", "price", "description"],
  "limit": 15
}

With filtering:

{
  "table": "users",
  "filter_prefix": "tenant:acme:",
  "full_text_search": {"query": "active:true"},
  "exclusion_query": {"query": "status:deleted"},
  "limit": 50
}

NDJSON format: For bulk queries, send multiple queries as NDJSON with Content-Type: application/x-ndjson. Each line must end with \n:

{"table":"wiki","semantic_search":"AI","indexes":["emb"],"limit":5}
{"table":"docs","full_text_search":{"query":"tutorial"},"limit":10}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "table": "wikipedia",
    "query": {
        "bool": {
            "must": [
                {
                    "match": {
                        "field": "body",
                        "text": "computer"
                    }
                }
            ],
            "filter": [
                {
                    "term": {
                        "path": "/tenant",
                        "value": "acme"
                    }
                }
            ],
            "must_not": [
                {
                    "exists": {
                        "path": "/deleted_at"
                    }
                }
            ]
        }
    },
    "full_text_search": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "full_text_index": "document_text",
    "semantic_search": "artificial intelligence and machine learning applications",
    "embedding_template": "{{remoteMedia url=this}}",
    "indexes": [
        "title_body_nomic",
        "description_embedding"
    ],
    "filter_prefix": "string",
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "exclusion_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "aggregations": {},
    "embeddings": {},
    "search_effort": 0.5,
    "fields": [
        "title",
        "url",
        "summary",
        "created_at"
    ],
    "hierarchy": null,
    "limit": 20,
    "offset": 0,
    "timeout_ms": 5000,
    "order_by": [
        {
            "field": "created_at",
            "desc": true
        },
        {
            "field": "score",
            "desc": true
        }
    ],
    "search_after": [
        null
    ],
    "search_before": [
        null
    ],
    "distance_under": 0.5,
    "distance_over": 0.1,
    "merge_config": {
        "strategy": "rrf",
        "weights": {
            "full_text": 0.3,
            "title_embedding": 1
        },
        "window_size": 1,
        "rank_constant": 0
    },
    "count": false,
    "profile": false,
    "reranker": {
        "provider": "cohere",
        "model": "rerank-v4.0-pro",
        "field": "content"
    },
    "analyses": {
        "pca": true,
        "tsne": true
    },
    "graph_queries": {},
    "document_renderer": "{{encodeToon this.fields}}",
    "pruner": {
        "min_score_ratio": 0.5,
        "max_score_gap_percent": 30,
        "min_absolute_score": 0.01,
        "require_multi_index": true,
        "std_dev_threshold": 1.5
    },
    "join": {
        "right_table": "customers",
        "join_type": "inner",
        "on": {
            "left_field": "customer_id",
            "right_field": "id",
            "operator": "eq"
        },
        "right_filters": {
            "filter_query": {
                "term": "string",
                "field": "string",
                "boost": 0
            },
            "filter_prefix": "string",
            "limit": 0
        },
        "right_fields": [
            "name",
            "email",
            "tier"
        ],
        "strategy_hint": "broadcast",
        "nested_join": "..."
    },
    "foreign_sources": {}
}

Code Examples#

curl -X POST "/db/v1/query" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table": "wikipedia",
    "query": {
        "bool": {
            "must": [
                {
                    "match": {
                        "field": "body",
                        "text": "computer"
                    }
                }
            ],
            "filter": [
                {
                    "term": {
                        "path": "/tenant",
                        "value": "acme"
                    }
                }
            ],
            "must_not": [
                {
                    "exists": {
                        "path": "/deleted_at"
                    }
                }
            ]
        }
    },
    "full_text_search": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "full_text_index": "document_text",
    "semantic_search": "artificial intelligence and machine learning applications",
    "embedding_template": "{{remoteMedia url=this}}",
    "indexes": [
        "title_body_nomic",
        "description_embedding"
    ],
    "filter_prefix": "string",
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "exclusion_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "aggregations": {},
    "embeddings": {},
    "search_effort": 0.5,
    "fields": [
        "title",
        "url",
        "summary",
        "created_at"
    ],
    "hierarchy": null,
    "limit": 20,
    "offset": 0,
    "timeout_ms": 5000,
    "order_by": [
        {
            "field": "created_at",
            "desc": true
        },
        {
            "field": "score",
            "desc": true
        }
    ],
    "search_after": [
        null
    ],
    "search_before": [
        null
    ],
    "distance_under": 0.5,
    "distance_over": 0.1,
    "merge_config": {
        "strategy": "rrf",
        "weights": {
            "full_text": 0.3,
            "title_embedding": 1
        },
        "window_size": 1,
        "rank_constant": 0
    },
    "count": false,
    "profile": false,
    "reranker": {
        "provider": "cohere",
        "model": "rerank-v4.0-pro",
        "field": "content"
    },
    "analyses": {
        "pca": true,
        "tsne": true
    },
    "graph_queries": {},
    "document_renderer": "{{encodeToon this.fields}}",
    "pruner": {
        "min_score_ratio": 0.5,
        "max_score_gap_percent": 30,
        "min_absolute_score": 0.01,
        "require_multi_index": true,
        "std_dev_threshold": 1.5
    },
    "join": {
        "right_table": "customers",
        "join_type": "inner",
        "on": {
            "left_field": "customer_id",
            "right_field": "id",
            "operator": "eq"
        },
        "right_filters": {
            "filter_query": {
                "term": "string",
                "field": "string",
                "boost": 0
            },
            "filter_prefix": "string",
            "limit": 0
        },
        "right_fields": [
            "name",
            "email",
            "tier"
        ],
        "strategy_hint": "broadcast",
        "nested_join": "..."
    },
    "foreign_sources": {}
}'

const response = await fetch('/db/v1/query', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "wikipedia",
        "query": {
            "bool": {
                "must": [
                    {
                        "match": {
                            "field": "body",
                            "text": "computer"
                        }
                    }
                ],
                "filter": [
                    {
                        "term": {
                            "path": "/tenant",
                            "value": "acme"
                        }
                    }
                ],
                "must_not": [
                    {
                        "exists": {
                            "path": "/deleted_at"
                        }
                    }
                ]
            }
        },
        "full_text_search": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "full_text_index": "document_text",
        "semantic_search": "artificial intelligence and machine learning applications",
        "embedding_template": "{{remoteMedia url=this}}",
        "indexes": [
            "title_body_nomic",
            "description_embedding"
        ],
        "filter_prefix": "string",
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "exclusion_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "aggregations": {},
        "embeddings": {},
        "search_effort": 0.5,
        "fields": [
            "title",
            "url",
            "summary",
            "created_at"
        ],
        "hierarchy": null,
        "limit": 20,
        "offset": 0,
        "timeout_ms": 5000,
        "order_by": [
            {
                "field": "created_at",
                "desc": true
            },
            {
                "field": "score",
                "desc": true
            }
        ],
        "search_after": [
            null
        ],
        "search_before": [
            null
        ],
        "distance_under": 0.5,
        "distance_over": 0.1,
        "merge_config": {
            "strategy": "rrf",
            "weights": {
                "full_text": 0.3,
                "title_embedding": 1
            },
            "window_size": 1,
            "rank_constant": 0
        },
        "count": false,
        "profile": false,
        "reranker": {
            "provider": "cohere",
            "model": "rerank-v4.0-pro",
            "field": "content"
        },
        "analyses": {
            "pca": true,
            "tsne": true
        },
        "graph_queries": {},
        "document_renderer": "{{encodeToon this.fields}}",
        "pruner": {
            "min_score_ratio": 0.5,
            "max_score_gap_percent": 30,
            "min_absolute_score": 0.01,
            "require_multi_index": true,
            "std_dev_threshold": 1.5
        },
        "join": {
            "right_table": "customers",
            "join_type": "inner",
            "on": {
                "left_field": "customer_id",
                "right_field": "id",
                "operator": "eq"
            },
            "right_filters": {
                "filter_query": {
                    "term": "string",
                    "field": "string",
                    "boost": 0
                },
                "filter_prefix": "string",
                "limit": 0
            },
            "right_fields": [
                "name",
                "email",
                "tier"
            ],
            "strategy_hint": "broadcast",
            "nested_join": "..."
        },
        "foreign_sources": {}
    })
});

const data = await response.json();

fetch('/db/v1/query', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "wikipedia",
        "query": {
            "bool": {
                "must": [
                    {
                        "match": {
                            "field": "body",
                            "text": "computer"
                        }
                    }
                ],
                "filter": [
                    {
                        "term": {
                            "path": "/tenant",
                            "value": "acme"
                        }
                    }
                ],
                "must_not": [
                    {
                        "exists": {
                            "path": "/deleted_at"
                        }
                    }
                ]
            }
        },
        "full_text_search": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "full_text_index": "document_text",
        "semantic_search": "artificial intelligence and machine learning applications",
        "embedding_template": "{{remoteMedia url=this}}",
        "indexes": [
            "title_body_nomic",
            "description_embedding"
        ],
        "filter_prefix": "string",
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "exclusion_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "aggregations": {},
        "embeddings": {},
        "search_effort": 0.5,
        "fields": [
            "title",
            "url",
            "summary",
            "created_at"
        ],
        "hierarchy": null,
        "limit": 20,
        "offset": 0,
        "timeout_ms": 5000,
        "order_by": [
            {
                "field": "created_at",
                "desc": true
            },
            {
                "field": "score",
                "desc": true
            }
        ],
        "search_after": [
            null
        ],
        "search_before": [
            null
        ],
        "distance_under": 0.5,
        "distance_over": 0.1,
        "merge_config": {
            "strategy": "rrf",
            "weights": {
                "full_text": 0.3,
                "title_embedding": 1
            },
            "window_size": 1,
            "rank_constant": 0
        },
        "count": false,
        "profile": false,
        "reranker": {
            "provider": "cohere",
            "model": "rerank-v4.0-pro",
            "field": "content"
        },
        "analyses": {
            "pca": true,
            "tsne": true
        },
        "graph_queries": {},
        "document_renderer": "{{encodeToon this.fields}}",
        "pruner": {
            "min_score_ratio": 0.5,
            "max_score_gap_percent": 30,
            "min_absolute_score": 0.01,
            "require_multi_index": true,
            "std_dev_threshold": 1.5
        },
        "join": {
            "right_table": "customers",
            "join_type": "inner",
            "on": {
                "left_field": "customer_id",
                "right_field": "id",
                "operator": "eq"
            },
            "right_filters": {
                "filter_query": {
                    "term": "string",
                    "field": "string",
                    "boost": 0
                },
                "filter_prefix": "string",
                "limit": 0
            },
            "right_fields": [
                "name",
                "email",
                "tier"
            ],
            "strategy_hint": "broadcast",
            "nested_join": "..."
        },
        "foreign_sources": {}
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/query',
    headers=headers,
    json={
        "table": "wikipedia",
        "query": {
            "bool": {
                "must": [
                    {
                        "match": {
                            "field": "body",
                            "text": "computer"
                        }
                    }
                ],
                "filter": [
                    {
                        "term": {
                            "path": "/tenant",
                            "value": "acme"
                        }
                    }
                ],
                "must_not": [
                    {
                        "exists": {
                            "path": "/deleted_at"
                        }
                    }
                ]
            }
        },
        "full_text_search": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "full_text_index": "document_text",
        "semantic_search": "artificial intelligence and machine learning applications",
        "embedding_template": "{{remoteMedia url=this}}",
        "indexes": [
            "title_body_nomic",
            "description_embedding"
        ],
        "filter_prefix": "string",
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "exclusion_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "aggregations": {},
        "embeddings": {},
        "search_effort": 0.5,
        "fields": [
            "title",
            "url",
            "summary",
            "created_at"
        ],
        "hierarchy": null,
        "limit": 20,
        "offset": 0,
        "timeout_ms": 5000,
        "order_by": [
            {
                "field": "created_at",
                "desc": true
            },
            {
                "field": "score",
                "desc": true
            }
        ],
        "search_after": [
            null
        ],
        "search_before": [
            null
        ],
        "distance_under": 0.5,
        "distance_over": 0.1,
        "merge_config": {
            "strategy": "rrf",
            "weights": {
                "full_text": 0.3,
                "title_embedding": 1
            },
            "window_size": 1,
            "rank_constant": 0
        },
        "count": false,
        "profile": false,
        "reranker": {
            "provider": "cohere",
            "model": "rerank-v4.0-pro",
            "field": "content"
        },
        "analyses": {
            "pca": true,
            "tsne": true
        },
        "graph_queries": {},
        "document_renderer": "{{encodeToon this.fields}}",
        "pruner": {
            "min_score_ratio": 0.5,
            "max_score_gap_percent": 30,
            "min_absolute_score": 0.01,
            "require_multi_index": true,
            "std_dev_threshold": 1.5
        },
        "join": {
            "right_table": "customers",
            "join_type": "inner",
            "on": {
                "left_field": "customer_id",
                "right_field": "id",
                "operator": "eq"
            },
            "right_filters": {
                "filter_query": {
                    "term": "string",
                    "field": "string",
                    "boost": 0
                },
                "filter_prefix": "string",
                "limit": 0
            },
            "right_fields": [
                "name",
                "email",
                "tier"
            ],
            "strategy_hint": "broadcast",
            "nested_join": "..."
        },
        "foreign_sources": {}
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "table": "wikipedia",
    "query": {
        "bool": {
            "must": [
                {
                    "match": {
                        "field": "body",
                        "text": "computer"
                    }
                }
            ],
            "filter": [
                {
                    "term": {
                        "path": "/tenant",
                        "value": "acme"
                    }
                }
            ],
            "must_not": [
                {
                    "exists": {
                        "path": "/deleted_at"
                    }
                }
            ]
        }
    },
    "full_text_search": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "full_text_index": "document_text",
    "semantic_search": "artificial intelligence and machine learning applications",
    "embedding_template": "{{remoteMedia url=this}}",
    "indexes": [
        "title_body_nomic",
        "description_embedding"
    ],
    "filter_prefix": "string",
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "exclusion_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "aggregations": {},
    "embeddings": {},
    "search_effort": 0.5,
    "fields": [
        "title",
        "url",
        "summary",
        "created_at"
    ],
    "hierarchy": null,
    "limit": 20,
    "offset": 0,
    "timeout_ms": 5000,
    "order_by": [
        {
            "field": "created_at",
            "desc": true
        },
        {
            "field": "score",
            "desc": true
        }
    ],
    "search_after": [
        null
    ],
    "search_before": [
        null
    ],
    "distance_under": 0.5,
    "distance_over": 0.1,
    "merge_config": {
        "strategy": "rrf",
        "weights": {
            "full_text": 0.3,
            "title_embedding": 1
        },
        "window_size": 1,
        "rank_constant": 0
    },
    "count": false,
    "profile": false,
    "reranker": {
        "provider": "cohere",
        "model": "rerank-v4.0-pro",
        "field": "content"
    },
    "analyses": {
        "pca": true,
        "tsne": true
    },
    "graph_queries": {},
    "document_renderer": "{{encodeToon this.fields}}",
    "pruner": {
        "min_score_ratio": 0.5,
        "max_score_gap_percent": 30,
        "min_absolute_score": 0.01,
        "require_multi_index": true,
        "std_dev_threshold": 1.5
    },
    "join": {
        "right_table": "customers",
        "join_type": "inner",
        "on": {
            "left_field": "customer_id",
            "right_field": "id",
            "operator": "eq"
        },
        "right_filters": {
            "filter_query": {
                "term": "string",
                "field": "string",
                "boost": 0
            },
            "filter_prefix": "string",
            "limit": 0
        },
        "right_fields": [
            "name",
            "email",
            "tier"
        ],
        "strategy_hint": "broadcast",
        "nested_join": "..."
    },
    "foreign_sources": {}
}`)
    req, _ := http.NewRequest("POST", "/db/v1/query", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "responses": [
    {
      "hits": {
        "total": {
          "value": 0,
          "relation": "exact"
        },
        "hits": [
          {
            "_id": "string",
            "_score": 0,
            "_distance": 0,
            "_index_scores": {},
            "_source": {},
            "hierarchy": {
              "level": "source",
              "parent_doc_key": "string",
              "parent_unit_id": "string",
              "artifact": {
                "name": "string",
                "kind": "chunk",
                "chunk_id": 0,
                "unit_id": "string",
                "source": {
                  "name": "string",
                  "kind": "chunk",
                  "chunk_id": 0,
                  "unit_id": "string"
                }
              },
              "matched_artifact": {
                "name": "string",
                "kind": "chunk",
                "chunk_id": 0,
                "unit_id": "string",
                "source": {
                  "name": "string",
                  "kind": "chunk",
                  "chunk_id": 0,
                  "unit_id": "string"
                }
              },
              "ancestors": {
                "source": {
                  "id": "string",
                  "document": {},
                  "key": "string",
                  "artifact_name": "string",
                  "source_field": "string",
                  "provenance": null
                },
                "unit": {
                  "id": "string",
                  "document": {},
                  "key": "string",
                  "artifact_name": "string",
                  "source_field": "string",
                  "provenance": null
                }
              },
              "evidence": {
                "local_id": "string",
                "decision": "string",
                "confidence": 0,
                "source_artifact": "string",
                "source_artifact_key": "string",
                "resolution_artifact": "string",
                "resolution_artifact_key": "string",
                "resolver": "string",
                "resolver_table": "string",
                "mention": {},
                "canonical": {}
              },
              "matches": [
                {
                  "_id": "string",
                  "_score": 0,
                  "_distance": 0,
                  "_source": {},
                  "hierarchy": {
                    "level": "source",
                    "parent_doc_key": "string",
                    "parent_unit_id": "string",
                    "artifact": {
                      "name": "string",
                      "kind": "chunk",
                      "chunk_id": 0,
                      "unit_id": "string",
                      "source": {
                        "name": "string",
                        "kind": "chunk",
                        "chunk_id": 0,
                        "unit_id": "string"
                      }
                    },
                    "ancestors": {
                      "source": {
                        "id": "string",
                        "document": {},
                        "key": "string",
                        "artifact_name": "string",
                        "source_field": "string",
                        "provenance": null
                      },
                      "unit": {
                        "id": "string",
                        "document": {},
                        "key": "string",
                        "artifact_name": "string",
                        "source_field": "string",
                        "provenance": null
                      }
                    }
                  }
                }
              ],
              "position": "string",
              "revision": "string",
              "chunks": [
                {
                  "_id": "string",
                  "_score": 0,
                  "_distance": 0,
                  "_source": {},
                  "hierarchy": {
                    "level": "source",
                    "parent_doc_key": "string",
                    "parent_unit_id": "string",
                    "artifact": {
                      "name": "string",
                      "kind": "chunk",
                      "chunk_id": 0,
                      "unit_id": "string",
                      "source": {
                        "name": "string",
                        "kind": "chunk",
                        "chunk_id": 0,
                        "unit_id": "string"
                      }
                    },
                    "ancestors": {
                      "source": {
                        "id": "string",
                        "document": {},
                        "key": "string",
                        "artifact_name": "string",
                        "source_field": "string",
                        "provenance": null
                      },
                      "unit": {
                        "id": "string",
                        "document": {},
                        "key": "string",
                        "artifact_name": "string",
                        "source_field": "string",
                        "provenance": null
                      }
                    }
                  }
                }
              ]
            },
            "_sort": [
              null
            ]
          }
        ],
        "max_score": 0
      },
      "aggregations": {},
      "analyses": {},
      "profile": {
        "shards": {
          "total": 0,
          "successful": 0,
          "failed": 0
        },
        "join": {
          "strategy_used": "broadcast",
          "left_rows_scanned": 0,
          "right_rows_scanned": 0,
          "rows_matched": 0,
          "rows_unmatched_left": 0,
          "rows_unmatched_right": 0,
          "duration_ms": 0
        },
        "reranker": {
          "provider": "antfly",
          "model": "string",
          "documents_reranked": 0,
          "duration_ms": 0
        },
        "merge": {
          "strategy": "rrf",
          "full_text_hits": 0,
          "semantic_hits": 0,
          "duration_ms": 0
        },
        "sort": {
          "plan": "string",
          "order_by": [
            {
              "field": "string",
              "desc": true
            }
          ],
          "cursor": "string",
          "exactness": "string",
          "source": "string",
          "candidate_source": "none",
          "cursor_support": "string",
          "source_load": "string",
          "distributed_behavior": "string",
          "selection_reason": "string",
          "require_native": true,
          "sort_lifecycle_state": "unsupported",
          "index_sort_coverage": "string",
          "candidate_count": 0,
          "cursor_rejected_count": 0,
          "selected_count": 0,
          "total_us": 0,
          "distributed_shard_count": 0,
          "budget_rejection_reason": "string",
          "sort_rejection_reason": "string",
          "sort_rejection_detail": "string",
          "sort_rejection_field": "string"
        }
      },
      "took": 0,
      "status": 0,
      "error": "string",
      "table": "string"
    }
  ]
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

Standalone evaluation endpoint#

POST/eval

Run evaluators on provided data without executing a query. Useful for testing evaluators, evaluating cached results, or batch evaluation.

Retrieval metrics (require ground_truth.relevant_ids and retrieved_ids):

recall, precision, ndcg, mrr, map

LLM-as-judge metrics (require judge config):

relevance, faithfulness, completeness, coherence, safety, helpfulness, correctness, citation_quality

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "evaluators": [
        "recall"
    ],
    "judge": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    },
    "ground_truth": {
        "relevant_ids": [
            "string"
        ],
        "expectations": "string"
    },
    "options": {
        "k": 1,
        "pass_threshold": 0,
        "timeout_seconds": 1
    },
    "query": "string",
    "output": "string",
    "context": [
        {}
    ],
    "retrieved_ids": [
        "string"
    ]
}

Code Examples#

curl -X POST "/db/v1/eval" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "evaluators": [
        "recall"
    ],
    "judge": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    },
    "ground_truth": {
        "relevant_ids": [
            "string"
        ],
        "expectations": "string"
    },
    "options": {
        "k": 1,
        "pass_threshold": 0,
        "timeout_seconds": 1
    },
    "query": "string",
    "output": "string",
    "context": [
        {}
    ],
    "retrieved_ids": [
        "string"
    ]
}'

const response = await fetch('/db/v1/eval', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "evaluators": [
            "recall"
        ],
        "judge": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        },
        "ground_truth": {
            "relevant_ids": [
                "string"
            ],
            "expectations": "string"
        },
        "options": {
            "k": 1,
            "pass_threshold": 0,
            "timeout_seconds": 1
        },
        "query": "string",
        "output": "string",
        "context": [
            {}
        ],
        "retrieved_ids": [
            "string"
        ]
    })
});

const data = await response.json();

fetch('/db/v1/eval', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "evaluators": [
            "recall"
        ],
        "judge": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        },
        "ground_truth": {
            "relevant_ids": [
                "string"
            ],
            "expectations": "string"
        },
        "options": {
            "k": 1,
            "pass_threshold": 0,
            "timeout_seconds": 1
        },
        "query": "string",
        "output": "string",
        "context": [
            {}
        ],
        "retrieved_ids": [
            "string"
        ]
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/eval',
    headers=headers,
    json={
        "evaluators": [
            "recall"
        ],
        "judge": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        },
        "ground_truth": {
            "relevant_ids": [
                "string"
            ],
            "expectations": "string"
        },
        "options": {
            "k": 1,
            "pass_threshold": 0,
            "timeout_seconds": 1
        },
        "query": "string",
        "output": "string",
        "context": [
            {}
        ],
        "retrieved_ids": [
            "string"
        ]
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "evaluators": [
        "recall"
    ],
    "judge": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    },
    "ground_truth": {
        "relevant_ids": [
            "string"
        ],
        "expectations": "string"
    },
    "options": {
        "k": 1,
        "pass_threshold": 0,
        "timeout_seconds": 1
    },
    "query": "string",
    "output": "string",
    "context": [
        {}
    ],
    "retrieved_ids": [
        "string"
    ]
}`)
    req, _ := http.NewRequest("POST", "/db/v1/eval", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "scores": {
    "retrieval": {},
    "generation": {}
  },
  "summary": {
    "average_score": 0,
    "passed": 0,
    "failed": 0,
    "total": 0
  },
  "duration_ms": 0
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

Build a search query from natural language#

POST/agents/query-builder

Uses an LLM to translate natural language search intent into a structured Antfly query. The generated query can be used directly in the QueryRequest.full_text_search or filter_query fields.

This endpoint is useful for:

Building queries from user descriptions
Generating example queries for a table's schema
Agentic retrieval in RAG pipelines

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "session_id": "string",
    "decisions": [
        {
            "question_id": "string",
            "answer": null,
            "approved": true
        }
    ],
    "interactive": true,
    "max_internal_iterations": 0,
    "max_user_clarifications": 0,
    "require_decision_after": 0,
    "example_documents": [
        {}
    ],
    "table": "articles",
    "intent": "Find all published articles about machine learning from the last year",
    "schema_fields": [
        "title",
        "content",
        "status",
        "published_at"
    ],
    "mode": "auto",
    "output": "query_request",
    "constraints": {
        "limit": 10,
        "require_executable": true,
        "prefer_indexes": [
            "body_embedding"
        ]
    },
    "generator": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    }
}

Code Examples#

curl -X POST "/db/v1/agents/query-builder" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "session_id": "string",
    "decisions": [
        {
            "question_id": "string",
            "answer": null,
            "approved": true
        }
    ],
    "interactive": true,
    "max_internal_iterations": 0,
    "max_user_clarifications": 0,
    "require_decision_after": 0,
    "example_documents": [
        {}
    ],
    "table": "articles",
    "intent": "Find all published articles about machine learning from the last year",
    "schema_fields": [
        "title",
        "content",
        "status",
        "published_at"
    ],
    "mode": "auto",
    "output": "query_request",
    "constraints": {
        "limit": 10,
        "require_executable": true,
        "prefer_indexes": [
            "body_embedding"
        ]
    },
    "generator": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    }
}'

const response = await fetch('/db/v1/agents/query-builder', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "session_id": "string",
        "decisions": [
            {
                "question_id": "string",
                "answer": null,
                "approved": true
            }
        ],
        "interactive": true,
        "max_internal_iterations": 0,
        "max_user_clarifications": 0,
        "require_decision_after": 0,
        "example_documents": [
            {}
        ],
        "table": "articles",
        "intent": "Find all published articles about machine learning from the last year",
        "schema_fields": [
            "title",
            "content",
            "status",
            "published_at"
        ],
        "mode": "auto",
        "output": "query_request",
        "constraints": {
            "limit": 10,
            "require_executable": true,
            "prefer_indexes": [
                "body_embedding"
            ]
        },
        "generator": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        }
    })
});

const data = await response.json();

fetch('/db/v1/agents/query-builder', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "session_id": "string",
        "decisions": [
            {
                "question_id": "string",
                "answer": null,
                "approved": true
            }
        ],
        "interactive": true,
        "max_internal_iterations": 0,
        "max_user_clarifications": 0,
        "require_decision_after": 0,
        "example_documents": [
            {}
        ],
        "table": "articles",
        "intent": "Find all published articles about machine learning from the last year",
        "schema_fields": [
            "title",
            "content",
            "status",
            "published_at"
        ],
        "mode": "auto",
        "output": "query_request",
        "constraints": {
            "limit": 10,
            "require_executable": true,
            "prefer_indexes": [
                "body_embedding"
            ]
        },
        "generator": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        }
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/agents/query-builder',
    headers=headers,
    json={
        "session_id": "string",
        "decisions": [
            {
                "question_id": "string",
                "answer": null,
                "approved": true
            }
        ],
        "interactive": true,
        "max_internal_iterations": 0,
        "max_user_clarifications": 0,
        "require_decision_after": 0,
        "example_documents": [
            {}
        ],
        "table": "articles",
        "intent": "Find all published articles about machine learning from the last year",
        "schema_fields": [
            "title",
            "content",
            "status",
            "published_at"
        ],
        "mode": "auto",
        "output": "query_request",
        "constraints": {
            "limit": 10,
            "require_executable": true,
            "prefer_indexes": [
                "body_embedding"
            ]
        },
        "generator": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        }
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "session_id": "string",
    "decisions": [
        {
            "question_id": "string",
            "answer": null,
            "approved": true
        }
    ],
    "interactive": true,
    "max_internal_iterations": 0,
    "max_user_clarifications": 0,
    "require_decision_after": 0,
    "example_documents": [
        {}
    ],
    "table": "articles",
    "intent": "Find all published articles about machine learning from the last year",
    "schema_fields": [
        "title",
        "content",
        "status",
        "published_at"
    ],
    "mode": "auto",
    "output": "query_request",
    "constraints": {
        "limit": 10,
        "require_executable": true,
        "prefer_indexes": [
            "body_embedding"
        ]
    },
    "generator": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    }
}`)
    req, _ := http.NewRequest("POST", "/db/v1/agents/query-builder", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "session_id": "string",
  "iteration": 0,
  "clarification_count": 0,
  "status": "clarification_required",
  "steps": [
    {
      "id": "string",
      "kind": "tool_call",
      "name": "string",
      "action": "string",
      "status": "success",
      "error_message": "string",
      "duration_ms": 0,
      "details": {}
    }
  ],
  "remaining_internal_iterations": 0,
  "remaining_user_clarifications": 0,
  "questions": [
    {
      "id": "clarify_oauth_version",
      "kind": "confirm",
      "question": "string",
      "reason": "string",
      "options": [
        "string"
      ],
      "default_answer": "string",
      "affects": [
        "string"
      ]
    }
  ],
  "query": {
    "conjuncts": [
      {
        "match": "machine learning",
        "field": "content"
      },
      {
        "term": "published",
        "field": "status"
      }
    ]
  },
  "query_request": {
    "table": "wikipedia",
    "query": {
      "bool": {
        "must": [
          {
            "match": {
              "field": "body",
              "text": "computer"
            }
          }
        ],
        "filter": [
          {
            "term": {
              "path": "/tenant",
              "value": "acme"
            }
          }
        ],
        "must_not": [
          {
            "exists": {
              "path": "/deleted_at"
            }
          }
        ]
      }
    },
    "full_text_search": {
      "term": "string",
      "field": "string",
      "boost": 0
    },
    "full_text_index": "document_text",
    "semantic_search": "artificial intelligence and machine learning applications",
    "embedding_template": "{{remoteMedia url=this}}",
    "indexes": [
      "title_body_nomic",
      "description_embedding"
    ],
    "filter_prefix": "string",
    "filter_query": {
      "term": "string",
      "field": "string",
      "boost": 0
    },
    "exclusion_query": {
      "term": "string",
      "field": "string",
      "boost": 0
    },
    "aggregations": {},
    "embeddings": {},
    "search_effort": 0.5,
    "fields": [
      "title",
      "url",
      "summary",
      "created_at"
    ],
    "hierarchy": null,
    "limit": 20,
    "offset": 0,
    "timeout_ms": 5000,
    "order_by": [
      {
        "field": "created_at",
        "desc": true
      },
      {
        "field": "score",
        "desc": true
      }
    ],
    "search_after": [
      null
    ],
    "search_before": [
      null
    ],
    "distance_under": 0.5,
    "distance_over": 0.1,
    "merge_config": {
      "strategy": "rrf",
      "weights": {
        "full_text": 0.3,
        "title_embedding": 1
      },
      "window_size": 1,
      "rank_constant": 0
    },
    "count": false,
    "profile": false,
    "reranker": {
      "provider": "cohere",
      "model": "rerank-v4.0-pro",
      "field": "content"
    },
    "analyses": {
      "pca": true,
      "tsne": true
    },
    "graph_queries": {},
    "document_renderer": "{{encodeToon this.fields}}",
    "pruner": {
      "min_score_ratio": 0.5,
      "max_score_gap_percent": 30,
      "min_absolute_score": 0.01,
      "require_multi_index": true,
      "std_dev_threshold": 1.5
    },
    "join": {
      "right_table": "customers",
      "join_type": "inner",
      "on": {
        "left_field": "customer_id",
        "right_field": "id",
        "operator": "eq"
      },
      "right_filters": {
        "filter_query": {
          "term": "string",
          "field": "string",
          "boost": 0
        },
        "filter_prefix": "string",
        "limit": 0
      },
      "right_fields": [
        "name",
        "email",
        "tier"
      ],
      "strategy_hint": "broadcast",
      "nested_join": "..."
    },
    "foreign_sources": {}
  },
  "retrieval_query_request": {
    "table": "wikipedia",
    "query": {
      "bool": {
        "must": [
          {
            "match": {
              "field": "body",
              "text": "computer"
            }
          }
        ],
        "filter": [
          {
            "term": {
              "path": "/tenant",
              "value": "acme"
            }
          }
        ],
        "must_not": [
          {
            "exists": {
              "path": "/deleted_at"
            }
          }
        ]
      }
    },
    "full_text_search": {
      "term": "string",
      "field": "string",
      "boost": 0
    },
    "full_text_index": "document_text",
    "semantic_search": "artificial intelligence and machine learning applications",
    "embedding_template": "{{remoteMedia url=this}}",
    "indexes": [
      "title_body_nomic",
      "description_embedding"
    ],
    "filter_prefix": "string",
    "filter_query": {
      "term": "string",
      "field": "string",
      "boost": 0
    },
    "exclusion_query": {
      "term": "string",
      "field": "string",
      "boost": 0
    },
    "aggregations": {},
    "embeddings": {},
    "search_effort": 0.5,
    "fields": [
      "title",
      "url",
      "summary",
      "created_at"
    ],
    "hierarchy": null,
    "limit": 20,
    "offset": 0,
    "timeout_ms": 5000,
    "order_by": [
      {
        "field": "created_at",
        "desc": true
      },
      {
        "field": "score",
        "desc": true
      }
    ],
    "search_after": [
      null
    ],
    "search_before": [
      null
    ],
    "distance_under": 0.5,
    "distance_over": 0.1,
    "merge_config": {
      "strategy": "rrf",
      "weights": {
        "full_text": 0.3,
        "title_embedding": 1
      },
      "window_size": 1,
      "rank_constant": 0
    },
    "count": false,
    "profile": false,
    "reranker": {
      "provider": "cohere",
      "model": "rerank-v4.0-pro",
      "field": "content"
    },
    "analyses": {
      "pca": true,
      "tsne": true
    },
    "graph_queries": {},
    "document_renderer": "{{encodeToon this.fields}}",
    "pruner": {
      "min_score_ratio": 0.5,
      "max_score_gap_percent": 30,
      "min_absolute_score": 0.01,
      "require_multi_index": true,
      "std_dev_threshold": 1.5
    },
    "join": {
      "right_table": "customers",
      "join_type": "inner",
      "on": {
        "left_field": "customer_id",
        "right_field": "id",
        "operator": "eq"
      },
      "right_filters": {
        "filter_query": {
          "term": "string",
          "field": "string",
          "boost": 0
        },
        "filter_prefix": "string",
        "limit": 0
      },
      "right_fields": [
        "name",
        "email",
        "tier"
      ],
      "strategy_hint": "broadcast",
      "nested_join": "..."
    },
    "foreign_sources": {}
  },
  "specialist": "full_text",
  "plan": {},
  "explanation": "Searches for 'machine learning' in content field AND requires status to be exactly 'published'",
  "confidence": 0.85,
  "warnings": [
    "Field 'category' not found in schema, using content field instead"
  ]
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

Retrieval Agent - Agentic document retrieval with tool calling#

POST/agents/retrieval

Uses a DFA-based approach to retrieve documents: clarify → select_strategy → refine_query → execute

Key Features:

Multi-strategy: Semantic, BM25, tree, graph, metadata, or hybrid
Query Pipeline: Chain queries with references (e.g., tree search starting from semantic results)
Clarification: Optional multi-turn for query disambiguation
Reasoning Chain: Returns steps taken during retrieval

Strategies:

semantic: Vector similarity search using embeddings
bm25: Full-text search with BM25 scoring
metadata: Structured field queries
tree: Iterative tree navigation with summarization (PageIndex-style)
graph: Relationship-based traversal
hybrid: Combine strategies with RRF or rerank

SSE Event Types:

step_started: Pipeline step began (see SSEStepStarted schema)
step_progress: Progress within a step (see SSEStepProgress schema)
step_completed: Pipeline step finished (see SSEStepCompleted schema)
classification: Query classification result (see ClassificationTransformationResult)
reasoning: Streamed reasoning text chunk (string)
followup: Generated follow-up question (string)
hit: Individual document result (see QueryHit)
tool_mode: Tool calling mode selected (see SSEToolMode)
eval: Evaluation metrics (see EvalResult)
done: Retrieval complete (see RetrievalAgentResult)
done is the authoritative final bounded-agent envelope for both JSON and SSE consumers
error: Error occurred (see SSEError)

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "query": "How do I configure OAuth?",
    "queries": [
        {
            "table": "docs",
            "semantic_search": "How do I configure OAuth?",
            "indexes": [
                "doc_embeddings"
            ],
            "limit": 10
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "string",
            "tool_calls": [
                {
                    "id": "string",
                    "type": "function",
                    "function": {
                        "name": "string",
                        "arguments": "string"
                    }
                }
            ],
            "tool_call_id": "string",
            "name": "string"
        }
    ],
    "agent_knowledge": "This collection contains API documentation for the Acme product suite.",
    "accumulated_filters": [
        {
            "field": "string",
            "operator": "eq",
            "value": null
        }
    ],
    "session_id": "string",
    "decisions": [
        {
            "question_id": "string",
            "answer": null,
            "approved": true
        }
    ],
    "interactive": true,
    "max_internal_iterations": 0,
    "max_user_clarifications": 0,
    "require_decision_after": 0,
    "max_context_tokens": 0,
    "reserve_tokens": 4000,
    "stream": true,
    "generator": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    },
    "chain": [
        {
            "generator": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "retry": {
                "max_attempts": 1,
                "initial_backoff_ms": 100,
                "backoff_multiplier": 1,
                "max_backoff_ms": 0
            },
            "condition": "always"
        }
    ],
    "tools": {
        "enabled_tools": [
            "add_filter",
            "semantic_search",
            "web_search"
        ],
        "web_search_config": {
            "provider": "exa",
            "api_key": "string",
            "endpoint": "string",
            "project_id": "string",
            "location": "string",
            "data_store": "string",
            "serving_config": "string",
            "credentials_path": "string",
            "max_results": 1,
            "timeout_ms": 0,
            "safe_search": true,
            "language": "en",
            "region": "us",
            "include_content": true,
            "include_highlights": true
        },
        "web_search_connection": "string",
        "fetch_config": {
            "s3_credentials": {
                "endpoint": "s3.amazonaws.com",
                "use_ssl": true,
                "access_key_id": "your-access-key-id",
                "secret_access_key": "your-secret-access-key",
                "session_token": "your-session-token"
            },
            "max_content_length": 0,
            "allowed_hosts": [
                "string"
            ],
            "block_private_ips": true,
            "max_download_size_bytes": 0,
            "timeout_seconds": 0
        },
        "max_tool_iterations": 1
    },
    "steps": {
        "classification": {
            "enabled": true,
            "with_reasoning": true,
            "force_strategy": "simple",
            "force_semantic_mode": "rewrite"
        },
        "retrieval": {
            "tools": {
                "enabled_tools": [
                    "add_filter",
                    "semantic_search",
                    "web_search"
                ],
                "web_search_config": {
                    "provider": "exa",
                    "api_key": "string",
                    "endpoint": "string",
                    "project_id": "string",
                    "location": "string",
                    "data_store": "string",
                    "serving_config": "string",
                    "credentials_path": "string",
                    "max_results": 1,
                    "timeout_ms": 0,
                    "safe_search": true,
                    "language": "en",
                    "region": "us",
                    "include_content": true,
                    "include_highlights": true
                },
                "web_search_connection": "string",
                "fetch_config": {
                    "s3_credentials": {
                        "endpoint": "s3.amazonaws.com",
                        "use_ssl": true,
                        "access_key_id": "your-access-key-id",
                        "secret_access_key": "your-secret-access-key",
                        "session_token": "your-session-token"
                    },
                    "max_content_length": 0,
                    "allowed_hosts": [
                        "string"
                    ],
                    "block_private_ips": true,
                    "max_download_size_bytes": 0,
                    "timeout_seconds": 0
                },
                "max_tool_iterations": 1
            }
        },
        "generation": {
            "enabled": true,
            "generator": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "chain": [
                {
                    "generator": {
                        "provider": "openai",
                        "model": "gpt-4.1",
                        "temperature": 0.7,
                        "max_tokens": 2048
                    },
                    "retry": {
                        "max_attempts": 1,
                        "initial_backoff_ms": 100,
                        "backoff_multiplier": 1,
                        "max_backoff_ms": 0
                    },
                    "condition": "always"
                }
            ],
            "system_prompt": "string",
            "generation_context": "Be concise and technical. Include code examples where relevant."
        },
        "followup": {
            "enabled": true,
            "count": 1
        },
        "confidence": {
            "enabled": true
        },
        "eval": {
            "evaluators": [
                "recall"
            ],
            "judge": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "ground_truth": {
                "relevant_ids": [
                    "string"
                ],
                "expectations": "string"
            },
            "options": {
                "k": 1,
                "pass_threshold": 0,
                "timeout_seconds": 1
            }
        }
    },
    "document_renderer": "{{encodeToon this.fields}}"
}

Code Examples#

curl -X POST "/db/v1/agents/retrieval" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "query": "How do I configure OAuth?",
    "queries": [
        {
            "table": "docs",
            "semantic_search": "How do I configure OAuth?",
            "indexes": [
                "doc_embeddings"
            ],
            "limit": 10
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "string",
            "tool_calls": [
                {
                    "id": "string",
                    "type": "function",
                    "function": {
                        "name": "string",
                        "arguments": "string"
                    }
                }
            ],
            "tool_call_id": "string",
            "name": "string"
        }
    ],
    "agent_knowledge": "This collection contains API documentation for the Acme product suite.",
    "accumulated_filters": [
        {
            "field": "string",
            "operator": "eq",
            "value": null
        }
    ],
    "session_id": "string",
    "decisions": [
        {
            "question_id": "string",
            "answer": null,
            "approved": true
        }
    ],
    "interactive": true,
    "max_internal_iterations": 0,
    "max_user_clarifications": 0,
    "require_decision_after": 0,
    "max_context_tokens": 0,
    "reserve_tokens": 4000,
    "stream": true,
    "generator": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    },
    "chain": [
        {
            "generator": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "retry": {
                "max_attempts": 1,
                "initial_backoff_ms": 100,
                "backoff_multiplier": 1,
                "max_backoff_ms": 0
            },
            "condition": "always"
        }
    ],
    "tools": {
        "enabled_tools": [
            "add_filter",
            "semantic_search",
            "web_search"
        ],
        "web_search_config": {
            "provider": "exa",
            "api_key": "string",
            "endpoint": "string",
            "project_id": "string",
            "location": "string",
            "data_store": "string",
            "serving_config": "string",
            "credentials_path": "string",
            "max_results": 1,
            "timeout_ms": 0,
            "safe_search": true,
            "language": "en",
            "region": "us",
            "include_content": true,
            "include_highlights": true
        },
        "web_search_connection": "string",
        "fetch_config": {
            "s3_credentials": {
                "endpoint": "s3.amazonaws.com",
                "use_ssl": true,
                "access_key_id": "your-access-key-id",
                "secret_access_key": "your-secret-access-key",
                "session_token": "your-session-token"
            },
            "max_content_length": 0,
            "allowed_hosts": [
                "string"
            ],
            "block_private_ips": true,
            "max_download_size_bytes": 0,
            "timeout_seconds": 0
        },
        "max_tool_iterations": 1
    },
    "steps": {
        "classification": {
            "enabled": true,
            "with_reasoning": true,
            "force_strategy": "simple",
            "force_semantic_mode": "rewrite"
        },
        "retrieval": {
            "tools": {
                "enabled_tools": [
                    "add_filter",
                    "semantic_search",
                    "web_search"
                ],
                "web_search_config": {
                    "provider": "exa",
                    "api_key": "string",
                    "endpoint": "string",
                    "project_id": "string",
                    "location": "string",
                    "data_store": "string",
                    "serving_config": "string",
                    "credentials_path": "string",
                    "max_results": 1,
                    "timeout_ms": 0,
                    "safe_search": true,
                    "language": "en",
                    "region": "us",
                    "include_content": true,
                    "include_highlights": true
                },
                "web_search_connection": "string",
                "fetch_config": {
                    "s3_credentials": {
                        "endpoint": "s3.amazonaws.com",
                        "use_ssl": true,
                        "access_key_id": "your-access-key-id",
                        "secret_access_key": "your-secret-access-key",
                        "session_token": "your-session-token"
                    },
                    "max_content_length": 0,
                    "allowed_hosts": [
                        "string"
                    ],
                    "block_private_ips": true,
                    "max_download_size_bytes": 0,
                    "timeout_seconds": 0
                },
                "max_tool_iterations": 1
            }
        },
        "generation": {
            "enabled": true,
            "generator": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "chain": [
                {
                    "generator": {
                        "provider": "openai",
                        "model": "gpt-4.1",
                        "temperature": 0.7,
                        "max_tokens": 2048
                    },
                    "retry": {
                        "max_attempts": 1,
                        "initial_backoff_ms": 100,
                        "backoff_multiplier": 1,
                        "max_backoff_ms": 0
                    },
                    "condition": "always"
                }
            ],
            "system_prompt": "string",
            "generation_context": "Be concise and technical. Include code examples where relevant."
        },
        "followup": {
            "enabled": true,
            "count": 1
        },
        "confidence": {
            "enabled": true
        },
        "eval": {
            "evaluators": [
                "recall"
            ],
            "judge": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "ground_truth": {
                "relevant_ids": [
                    "string"
                ],
                "expectations": "string"
            },
            "options": {
                "k": 1,
                "pass_threshold": 0,
                "timeout_seconds": 1
            }
        }
    },
    "document_renderer": "{{encodeToon this.fields}}"
}'

const response = await fetch('/db/v1/agents/retrieval', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "query": "How do I configure OAuth?",
        "queries": [
            {
                "table": "docs",
                "semantic_search": "How do I configure OAuth?",
                "indexes": [
                    "doc_embeddings"
                ],
                "limit": 10
            }
        ],
        "messages": [
            {
                "role": "user",
                "content": "string",
                "tool_calls": [
                    {
                        "id": "string",
                        "type": "function",
                        "function": {
                            "name": "string",
                            "arguments": "string"
                        }
                    }
                ],
                "tool_call_id": "string",
                "name": "string"
            }
        ],
        "agent_knowledge": "This collection contains API documentation for the Acme product suite.",
        "accumulated_filters": [
            {
                "field": "string",
                "operator": "eq",
                "value": null
            }
        ],
        "session_id": "string",
        "decisions": [
            {
                "question_id": "string",
                "answer": null,
                "approved": true
            }
        ],
        "interactive": true,
        "max_internal_iterations": 0,
        "max_user_clarifications": 0,
        "require_decision_after": 0,
        "max_context_tokens": 0,
        "reserve_tokens": 4000,
        "stream": true,
        "generator": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        },
        "chain": [
            {
                "generator": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "retry": {
                    "max_attempts": 1,
                    "initial_backoff_ms": 100,
                    "backoff_multiplier": 1,
                    "max_backoff_ms": 0
                },
                "condition": "always"
            }
        ],
        "tools": {
            "enabled_tools": [
                "add_filter",
                "semantic_search",
                "web_search"
            ],
            "web_search_config": {
                "provider": "exa",
                "api_key": "string",
                "endpoint": "string",
                "project_id": "string",
                "location": "string",
                "data_store": "string",
                "serving_config": "string",
                "credentials_path": "string",
                "max_results": 1,
                "timeout_ms": 0,
                "safe_search": true,
                "language": "en",
                "region": "us",
                "include_content": true,
                "include_highlights": true
            },
            "web_search_connection": "string",
            "fetch_config": {
                "s3_credentials": {
                    "endpoint": "s3.amazonaws.com",
                    "use_ssl": true,
                    "access_key_id": "your-access-key-id",
                    "secret_access_key": "your-secret-access-key",
                    "session_token": "your-session-token"
                },
                "max_content_length": 0,
                "allowed_hosts": [
                    "string"
                ],
                "block_private_ips": true,
                "max_download_size_bytes": 0,
                "timeout_seconds": 0
            },
            "max_tool_iterations": 1
        },
        "steps": {
            "classification": {
                "enabled": true,
                "with_reasoning": true,
                "force_strategy": "simple",
                "force_semantic_mode": "rewrite"
            },
            "retrieval": {
                "tools": {
                    "enabled_tools": [
                        "add_filter",
                        "semantic_search",
                        "web_search"
                    ],
                    "web_search_config": {
                        "provider": "exa",
                        "api_key": "string",
                        "endpoint": "string",
                        "project_id": "string",
                        "location": "string",
                        "data_store": "string",
                        "serving_config": "string",
                        "credentials_path": "string",
                        "max_results": 1,
                        "timeout_ms": 0,
                        "safe_search": true,
                        "language": "en",
                        "region": "us",
                        "include_content": true,
                        "include_highlights": true
                    },
                    "web_search_connection": "string",
                    "fetch_config": {
                        "s3_credentials": {
                            "endpoint": "s3.amazonaws.com",
                            "use_ssl": true,
                            "access_key_id": "your-access-key-id",
                            "secret_access_key": "your-secret-access-key",
                            "session_token": "your-session-token"
                        },
                        "max_content_length": 0,
                        "allowed_hosts": [
                            "string"
                        ],
                        "block_private_ips": true,
                        "max_download_size_bytes": 0,
                        "timeout_seconds": 0
                    },
                    "max_tool_iterations": 1
                }
            },
            "generation": {
                "enabled": true,
                "generator": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "chain": [
                    {
                        "generator": {
                            "provider": "openai",
                            "model": "gpt-4.1",
                            "temperature": 0.7,
                            "max_tokens": 2048
                        },
                        "retry": {
                            "max_attempts": 1,
                            "initial_backoff_ms": 100,
                            "backoff_multiplier": 1,
                            "max_backoff_ms": 0
                        },
                        "condition": "always"
                    }
                ],
                "system_prompt": "string",
                "generation_context": "Be concise and technical. Include code examples where relevant."
            },
            "followup": {
                "enabled": true,
                "count": 1
            },
            "confidence": {
                "enabled": true
            },
            "eval": {
                "evaluators": [
                    "recall"
                ],
                "judge": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "ground_truth": {
                    "relevant_ids": [
                        "string"
                    ],
                    "expectations": "string"
                },
                "options": {
                    "k": 1,
                    "pass_threshold": 0,
                    "timeout_seconds": 1
                }
            }
        },
        "document_renderer": "{{encodeToon this.fields}}"
    })
});

const data = await response.json();

fetch('/db/v1/agents/retrieval', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "query": "How do I configure OAuth?",
        "queries": [
            {
                "table": "docs",
                "semantic_search": "How do I configure OAuth?",
                "indexes": [
                    "doc_embeddings"
                ],
                "limit": 10
            }
        ],
        "messages": [
            {
                "role": "user",
                "content": "string",
                "tool_calls": [
                    {
                        "id": "string",
                        "type": "function",
                        "function": {
                            "name": "string",
                            "arguments": "string"
                        }
                    }
                ],
                "tool_call_id": "string",
                "name": "string"
            }
        ],
        "agent_knowledge": "This collection contains API documentation for the Acme product suite.",
        "accumulated_filters": [
            {
                "field": "string",
                "operator": "eq",
                "value": null
            }
        ],
        "session_id": "string",
        "decisions": [
            {
                "question_id": "string",
                "answer": null,
                "approved": true
            }
        ],
        "interactive": true,
        "max_internal_iterations": 0,
        "max_user_clarifications": 0,
        "require_decision_after": 0,
        "max_context_tokens": 0,
        "reserve_tokens": 4000,
        "stream": true,
        "generator": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        },
        "chain": [
            {
                "generator": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "retry": {
                    "max_attempts": 1,
                    "initial_backoff_ms": 100,
                    "backoff_multiplier": 1,
                    "max_backoff_ms": 0
                },
                "condition": "always"
            }
        ],
        "tools": {
            "enabled_tools": [
                "add_filter",
                "semantic_search",
                "web_search"
            ],
            "web_search_config": {
                "provider": "exa",
                "api_key": "string",
                "endpoint": "string",
                "project_id": "string",
                "location": "string",
                "data_store": "string",
                "serving_config": "string",
                "credentials_path": "string",
                "max_results": 1,
                "timeout_ms": 0,
                "safe_search": true,
                "language": "en",
                "region": "us",
                "include_content": true,
                "include_highlights": true
            },
            "web_search_connection": "string",
            "fetch_config": {
                "s3_credentials": {
                    "endpoint": "s3.amazonaws.com",
                    "use_ssl": true,
                    "access_key_id": "your-access-key-id",
                    "secret_access_key": "your-secret-access-key",
                    "session_token": "your-session-token"
                },
                "max_content_length": 0,
                "allowed_hosts": [
                    "string"
                ],
                "block_private_ips": true,
                "max_download_size_bytes": 0,
                "timeout_seconds": 0
            },
            "max_tool_iterations": 1
        },
        "steps": {
            "classification": {
                "enabled": true,
                "with_reasoning": true,
                "force_strategy": "simple",
                "force_semantic_mode": "rewrite"
            },
            "retrieval": {
                "tools": {
                    "enabled_tools": [
                        "add_filter",
                        "semantic_search",
                        "web_search"
                    ],
                    "web_search_config": {
                        "provider": "exa",
                        "api_key": "string",
                        "endpoint": "string",
                        "project_id": "string",
                        "location": "string",
                        "data_store": "string",
                        "serving_config": "string",
                        "credentials_path": "string",
                        "max_results": 1,
                        "timeout_ms": 0,
                        "safe_search": true,
                        "language": "en",
                        "region": "us",
                        "include_content": true,
                        "include_highlights": true
                    },
                    "web_search_connection": "string",
                    "fetch_config": {
                        "s3_credentials": {
                            "endpoint": "s3.amazonaws.com",
                            "use_ssl": true,
                            "access_key_id": "your-access-key-id",
                            "secret_access_key": "your-secret-access-key",
                            "session_token": "your-session-token"
                        },
                        "max_content_length": 0,
                        "allowed_hosts": [
                            "string"
                        ],
                        "block_private_ips": true,
                        "max_download_size_bytes": 0,
                        "timeout_seconds": 0
                    },
                    "max_tool_iterations": 1
                }
            },
            "generation": {
                "enabled": true,
                "generator": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "chain": [
                    {
                        "generator": {
                            "provider": "openai",
                            "model": "gpt-4.1",
                            "temperature": 0.7,
                            "max_tokens": 2048
                        },
                        "retry": {
                            "max_attempts": 1,
                            "initial_backoff_ms": 100,
                            "backoff_multiplier": 1,
                            "max_backoff_ms": 0
                        },
                        "condition": "always"
                    }
                ],
                "system_prompt": "string",
                "generation_context": "Be concise and technical. Include code examples where relevant."
            },
            "followup": {
                "enabled": true,
                "count": 1
            },
            "confidence": {
                "enabled": true
            },
            "eval": {
                "evaluators": [
                    "recall"
                ],
                "judge": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "ground_truth": {
                    "relevant_ids": [
                        "string"
                    ],
                    "expectations": "string"
                },
                "options": {
                    "k": 1,
                    "pass_threshold": 0,
                    "timeout_seconds": 1
                }
            }
        },
        "document_renderer": "{{encodeToon this.fields}}"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/agents/retrieval',
    headers=headers,
    json={
        "query": "How do I configure OAuth?",
        "queries": [
            {
                "table": "docs",
                "semantic_search": "How do I configure OAuth?",
                "indexes": [
                    "doc_embeddings"
                ],
                "limit": 10
            }
        ],
        "messages": [
            {
                "role": "user",
                "content": "string",
                "tool_calls": [
                    {
                        "id": "string",
                        "type": "function",
                        "function": {
                            "name": "string",
                            "arguments": "string"
                        }
                    }
                ],
                "tool_call_id": "string",
                "name": "string"
            }
        ],
        "agent_knowledge": "This collection contains API documentation for the Acme product suite.",
        "accumulated_filters": [
            {
                "field": "string",
                "operator": "eq",
                "value": null
            }
        ],
        "session_id": "string",
        "decisions": [
            {
                "question_id": "string",
                "answer": null,
                "approved": true
            }
        ],
        "interactive": true,
        "max_internal_iterations": 0,
        "max_user_clarifications": 0,
        "require_decision_after": 0,
        "max_context_tokens": 0,
        "reserve_tokens": 4000,
        "stream": true,
        "generator": {
            "provider": "openai",
            "model": "gpt-4.1",
            "temperature": 0.7,
            "max_tokens": 2048
        },
        "chain": [
            {
                "generator": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "retry": {
                    "max_attempts": 1,
                    "initial_backoff_ms": 100,
                    "backoff_multiplier": 1,
                    "max_backoff_ms": 0
                },
                "condition": "always"
            }
        ],
        "tools": {
            "enabled_tools": [
                "add_filter",
                "semantic_search",
                "web_search"
            ],
            "web_search_config": {
                "provider": "exa",
                "api_key": "string",
                "endpoint": "string",
                "project_id": "string",
                "location": "string",
                "data_store": "string",
                "serving_config": "string",
                "credentials_path": "string",
                "max_results": 1,
                "timeout_ms": 0,
                "safe_search": true,
                "language": "en",
                "region": "us",
                "include_content": true,
                "include_highlights": true
            },
            "web_search_connection": "string",
            "fetch_config": {
                "s3_credentials": {
                    "endpoint": "s3.amazonaws.com",
                    "use_ssl": true,
                    "access_key_id": "your-access-key-id",
                    "secret_access_key": "your-secret-access-key",
                    "session_token": "your-session-token"
                },
                "max_content_length": 0,
                "allowed_hosts": [
                    "string"
                ],
                "block_private_ips": true,
                "max_download_size_bytes": 0,
                "timeout_seconds": 0
            },
            "max_tool_iterations": 1
        },
        "steps": {
            "classification": {
                "enabled": true,
                "with_reasoning": true,
                "force_strategy": "simple",
                "force_semantic_mode": "rewrite"
            },
            "retrieval": {
                "tools": {
                    "enabled_tools": [
                        "add_filter",
                        "semantic_search",
                        "web_search"
                    ],
                    "web_search_config": {
                        "provider": "exa",
                        "api_key": "string",
                        "endpoint": "string",
                        "project_id": "string",
                        "location": "string",
                        "data_store": "string",
                        "serving_config": "string",
                        "credentials_path": "string",
                        "max_results": 1,
                        "timeout_ms": 0,
                        "safe_search": true,
                        "language": "en",
                        "region": "us",
                        "include_content": true,
                        "include_highlights": true
                    },
                    "web_search_connection": "string",
                    "fetch_config": {
                        "s3_credentials": {
                            "endpoint": "s3.amazonaws.com",
                            "use_ssl": true,
                            "access_key_id": "your-access-key-id",
                            "secret_access_key": "your-secret-access-key",
                            "session_token": "your-session-token"
                        },
                        "max_content_length": 0,
                        "allowed_hosts": [
                            "string"
                        ],
                        "block_private_ips": true,
                        "max_download_size_bytes": 0,
                        "timeout_seconds": 0
                    },
                    "max_tool_iterations": 1
                }
            },
            "generation": {
                "enabled": true,
                "generator": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "chain": [
                    {
                        "generator": {
                            "provider": "openai",
                            "model": "gpt-4.1",
                            "temperature": 0.7,
                            "max_tokens": 2048
                        },
                        "retry": {
                            "max_attempts": 1,
                            "initial_backoff_ms": 100,
                            "backoff_multiplier": 1,
                            "max_backoff_ms": 0
                        },
                        "condition": "always"
                    }
                ],
                "system_prompt": "string",
                "generation_context": "Be concise and technical. Include code examples where relevant."
            },
            "followup": {
                "enabled": true,
                "count": 1
            },
            "confidence": {
                "enabled": true
            },
            "eval": {
                "evaluators": [
                    "recall"
                ],
                "judge": {
                    "provider": "openai",
                    "model": "gpt-4.1",
                    "temperature": 0.7,
                    "max_tokens": 2048
                },
                "ground_truth": {
                    "relevant_ids": [
                        "string"
                    ],
                    "expectations": "string"
                },
                "options": {
                    "k": 1,
                    "pass_threshold": 0,
                    "timeout_seconds": 1
                }
            }
        },
        "document_renderer": "{{encodeToon this.fields}}"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "query": "How do I configure OAuth?",
    "queries": [
        {
            "table": "docs",
            "semantic_search": "How do I configure OAuth?",
            "indexes": [
                "doc_embeddings"
            ],
            "limit": 10
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "string",
            "tool_calls": [
                {
                    "id": "string",
                    "type": "function",
                    "function": {
                        "name": "string",
                        "arguments": "string"
                    }
                }
            ],
            "tool_call_id": "string",
            "name": "string"
        }
    ],
    "agent_knowledge": "This collection contains API documentation for the Acme product suite.",
    "accumulated_filters": [
        {
            "field": "string",
            "operator": "eq",
            "value": null
        }
    ],
    "session_id": "string",
    "decisions": [
        {
            "question_id": "string",
            "answer": null,
            "approved": true
        }
    ],
    "interactive": true,
    "max_internal_iterations": 0,
    "max_user_clarifications": 0,
    "require_decision_after": 0,
    "max_context_tokens": 0,
    "reserve_tokens": 4000,
    "stream": true,
    "generator": {
        "provider": "openai",
        "model": "gpt-4.1",
        "temperature": 0.7,
        "max_tokens": 2048
    },
    "chain": [
        {
            "generator": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "retry": {
                "max_attempts": 1,
                "initial_backoff_ms": 100,
                "backoff_multiplier": 1,
                "max_backoff_ms": 0
            },
            "condition": "always"
        }
    ],
    "tools": {
        "enabled_tools": [
            "add_filter",
            "semantic_search",
            "web_search"
        ],
        "web_search_config": {
            "provider": "exa",
            "api_key": "string",
            "endpoint": "string",
            "project_id": "string",
            "location": "string",
            "data_store": "string",
            "serving_config": "string",
            "credentials_path": "string",
            "max_results": 1,
            "timeout_ms": 0,
            "safe_search": true,
            "language": "en",
            "region": "us",
            "include_content": true,
            "include_highlights": true
        },
        "web_search_connection": "string",
        "fetch_config": {
            "s3_credentials": {
                "endpoint": "s3.amazonaws.com",
                "use_ssl": true,
                "access_key_id": "your-access-key-id",
                "secret_access_key": "your-secret-access-key",
                "session_token": "your-session-token"
            },
            "max_content_length": 0,
            "allowed_hosts": [
                "string"
            ],
            "block_private_ips": true,
            "max_download_size_bytes": 0,
            "timeout_seconds": 0
        },
        "max_tool_iterations": 1
    },
    "steps": {
        "classification": {
            "enabled": true,
            "with_reasoning": true,
            "force_strategy": "simple",
            "force_semantic_mode": "rewrite"
        },
        "retrieval": {
            "tools": {
                "enabled_tools": [
                    "add_filter",
                    "semantic_search",
                    "web_search"
                ],
                "web_search_config": {
                    "provider": "exa",
                    "api_key": "string",
                    "endpoint": "string",
                    "project_id": "string",
                    "location": "string",
                    "data_store": "string",
                    "serving_config": "string",
                    "credentials_path": "string",
                    "max_results": 1,
                    "timeout_ms": 0,
                    "safe_search": true,
                    "language": "en",
                    "region": "us",
                    "include_content": true,
                    "include_highlights": true
                },
                "web_search_connection": "string",
                "fetch_config": {
                    "s3_credentials": {
                        "endpoint": "s3.amazonaws.com",
                        "use_ssl": true,
                        "access_key_id": "your-access-key-id",
                        "secret_access_key": "your-secret-access-key",
                        "session_token": "your-session-token"
                    },
                    "max_content_length": 0,
                    "allowed_hosts": [
                        "string"
                    ],
                    "block_private_ips": true,
                    "max_download_size_bytes": 0,
                    "timeout_seconds": 0
                },
                "max_tool_iterations": 1
            }
        },
        "generation": {
            "enabled": true,
            "generator": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "chain": [
                {
                    "generator": {
                        "provider": "openai",
                        "model": "gpt-4.1",
                        "temperature": 0.7,
                        "max_tokens": 2048
                    },
                    "retry": {
                        "max_attempts": 1,
                        "initial_backoff_ms": 100,
                        "backoff_multiplier": 1,
                        "max_backoff_ms": 0
                    },
                    "condition": "always"
                }
            ],
            "system_prompt": "string",
            "generation_context": "Be concise and technical. Include code examples where relevant."
        },
        "followup": {
            "enabled": true,
            "count": 1
        },
        "confidence": {
            "enabled": true
        },
        "eval": {
            "evaluators": [
                "recall"
            ],
            "judge": {
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0.7,
                "max_tokens": 2048
            },
            "ground_truth": {
                "relevant_ids": [
                    "string"
                ],
                "expectations": "string"
            },
            "options": {
                "k": 1,
                "pass_threshold": 0,
                "timeout_seconds": 1
            }
        }
    },
    "document_renderer": "{{encodeToon this.fields}}"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/agents/retrieval", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "id": "ragr_cr3ig20h5tbs73e3ahrg",
  "model": "gemini-2.0-flash",
  "created_at": 0,
  "status": "clarification_required",
  "incomplete_details": {
    "reason": "max_internal_iterations"
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "cached_input_tokens": 0,
    "llm_calls": 0,
    "resources_retrieved": 0,
    "prune_stats": {
      "resources_kept": 0,
      "resources_pruned": 0,
      "tokens_kept": 0,
      "tokens_pruned": 0
    }
  },
  "hits": [
    {
      "_id": "string",
      "_score": 0,
      "_distance": 0,
      "_index_scores": {},
      "_source": {},
      "hierarchy": {
        "level": "source",
        "parent_doc_key": "string",
        "parent_unit_id": "string",
        "artifact": {
          "name": "string",
          "kind": "chunk",
          "chunk_id": 0,
          "unit_id": "string",
          "source": {
            "name": "string",
            "kind": "chunk",
            "chunk_id": 0,
            "unit_id": "string"
          }
        },
        "matched_artifact": {
          "name": "string",
          "kind": "chunk",
          "chunk_id": 0,
          "unit_id": "string",
          "source": {
            "name": "string",
            "kind": "chunk",
            "chunk_id": 0,
            "unit_id": "string"
          }
        },
        "ancestors": {
          "source": {
            "id": "string",
            "document": {},
            "key": "string",
            "artifact_name": "string",
            "source_field": "string",
            "provenance": null
          },
          "unit": {
            "id": "string",
            "document": {},
            "key": "string",
            "artifact_name": "string",
            "source_field": "string",
            "provenance": null
          }
        },
        "evidence": {
          "local_id": "string",
          "decision": "string",
          "confidence": 0,
          "source_artifact": "string",
          "source_artifact_key": "string",
          "resolution_artifact": "string",
          "resolution_artifact_key": "string",
          "resolver": "string",
          "resolver_table": "string",
          "mention": {},
          "canonical": {}
        },
        "matches": [
          {
            "_id": "string",
            "_score": 0,
            "_distance": 0,
            "_source": {},
            "hierarchy": {
              "level": "source",
              "parent_doc_key": "string",
              "parent_unit_id": "string",
              "artifact": {
                "name": "string",
                "kind": "chunk",
                "chunk_id": 0,
                "unit_id": "string",
                "source": {
                  "name": "string",
                  "kind": "chunk",
                  "chunk_id": 0,
                  "unit_id": "string"
                }
              },
              "ancestors": {
                "source": {
                  "id": "string",
                  "document": {},
                  "key": "string",
                  "artifact_name": "string",
                  "source_field": "string",
                  "provenance": null
                },
                "unit": {
                  "id": "string",
                  "document": {},
                  "key": "string",
                  "artifact_name": "string",
                  "source_field": "string",
                  "provenance": null
                }
              }
            }
          }
        ],
        "position": "string",
        "revision": "string",
        "chunks": [
          {
            "_id": "string",
            "_score": 0,
            "_distance": 0,
            "_source": {},
            "hierarchy": {
              "level": "source",
              "parent_doc_key": "string",
              "parent_unit_id": "string",
              "artifact": {
                "name": "string",
                "kind": "chunk",
                "chunk_id": 0,
                "unit_id": "string",
                "source": {
                  "name": "string",
                  "kind": "chunk",
                  "chunk_id": 0,
                  "unit_id": "string"
                }
              },
              "ancestors": {
                "source": {
                  "id": "string",
                  "document": {},
                  "key": "string",
                  "artifact_name": "string",
                  "source_field": "string",
                  "provenance": null
                },
                "unit": {
                  "id": "string",
                  "document": {},
                  "key": "string",
                  "artifact_name": "string",
                  "source_field": "string",
                  "provenance": null
                }
              }
            }
          }
        ]
      },
      "_sort": [
        null
      ]
    }
  ],
  "steps": [
    {
      "id": "string",
      "kind": "tool_call",
      "name": "string",
      "action": "string",
      "status": "success",
      "error_message": "string",
      "duration_ms": 0,
      "details": {}
    }
  ],
  "strategy_used": "semantic",
  "session_id": "string",
  "iteration": 0,
  "clarification_count": 0,
  "remaining_internal_iterations": 0,
  "remaining_user_clarifications": 0,
  "questions": [
    {
      "id": "clarify_oauth_version",
      "kind": "confirm",
      "question": "string",
      "reason": "string",
      "options": [
        "string"
      ],
      "default_answer": "string",
      "affects": [
        "string"
      ]
    }
  ],
  "applied_filters": [
    {
      "field": "string",
      "operator": "eq",
      "value": null
    }
  ],
  "tool_calls_made": 0,
  "messages": [
    {
      "role": "user",
      "content": "string",
      "tool_calls": [
        {
          "id": "string",
          "type": "function",
          "function": {
            "name": "string",
            "arguments": "string"
          }
        }
      ],
      "tool_call_id": "string",
      "name": "string"
    }
  ],
  "classification": {
    "route_type": "question",
    "strategy": "simple",
    "semantic_mode": "rewrite",
    "improved_query": "string",
    "semantic_query": "string",
    "step_back_query": "string",
    "sub_questions": [
      "string"
    ],
    "multi_phrases": [
      "string"
    ],
    "reasoning": "string",
    "confidence": 0
  },
  "generation": "string",
  "generation_confidence": 0,
  "context_relevance": 0,
  "followup_questions": [
    "string"
  ],
  "eval_result": {
    "scores": {
      "retrieval": {},
      "generation": {}
    },
    "summary": {
      "average_score": 0,
      "passed": 0,
      "failed": 0,
      "total": 0
    },
    "duration_ms": 0
  }
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

Query a specific table#

POST/tables/{tableName}/query

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "table": "wikipedia",
    "query": {
        "bool": {
            "must": [
                {
                    "match": {
                        "field": "body",
                        "text": "computer"
                    }
                }
            ],
            "filter": [
                {
                    "term": {
                        "path": "/tenant",
                        "value": "acme"
                    }
                }
            ],
            "must_not": [
                {
                    "exists": {
                        "path": "/deleted_at"
                    }
                }
            ]
        }
    },
    "full_text_search": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "full_text_index": "document_text",
    "semantic_search": "artificial intelligence and machine learning applications",
    "embedding_template": "{{remoteMedia url=this}}",
    "indexes": [
        "title_body_nomic",
        "description_embedding"
    ],
    "filter_prefix": "string",
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "exclusion_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "aggregations": {},
    "embeddings": {},
    "search_effort": 0.5,
    "fields": [
        "title",
        "url",
        "summary",
        "created_at"
    ],
    "hierarchy": null,
    "limit": 20,
    "offset": 0,
    "timeout_ms": 5000,
    "order_by": [
        {
            "field": "created_at",
            "desc": true
        },
        {
            "field": "score",
            "desc": true
        }
    ],
    "search_after": [
        null
    ],
    "search_before": [
        null
    ],
    "distance_under": 0.5,
    "distance_over": 0.1,
    "merge_config": {
        "strategy": "rrf",
        "weights": {
            "full_text": 0.3,
            "title_embedding": 1
        },
        "window_size": 1,
        "rank_constant": 0
    },
    "count": false,
    "profile": false,
    "reranker": {
        "provider": "cohere",
        "model": "rerank-v4.0-pro",
        "field": "content"
    },
    "analyses": {
        "pca": true,
        "tsne": true
    },
    "graph_queries": {},
    "document_renderer": "{{encodeToon this.fields}}",
    "pruner": {
        "min_score_ratio": 0.5,
        "max_score_gap_percent": 30,
        "min_absolute_score": 0.01,
        "require_multi_index": true,
        "std_dev_threshold": 1.5
    },
    "join": {
        "right_table": "customers",
        "join_type": "inner",
        "on": {
            "left_field": "customer_id",
            "right_field": "id",
            "operator": "eq"
        },
        "right_filters": {
            "filter_query": {
                "term": "string",
                "field": "string",
                "boost": 0
            },
            "filter_prefix": "string",
            "limit": 0
        },
        "right_fields": [
            "name",
            "email",
            "tier"
        ],
        "strategy_hint": "broadcast",
        "nested_join": "..."
    },
    "foreign_sources": {}
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/query" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table": "wikipedia",
    "query": {
        "bool": {
            "must": [
                {
                    "match": {
                        "field": "body",
                        "text": "computer"
                    }
                }
            ],
            "filter": [
                {
                    "term": {
                        "path": "/tenant",
                        "value": "acme"
                    }
                }
            ],
            "must_not": [
                {
                    "exists": {
                        "path": "/deleted_at"
                    }
                }
            ]
        }
    },
    "full_text_search": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "full_text_index": "document_text",
    "semantic_search": "artificial intelligence and machine learning applications",
    "embedding_template": "{{remoteMedia url=this}}",
    "indexes": [
        "title_body_nomic",
        "description_embedding"
    ],
    "filter_prefix": "string",
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "exclusion_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "aggregations": {},
    "embeddings": {},
    "search_effort": 0.5,
    "fields": [
        "title",
        "url",
        "summary",
        "created_at"
    ],
    "hierarchy": null,
    "limit": 20,
    "offset": 0,
    "timeout_ms": 5000,
    "order_by": [
        {
            "field": "created_at",
            "desc": true
        },
        {
            "field": "score",
            "desc": true
        }
    ],
    "search_after": [
        null
    ],
    "search_before": [
        null
    ],
    "distance_under": 0.5,
    "distance_over": 0.1,
    "merge_config": {
        "strategy": "rrf",
        "weights": {
            "full_text": 0.3,
            "title_embedding": 1
        },
        "window_size": 1,
        "rank_constant": 0
    },
    "count": false,
    "profile": false,
    "reranker": {
        "provider": "cohere",
        "model": "rerank-v4.0-pro",
        "field": "content"
    },
    "analyses": {
        "pca": true,
        "tsne": true
    },
    "graph_queries": {},
    "document_renderer": "{{encodeToon this.fields}}",
    "pruner": {
        "min_score_ratio": 0.5,
        "max_score_gap_percent": 30,
        "min_absolute_score": 0.01,
        "require_multi_index": true,
        "std_dev_threshold": 1.5
    },
    "join": {
        "right_table": "customers",
        "join_type": "inner",
        "on": {
            "left_field": "customer_id",
            "right_field": "id",
            "operator": "eq"
        },
        "right_filters": {
            "filter_query": {
                "term": "string",
                "field": "string",
                "boost": 0
            },
            "filter_prefix": "string",
            "limit": 0
        },
        "right_fields": [
            "name",
            "email",
            "tier"
        ],
        "strategy_hint": "broadcast",
        "nested_join": "..."
    },
    "foreign_sources": {}
}'

const response = await fetch('/db/v1/tables/{tableName}/query', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "wikipedia",
        "query": {
            "bool": {
                "must": [
                    {
                        "match": {
                            "field": "body",
                            "text": "computer"
                        }
                    }
                ],
                "filter": [
                    {
                        "term": {
                            "path": "/tenant",
                            "value": "acme"
                        }
                    }
                ],
                "must_not": [
                    {
                        "exists": {
                            "path": "/deleted_at"
                        }
                    }
                ]
            }
        },
        "full_text_search": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "full_text_index": "document_text",
        "semantic_search": "artificial intelligence and machine learning applications",
        "embedding_template": "{{remoteMedia url=this}}",
        "indexes": [
            "title_body_nomic",
            "description_embedding"
        ],
        "filter_prefix": "string",
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "exclusion_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "aggregations": {},
        "embeddings": {},
        "search_effort": 0.5,
        "fields": [
            "title",
            "url",
            "summary",
            "created_at"
        ],
        "hierarchy": null,
        "limit": 20,
        "offset": 0,
        "timeout_ms": 5000,
        "order_by": [
            {
                "field": "created_at",
                "desc": true
            },
            {
                "field": "score",
                "desc": true
            }
        ],
        "search_after": [
            null
        ],
        "search_before": [
            null
        ],
        "distance_under": 0.5,
        "distance_over": 0.1,
        "merge_config": {
            "strategy": "rrf",
            "weights": {
                "full_text": 0.3,
                "title_embedding": 1
            },
            "window_size": 1,
            "rank_constant": 0
        },
        "count": false,
        "profile": false,
        "reranker": {
            "provider": "cohere",
            "model": "rerank-v4.0-pro",
            "field": "content"
        },
        "analyses": {
            "pca": true,
            "tsne": true
        },
        "graph_queries": {},
        "document_renderer": "{{encodeToon this.fields}}",
        "pruner": {
            "min_score_ratio": 0.5,
            "max_score_gap_percent": 30,
            "min_absolute_score": 0.01,
            "require_multi_index": true,
            "std_dev_threshold": 1.5
        },
        "join": {
            "right_table": "customers",
            "join_type": "inner",
            "on": {
                "left_field": "customer_id",
                "right_field": "id",
                "operator": "eq"
            },
            "right_filters": {
                "filter_query": {
                    "term": "string",
                    "field": "string",
                    "boost": 0
                },
                "filter_prefix": "string",
                "limit": 0
            },
            "right_fields": [
                "name",
                "email",
                "tier"
            ],
            "strategy_hint": "broadcast",
            "nested_join": "..."
        },
        "foreign_sources": {}
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/query', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "wikipedia",
        "query": {
            "bool": {
                "must": [
                    {
                        "match": {
                            "field": "body",
                            "text": "computer"
                        }
                    }
                ],
                "filter": [
                    {
                        "term": {
                            "path": "/tenant",
                            "value": "acme"
                        }
                    }
                ],
                "must_not": [
                    {
                        "exists": {
                            "path": "/deleted_at"
                        }
                    }
                ]
            }
        },
        "full_text_search": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "full_text_index": "document_text",
        "semantic_search": "artificial intelligence and machine learning applications",
        "embedding_template": "{{remoteMedia url=this}}",
        "indexes": [
            "title_body_nomic",
            "description_embedding"
        ],
        "filter_prefix": "string",
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "exclusion_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "aggregations": {},
        "embeddings": {},
        "search_effort": 0.5,
        "fields": [
            "title",
            "url",
            "summary",
            "created_at"
        ],
        "hierarchy": null,
        "limit": 20,
        "offset": 0,
        "timeout_ms": 5000,
        "order_by": [
            {
                "field": "created_at",
                "desc": true
            },
            {
                "field": "score",
                "desc": true
            }
        ],
        "search_after": [
            null
        ],
        "search_before": [
            null
        ],
        "distance_under": 0.5,
        "distance_over": 0.1,
        "merge_config": {
            "strategy": "rrf",
            "weights": {
                "full_text": 0.3,
                "title_embedding": 1
            },
            "window_size": 1,
            "rank_constant": 0
        },
        "count": false,
        "profile": false,
        "reranker": {
            "provider": "cohere",
            "model": "rerank-v4.0-pro",
            "field": "content"
        },
        "analyses": {
            "pca": true,
            "tsne": true
        },
        "graph_queries": {},
        "document_renderer": "{{encodeToon this.fields}}",
        "pruner": {
            "min_score_ratio": 0.5,
            "max_score_gap_percent": 30,
            "min_absolute_score": 0.01,
            "require_multi_index": true,
            "std_dev_threshold": 1.5
        },
        "join": {
            "right_table": "customers",
            "join_type": "inner",
            "on": {
                "left_field": "customer_id",
                "right_field": "id",
                "operator": "eq"
            },
            "right_filters": {
                "filter_query": {
                    "term": "string",
                    "field": "string",
                    "boost": 0
                },
                "filter_prefix": "string",
                "limit": 0
            },
            "right_fields": [
                "name",
                "email",
                "tier"
            ],
            "strategy_hint": "broadcast",
            "nested_join": "..."
        },
        "foreign_sources": {}
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/query',
    headers=headers,
    json={
        "table": "wikipedia",
        "query": {
            "bool": {
                "must": [
                    {
                        "match": {
                            "field": "body",
                            "text": "computer"
                        }
                    }
                ],
                "filter": [
                    {
                        "term": {
                            "path": "/tenant",
                            "value": "acme"
                        }
                    }
                ],
                "must_not": [
                    {
                        "exists": {
                            "path": "/deleted_at"
                        }
                    }
                ]
            }
        },
        "full_text_search": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "full_text_index": "document_text",
        "semantic_search": "artificial intelligence and machine learning applications",
        "embedding_template": "{{remoteMedia url=this}}",
        "indexes": [
            "title_body_nomic",
            "description_embedding"
        ],
        "filter_prefix": "string",
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "exclusion_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "aggregations": {},
        "embeddings": {},
        "search_effort": 0.5,
        "fields": [
            "title",
            "url",
            "summary",
            "created_at"
        ],
        "hierarchy": null,
        "limit": 20,
        "offset": 0,
        "timeout_ms": 5000,
        "order_by": [
            {
                "field": "created_at",
                "desc": true
            },
            {
                "field": "score",
                "desc": true
            }
        ],
        "search_after": [
            null
        ],
        "search_before": [
            null
        ],
        "distance_under": 0.5,
        "distance_over": 0.1,
        "merge_config": {
            "strategy": "rrf",
            "weights": {
                "full_text": 0.3,
                "title_embedding": 1
            },
            "window_size": 1,
            "rank_constant": 0
        },
        "count": false,
        "profile": false,
        "reranker": {
            "provider": "cohere",
            "model": "rerank-v4.0-pro",
            "field": "content"
        },
        "analyses": {
            "pca": true,
            "tsne": true
        },
        "graph_queries": {},
        "document_renderer": "{{encodeToon this.fields}}",
        "pruner": {
            "min_score_ratio": 0.5,
            "max_score_gap_percent": 30,
            "min_absolute_score": 0.01,
            "require_multi_index": true,
            "std_dev_threshold": 1.5
        },
        "join": {
            "right_table": "customers",
            "join_type": "inner",
            "on": {
                "left_field": "customer_id",
                "right_field": "id",
                "operator": "eq"
            },
            "right_filters": {
                "filter_query": {
                    "term": "string",
                    "field": "string",
                    "boost": 0
                },
                "filter_prefix": "string",
                "limit": 0
            },
            "right_fields": [
                "name",
                "email",
                "tier"
            ],
            "strategy_hint": "broadcast",
            "nested_join": "..."
        },
        "foreign_sources": {}
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "table": "wikipedia",
    "query": {
        "bool": {
            "must": [
                {
                    "match": {
                        "field": "body",
                        "text": "computer"
                    }
                }
            ],
            "filter": [
                {
                    "term": {
                        "path": "/tenant",
                        "value": "acme"
                    }
                }
            ],
            "must_not": [
                {
                    "exists": {
                        "path": "/deleted_at"
                    }
                }
            ]
        }
    },
    "full_text_search": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "full_text_index": "document_text",
    "semantic_search": "artificial intelligence and machine learning applications",
    "embedding_template": "{{remoteMedia url=this}}",
    "indexes": [
        "title_body_nomic",
        "description_embedding"
    ],
    "filter_prefix": "string",
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "exclusion_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "aggregations": {},
    "embeddings": {},
    "search_effort": 0.5,
    "fields": [
        "title",
        "url",
        "summary",
        "created_at"
    ],
    "hierarchy": null,
    "limit": 20,
    "offset": 0,
    "timeout_ms": 5000,
    "order_by": [
        {
            "field": "created_at",
            "desc": true
        },
        {
            "field": "score",
            "desc": true
        }
    ],
    "search_after": [
        null
    ],
    "search_before": [
        null
    ],
    "distance_under": 0.5,
    "distance_over": 0.1,
    "merge_config": {
        "strategy": "rrf",
        "weights": {
            "full_text": 0.3,
            "title_embedding": 1
        },
        "window_size": 1,
        "rank_constant": 0
    },
    "count": false,
    "profile": false,
    "reranker": {
        "provider": "cohere",
        "model": "rerank-v4.0-pro",
        "field": "content"
    },
    "analyses": {
        "pca": true,
        "tsne": true
    },
    "graph_queries": {},
    "document_renderer": "{{encodeToon this.fields}}",
    "pruner": {
        "min_score_ratio": 0.5,
        "max_score_gap_percent": 30,
        "min_absolute_score": 0.01,
        "require_multi_index": true,
        "std_dev_threshold": 1.5
    },
    "join": {
        "right_table": "customers",
        "join_type": "inner",
        "on": {
            "left_field": "customer_id",
            "right_field": "id",
            "operator": "eq"
        },
        "right_filters": {
            "filter_query": {
                "term": "string",
                "field": "string",
                "boost": 0
            },
            "filter_prefix": "string",
            "limit": 0
        },
        "right_fields": [
            "name",
            "email",
            "tier"
        ],
        "strategy_hint": "broadcast",
        "nested_join": "..."
    },
    "foreign_sources": {}
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/query", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "responses": [
    {
      "hits": {
        "total": {
          "value": 0,
          "relation": "exact"
        },
        "hits": [
          {
            "_id": "string",
            "_score": 0,
            "_distance": 0,
            "_index_scores": {},
            "_source": {},
            "hierarchy": {
              "level": "source",
              "parent_doc_key": "string",
              "parent_unit_id": "string",
              "artifact": {
                "name": "string",
                "kind": "chunk",
                "chunk_id": 0,
                "unit_id": "string",
                "source": {
                  "name": "string",
                  "kind": "chunk",
                  "chunk_id": 0,
                  "unit_id": "string"
                }
              },
              "matched_artifact": {
                "name": "string",
                "kind": "chunk",
                "chunk_id": 0,
                "unit_id": "string",
                "source": {
                  "name": "string",
                  "kind": "chunk",
                  "chunk_id": 0,
                  "unit_id": "string"
                }
              },
              "ancestors": {
                "source": {
                  "id": "string",
                  "document": {},
                  "key": "string",
                  "artifact_name": "string",
                  "source_field": "string",
                  "provenance": null
                },
                "unit": {
                  "id": "string",
                  "document": {},
                  "key": "string",
                  "artifact_name": "string",
                  "source_field": "string",
                  "provenance": null
                }
              },
              "evidence": {
                "local_id": "string",
                "decision": "string",
                "confidence": 0,
                "source_artifact": "string",
                "source_artifact_key": "string",
                "resolution_artifact": "string",
                "resolution_artifact_key": "string",
                "resolver": "string",
                "resolver_table": "string",
                "mention": {},
                "canonical": {}
              },
              "matches": [
                {
                  "_id": "string",
                  "_score": 0,
                  "_distance": 0,
                  "_source": {},
                  "hierarchy": {
                    "level": "source",
                    "parent_doc_key": "string",
                    "parent_unit_id": "string",
                    "artifact": {
                      "name": "string",
                      "kind": "chunk",
                      "chunk_id": 0,
                      "unit_id": "string",
                      "source": {
                        "name": "string",
                        "kind": "chunk",
                        "chunk_id": 0,
                        "unit_id": "string"
                      }
                    },
                    "ancestors": {
                      "source": {
                        "id": "string",
                        "document": {},
                        "key": "string",
                        "artifact_name": "string",
                        "source_field": "string",
                        "provenance": null
                      },
                      "unit": {
                        "id": "string",
                        "document": {},
                        "key": "string",
                        "artifact_name": "string",
                        "source_field": "string",
                        "provenance": null
                      }
                    }
                  }
                }
              ],
              "position": "string",
              "revision": "string",
              "chunks": [
                {
                  "_id": "string",
                  "_score": 0,
                  "_distance": 0,
                  "_source": {},
                  "hierarchy": {
                    "level": "source",
                    "parent_doc_key": "string",
                    "parent_unit_id": "string",
                    "artifact": {
                      "name": "string",
                      "kind": "chunk",
                      "chunk_id": 0,
                      "unit_id": "string",
                      "source": {
                        "name": "string",
                        "kind": "chunk",
                        "chunk_id": 0,
                        "unit_id": "string"
                      }
                    },
                    "ancestors": {
                      "source": {
                        "id": "string",
                        "document": {},
                        "key": "string",
                        "artifact_name": "string",
                        "source_field": "string",
                        "provenance": null
                      },
                      "unit": {
                        "id": "string",
                        "document": {},
                        "key": "string",
                        "artifact_name": "string",
                        "source_field": "string",
                        "provenance": null
                      }
                    }
                  }
                }
              ]
            },
            "_sort": [
              null
            ]
          }
        ],
        "max_score": 0
      },
      "aggregations": {},
      "analyses": {},
      "profile": {
        "shards": {
          "total": 0,
          "successful": 0,
          "failed": 0
        },
        "join": {
          "strategy_used": "broadcast",
          "left_rows_scanned": 0,
          "right_rows_scanned": 0,
          "rows_matched": 0,
          "rows_unmatched_left": 0,
          "rows_unmatched_right": 0,
          "duration_ms": 0
        },
        "reranker": {
          "provider": "antfly",
          "model": "string",
          "documents_reranked": 0,
          "duration_ms": 0
        },
        "merge": {
          "strategy": "rrf",
          "full_text_hits": 0,
          "semantic_hits": 0,
          "duration_ms": 0
        },
        "sort": {
          "plan": "string",
          "order_by": [
            {
              "field": "string",
              "desc": true
            }
          ],
          "cursor": "string",
          "exactness": "string",
          "source": "string",
          "candidate_source": "none",
          "cursor_support": "string",
          "source_load": "string",
          "distributed_behavior": "string",
          "selection_reason": "string",
          "require_native": true,
          "sort_lifecycle_state": "unsupported",
          "index_sort_coverage": "string",
          "candidate_count": 0,
          "cursor_rejected_count": 0,
          "selected_count": 0,
          "total_us": 0,
          "distributed_shard_count": 0,
          "budget_rejection_reason": "string",
          "sort_rejection_reason": "string",
          "sort_rejection_detail": "string",
          "sort_rejection_field": "string"
        }
      },
      "took": 0,
      "status": 0,
      "error": "string",
      "table": "string"
    }
  ]
}