Properties
| Name | Type | Description |
|---|---|---|
| session_id | string | Correlation identifier for a bounded agent interaction. In Phase 1 this is echoed back to the client but does not imply server-side session persistence. |
| decisions | array | Structured answers provided by the user as part of client-carried continuation. |
| interactive | boolean | If true, the agent may return clarification questions when needed. |
| max_internal_iterations | integer | Maximum planning tool calls (0-20). Zero uses the compatibility planner. A positive value enables model-directed table inspection and complete QueryRequest submission using the canonical DSL parser an |
| max_user_clarifications | integer | Maximum number of clarification turns the agent may request from the user. |
| require_decision_after | integer | Force a user-facing decision after this many unresolved internal passes. |
| example_documents | array | Optional example documents to help the query builder infer field shapes and representative values. When omitted and the table has data but no schema, the server samples up to one document automaticall |
| table | string | Name of the table to build query for. If provided, uses table schema for field context. |
| intent | string | Natural language description of the search intent |
| schema_fields | array | List of searchable field names to consider. Overrides table schema if provided. |
| mode | string | Optional strategy hint for the coordinator. Suggested values are `auto`, `full_text`, `semantic`, `hybrid`, `filter`, `tree`, and `graph`. Unknown values are accepted for forward compatibility and may |
| output | string | Preferred output artifact. Suggested values are `query_request`, `bleve` (Antfly's native, Bleve-compatible full-text query JSON), and `filter_query`. The compatibility `query` field is still returned |
| constraints | object | Optional execution constraints for the coordinator, such as `limit`, `allowed_fields`, `prefer_indexes`, and `require_executable`. |
| generator | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/antfly/json-schema/antfly-query-builder-request-schema.json",
"title": "QueryBuilderRequest",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/antfly-query-operations-api-openapi.yml#/components/schemas/QueryBuilderRequest",
"type": "object",
"required": [
"intent"
],
"properties": {
"session_id": {
"type": "string",
"description": "Correlation identifier for a bounded agent interaction. In Phase 1 this is echoed back to the client but does not imply server-side session persistence."
},
"decisions": {
"type": "array",
"items": {
"$ref": "#/$defs/AgentDecision"
},
"description": "Structured answers provided by the user as part of client-carried continuation."
},
"interactive": {
"type": "boolean",
"default": true,
"description": "If true, the agent may return clarification questions when needed."
},
"max_internal_iterations": {
"type": "integer",
"minimum": 0,
"maximum": 20,
"description": "Maximum planning tool calls (0-20). Zero uses the compatibility planner. A positive value enables model-directed table inspection and complete QueryRequest submission using the canonical DSL parser and runtime preflight, with validation feedback for repair. It requires an Antfly or OpenAI tool-capable generator and never executes database searches."
},
"max_user_clarifications": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Maximum number of clarification turns the agent may request from the user."
},
"require_decision_after": {
"type": "integer",
"minimum": 0,
"maximum": 20,
"description": "Force a user-facing decision after this many unresolved internal passes."
},
"example_documents": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Optional example documents to help the query builder infer field shapes and representative values. When omitted and the table has data but no schema, the server samples up to one document automatically."
},
"table": {
"type": "string",
"description": "Name of the table to build query for. If provided, uses table schema for field context."
},
"intent": {
"type": "string",
"description": "Natural language description of the search intent"
},
"schema_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of searchable field names to consider. Overrides table schema if provided."
},
"mode": {
"type": "string",
"description": "Optional strategy hint for the coordinator. Suggested values are `auto`, `full_text`,\n`semantic`, `hybrid`, `filter`, `tree`, and `graph`. Unknown values are accepted for\nforward compatibility and may fall back to `auto`.\n"
},
"output": {
"type": "string",
"description": "Preferred output artifact. Suggested values are `query_request`, `bleve` (Antfly's\nnative, Bleve-compatible full-text query JSON), and `filter_query`. The compatibility\n`query` field is still returned for existing clients.\n"
},
"constraints": {
"type": "object",
"additionalProperties": true,
"description": "Optional execution constraints for the coordinator, such as `limit`, `allowed_fields`,\n`prefer_indexes`, and `require_executable`.\n"
},
"generator": {
"$ref": "#/$defs/GeneratorConfig"
}
},
"$defs": {
"AgentDecision": {
"type": "object",
"required": [
"question_id"
],
"properties": {
"question_id": {
"type": "string",
"description": "The question being answered"
},
"answer": {
"description": "User answer, scalar or structured depending on the question kind"
},
"approved": {
"type": "boolean",
"description": "Used for confirm/review steps where the draft may be accepted as-is"
}
}
},
"AntflyGeneratorConfig": {
"type": "object",
"description": "Configuration for the Antfly inference generative AI provider.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"antfly"
]
},
"model": {
"type": "string",
"description": "The name of the generator model."
},
"api_url": {
"type": "string",
"format": "uri",
"description": "The URL of the Inference API endpoint. Can also be set via ANTFLY_INFERENCE_URL environment variable."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-2.0).",
"minimum": 0.0,
"maximum": 2.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter.",
"minimum": 0.0,
"maximum": 1.0
},
"top_k": {
"type": "integer",
"description": "Top-k sampling parameter."
},
"timeout": {
"type": "integer",
"description": "HTTP response timeout in seconds for Inference API calls.",
"minimum": 1
}
},
"required": [
"provider",
"model"
]
},
"AnthropicGeneratorConfig": {
"type": "object",
"description": "Configuration for the Anthropic generative AI provider.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic"
]
},
"workspace_id": {
"type": "string",
"description": "Anthropic workspace for keys not scoped to a workspace. Defaults to ANTHROPIC_WORKSPACE_ID."
},
"model": {
"type": "string",
"description": "The full model ID of the Anthropic model to use.",
"default": "claude-sonnet-4-5-20250929"
},
"api_key": {
"type": "string",
"writeOnly": true,
"description": "Anthropic API key or secret reference. Defaults to ANTHROPIC_API_KEY."
},
"url": {
"type": "string",
"format": "uri",
"description": "Messages API base URL. Defaults to https://api.anthropic.com/v1."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-1.0).",
"minimum": 0.0,
"maximum": 1.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate in the response."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter (0.0-1.0).",
"minimum": 0.0,
"maximum": 1.0
},
"top_k": {
"type": "integer",
"description": "Top-k sampling parameter."
}
},
"required": [
"provider",
"model"
]
},
"AppleGeneratorConfig": {
"type": "object",
"description": "On-device Apple Foundation Models generation. Requires a macOS Apple provider build, Apple Intelligence enabled, and its system model ready. Supports text conversations; tool calling and media attachments are not supported.",
"properties": {
"provider": {
"type": "string",
"enum": [
"apple"
]
},
"max_tokens": {
"type": "integer",
"minimum": 1,
"default": 256
},
"temperature": {
"type": "number",
"minimum": 0,
"maximum": 2
}
}
},
"BedrockGeneratorConfig": {
"type": "object",
"description": "AWS Bedrock Converse generation, including image inputs and tools for\nmodels that support them. Uses the AWS default credential chain unless\nan explicit Bedrock API key is configured. Image capability is declared\nper target through inference_capabilities; model IDs are not allowlisted.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"bedrock"
]
},
"url": {
"type": "string",
"description": "Optional Bedrock Runtime endpoint override. Defaults to the regional AWS endpoint."
},
"api_key": {
"type": "string",
"description": "Optional Bedrock bearer API key or secret reference. Omit to use signed AWS requests and the default credential chain."
},
"model": {
"type": "string",
"description": "The Bedrock model ID to use."
},
"region": {
"type": "string",
"description": "AWS region. Defaults to AWS_REGION, then AWS_DEFAULT_REGION, then us-east-1."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-1.0).",
"minimum": 0.0,
"maximum": 1.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter.",
"minimum": 0.0,
"maximum": 1.0
}
},
"required": [
"provider",
"model"
]
},
"ChatGPTGeneratorConfig": {
"type": "object",
"description": "Personal ChatGPT plan for interactive generation. Credentials stay in the local runtime.",
"required": [
"provider",
"model",
"connection_id"
],
"properties": {
"provider": {
"type": "string",
"enum": [
"chatgpt"
]
},
"reasoning_effort": {
"$ref": "#/$defs/OpenAIReasoningEffort"
},
"model": {
"type": "string"
},
"connection_id": {
"type": "string",
"description": "Opaque personal registration owned by the authenticated caller."
}
}
},
"CloudflareGeneratorConfig": {
"type": "object",
"description": "Cloudflare Workers AI generation. Uses CLOUDFLARE_API_TOKEN or an Antfly secret reference.",
"properties": {
"provider": {
"type": "string",
"enum": [
"cloudflare"
]
},
"account_id": {
"type": "string",
"minLength": 1
},
"gateway_id": {
"type": "string",
"minLength": 1,
"description": "Optional AI Gateway ID, sent through cf-aig-gateway-id."
},
"model": {
"type": "string",
"default": "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
},
"api_key": {
"type": "string",
"writeOnly": true
},
"url": {
"type": "string",
"description": "Optional deployment-owned endpoint override."
},
"max_tokens": {
"type": "integer",
"minimum": 1
},
"temperature": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 2
},
"top_p": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
},
"frequency_penalty": {
"type": "number",
"format": "float",
"minimum": -2,
"maximum": 2
},
"presence_penalty": {
"type": "number",
"format": "float",
"minimum": -2,
"maximum": 2
}
},
"required": [
"provider",
"account_id",
"model"
]
},
"GeneratorConfig": {
"description": "A unified configuration for a generative AI provider.\n",
"allOf": [
{
"oneOf": [
{
"$ref": "#/$defs/CloudflareGeneratorConfig"
},
{
"$ref": "#/$defs/GoogleGeneratorConfig"
},
{
"$ref": "#/$defs/VertexGeneratorConfig"
},
{
"$ref": "#/$defs/BedrockGeneratorConfig"
},
{
"$ref": "#/$defs/AnthropicGeneratorConfig"
},
{
"$ref": "#/$defs/OllamaGeneratorConfig"
},
{
"$ref": "#/$defs/AntflyGeneratorConfig"
},
{
"$ref": "#/$defs/ChatGPTGeneratorConfig"
},
{
"$ref": "#/$defs/OpenAIGeneratorConfig"
},
{
"$ref": "#/$defs/OpenRouterGeneratorConfig"
},
{
"$ref": "#/$defs/AppleGeneratorConfig"
}
]
},
{
"properties": {
"max_image_input_tokens": {
"x-go-type-skip-optional-pointer": false,
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Conservative input-token ceiling per image. Required for image calls when tokens_per_minute is configured; choose a bound valid for the model and image policy."
},
"rate_limit": {
"x-go-type-skip-optional-pointer": false,
"$ref": "#/$defs/RateLimitConfig"
},
"provider": {
"$ref": "#/$defs/GeneratorProvider"
}
},
"required": [
"provider"
]
}
]
},
"GeneratorProvider": {
"type": "string",
"enum": [
"cloudflare",
"gemini",
"vertex",
"bedrock",
"anthropic",
"ollama",
"openai",
"chatgpt",
"openrouter",
"antfly",
"apple"
],
"description": "Generator providers implemented by Antfly's generation runtime."
},
"GoogleGeneratorConfig": {
"type": "object",
"description": "Configuration for the Google generative AI provider (Gemini).\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"gemini"
]
},
"project_id": {
"type": "string",
"description": "The Google Cloud project ID."
},
"location": {
"type": "string",
"description": "The Google Cloud location (e.g., 'us-central1')."
},
"model": {
"type": "string",
"description": "The name of the generative model to use.",
"default": "gemini-2.5-flash"
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-2.0).",
"minimum": 0.0,
"maximum": 2.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter.",
"minimum": 0.0,
"maximum": 1.0
},
"top_k": {
"type": "integer",
"description": "Top-k sampling parameter."
},
"api_key": {
"type": "string",
"writeOnly": true,
"description": "The Google API key."
},
"url": {
"type": "string",
"format": "uri",
"description": "The URL of the Google API endpoint."
}
},
"required": [
"provider",
"model"
]
},
"OllamaGeneratorConfig": {
"type": "object",
"description": "Configuration for the Ollama generative AI provider.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"ollama"
]
},
"model": {
"type": "string",
"description": "The name of the Ollama model to use."
},
"url": {
"type": "string",
"format": "uri",
"description": "The URL of the Ollama API endpoint."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-2.0).",
"minimum": 0.0,
"maximum": 2.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter.",
"minimum": 0.0,
"maximum": 1.0
},
"top_k": {
"type": "integer",
"description": "Top-k sampling parameter."
},
"timeout": {
"type": "integer",
"description": "HTTP response timeout in seconds for Ollama API calls.",
"minimum": 1
}
},
"required": [
"provider",
"model"
]
},
"OpenAIGeneratorConfig": {
"type": "object",
"description": "Configuration for the OpenAI generative AI provider.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"openai"
]
},
"model": {
"type": "string",
"description": "The name of the OpenAI model to use.",
"default": "gpt-4.1"
},
"url": {
"type": "string",
"format": "uri",
"description": "The URL of the OpenAI API endpoint."
},
"api_key": {
"type": "string",
"writeOnly": true,
"description": "The OpenAI API key."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-2.0).",
"minimum": 0.0,
"maximum": 2.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate."
},
"max_completion_tokens": {
"type": "integer",
"minimum": 1,
"description": "OpenAI completion budget, including visible output and reasoning tokens.\nUse for reasoning models instead of max_tokens; the two are mutually exclusive.\n"
},
"reasoning_effort": {
"$ref": "#/$defs/OpenAIReasoningEffort",
"description": "Optional reasoning effort. Supported values depend on the selected OpenAI model."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter.",
"minimum": 0.0,
"maximum": 1.0
},
"frequency_penalty": {
"type": "number",
"format": "float",
"description": "Penalty for token frequency (-2.0 to 2.0).",
"minimum": -2.0,
"maximum": 2.0
},
"presence_penalty": {
"type": "number",
"format": "float",
"description": "Penalty for token presence (-2.0 to 2.0).",
"minimum": -2.0,
"maximum": 2.0
}
},
"required": [
"provider",
"model"
]
},
"OpenAIReasoningEffort": {
"type": "string",
"enum": [
"none",
"minimal",
"low",
"medium",
"high",
"xhigh",
"max"
],
"description": "OpenAI reasoning effort; model support varies. Omit to use the model default."
},
"OpenRouterGeneratorConfig": {
"type": "object",
"description": "Configuration for the OpenRouter generative AI provider.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"openrouter"
]
},
"model": {
"type": "string",
"description": "The OpenRouter model identifier to use."
},
"url": {
"type": "string",
"format": "uri",
"description": "The URL of the OpenRouter API endpoint.",
"default": "https://openrouter.ai/api/v1"
},
"api_key": {
"type": "string",
"writeOnly": true,
"description": "The OpenRouter API key."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-2.0).",
"minimum": 0.0,
"maximum": 2.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate in the response."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter (0.0-1.0).",
"minimum": 0.0,
"maximum": 1.0
},
"frequency_penalty": {
"type": "number",
"format": "float",
"description": "Penalty for token frequency (-2.0 to 2.0).",
"minimum": -2.0,
"maximum": 2.0
},
"presence_penalty": {
"type": "number",
"format": "float",
"description": "Penalty for token presence (-2.0 to 2.0).",
"minimum": -2.0,
"maximum": 2.0
}
},
"required": [
"provider",
"model"
]
},
"RateLimitConfig": {
"type": "object",
"x-go-type-skip-optional-pointer": false,
"additionalProperties": false,
"description": "Outbound provider limits shared within one Antfly process by effective\nendpoint, operation, model, credential source, project and region/location.\nConflicting policies for an active scope are rejected. These limits do\nnot coordinate across replicas or infer the provider's account quota.\n",
"properties": {
"pacing": {
"$ref": "#/$defs/RequestPacing",
"description": "Request pacing mode. Defaults to token_bucket. Legacy flat embedder RPM with burst=1 uses completion pacing."
},
"requests_per_minute": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 4294967295
},
"burst": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 4294967295,
"default": 1
},
"tokens_per_minute": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Conservative text budget: each HTTP attempt reserves its serialized\nUTF-8 body byte count plus the configured generation output cap.\nReservations are not refunded. A request larger than this budget\nis rejected. This is not provider billing token accounting; media\nrequests are not supported with this limit.\n"
},
"max_concurrency": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 4294967295,
"description": "Maximum in-flight HTTP attempts, held through response completion."
}
}
},
"RequestPacing": {
"type": "string",
"enum": [
"token_bucket",
"completion"
],
"description": "token_bucket limits admission rate while allowing overlapping attempts.\ncompletion serializes attempts and waits one RPM interval after each\nattempt finishes, including streamed writes and transport failures.\nThis prevents delayed connection setup from compressing successful\nrequest spacing, at the cost of response latency plus one interval per\nrequest. Requires requests_per_minute and burst=1. Neither mode can\nguarantee zero upstream 429s or coordinate other processes.\n"
},
"VertexGeneratorConfig": {
"type": "object",
"description": "Configuration for Google Cloud Vertex AI generative models.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"vertex"
]
},
"model": {
"type": "string",
"description": "The name of the Vertex AI model to use.",
"default": "gemini-2.5-flash"
},
"project_id": {
"type": "string",
"description": "Google Cloud project ID."
},
"location": {
"type": "string",
"description": "Google Cloud region for Vertex AI API.",
"default": "us-central1"
},
"credentials_path": {
"type": "string",
"writeOnly": true,
"description": "Path to service account JSON key file."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-2.0).",
"minimum": 0.0,
"maximum": 2.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate in the response."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter (0.0-1.0).",
"minimum": 0.0,
"maximum": 1.0
},
"top_k": {
"type": "integer",
"description": "Top-k sampling parameter."
}
},
"required": [
"provider",
"model"
]
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/antfly-query-builder-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.