Antfly · Schema

RetrievalAgentResult

Result from the retrieval agent

Artificial IntelligenceSearchRetrievalVectorsHybrid

Properties

Name Type Description
id string Unique response ID for logging and tracing
model string LLM model used for generation
created_at integer Unix timestamp (seconds) when the response was created
status object Current status of the bounded agent execution
incomplete_details object Present when status is "incomplete" — explains why
usage object Token usage and resource statistics from this execution
hits array Retrieved query hits
steps array Shared bounded-agent execution trace for this retrieval run.
strategy_used object Primary strategy that was used (optional in agentic mode)
session_id string Correlation identifier for client-carried continuation.
iteration integer Current internal iteration count for this bounded session.
clarification_count integer Number of user clarification turns already consumed in this session.
remaining_internal_iterations integer Remaining internal reasoning/tool-use iterations for this session.
remaining_user_clarifications integer Remaining clarification turns allowed for this session.
questions array Clarification questions exposed in the shared bounded-agent envelope.
applied_filters array Filters that were applied during retrieval
tool_calls_made integer Total number of tool calls made during retrieval
messages array Optional conversational context including tool calls and responses. Decisions remain the authoritative continuation input for bounded agent interactions.
classification object Query classification and transformation result. Present when steps.classification was configured. Includes strategy, semantic_query, sub_questions (decompose), step_back_query, and reasoning.
generation string Generated response in markdown format. Present when steps.generation was configured.
generation_confidence number Confidence in the generated response (requires steps.confidence)
context_relevance number Relevance of retrieved documents to the query (requires steps.confidence)
followup_questions array Suggested follow-up questions (requires steps.followup)
eval_result object Evaluation results when steps.eval was configured
View JSON Schema on GitHub

JSON Schema

antfly-retrieval-agent-result-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/antfly/json-schema/antfly-retrieval-agent-result-schema.json",
  "title": "RetrievalAgentResult",
  "description": "Result from the retrieval agent",
  "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/RetrievalAgentResult",
  "type": "object",
  "required": [
    "hits",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique response ID for logging and tracing"
    },
    "model": {
      "type": "string",
      "description": "LLM model used for generation"
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp (seconds) when the response was created"
    },
    "status": {
      "$ref": "#/$defs/AgentStatus",
      "description": "Current status of the bounded agent execution"
    },
    "incomplete_details": {
      "$ref": "#/$defs/IncompleteDetails",
      "description": "Present when status is \"incomplete\" — explains why"
    },
    "usage": {
      "$ref": "#/$defs/RetrievalAgentUsage",
      "description": "Token usage and resource statistics from this execution"
    },
    "hits": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/QueryHit"
      },
      "description": "Retrieved query hits"
    },
    "steps": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentStep"
      },
      "description": "Shared bounded-agent execution trace for this retrieval run."
    },
    "strategy_used": {
      "$ref": "#/$defs/RetrievalStrategy",
      "description": "Primary strategy that was used (optional in agentic mode)"
    },
    "session_id": {
      "type": "string",
      "description": "Correlation identifier for client-carried continuation."
    },
    "iteration": {
      "type": "integer",
      "description": "Current internal iteration count for this bounded session."
    },
    "clarification_count": {
      "type": "integer",
      "description": "Number of user clarification turns already consumed in this session."
    },
    "remaining_internal_iterations": {
      "type": "integer",
      "description": "Remaining internal reasoning/tool-use iterations for this session."
    },
    "remaining_user_clarifications": {
      "type": "integer",
      "description": "Remaining clarification turns allowed for this session."
    },
    "questions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentQuestion"
      },
      "description": "Clarification questions exposed in the shared bounded-agent envelope."
    },
    "applied_filters": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FilterSpec"
      },
      "description": "Filters that were applied during retrieval"
    },
    "tool_calls_made": {
      "type": "integer",
      "description": "Total number of tool calls made during retrieval"
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChatMessage"
      },
      "description": "Optional conversational context including tool calls and responses.\nDecisions remain the authoritative continuation input for bounded agent interactions.\n"
    },
    "classification": {
      "$ref": "#/$defs/ClassificationTransformationResult",
      "description": "Query classification and transformation result. Present when\nsteps.classification was configured. Includes strategy, semantic_query,\nsub_questions (decompose), step_back_query, and reasoning.\n"
    },
    "generation": {
      "type": "string",
      "description": "Generated response in markdown format. Present when steps.generation\nwas configured.\n"
    },
    "generation_confidence": {
      "type": "number",
      "format": "float",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Confidence in the generated response (requires steps.confidence)"
    },
    "context_relevance": {
      "type": "number",
      "format": "float",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Relevance of retrieved documents to the query (requires steps.confidence)"
    },
    "followup_questions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Suggested follow-up questions (requires steps.followup)"
    },
    "eval_result": {
      "$ref": "#/$defs/EvalResult",
      "description": "Evaluation results when steps.eval was configured"
    }
  },
  "$defs": {
    "AgentQuestion": {
      "type": "object",
      "required": [
        "id",
        "kind",
        "question"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable question identifier for client-carried continuation"
        },
        "kind": {
          "$ref": "#/$defs/AgentQuestionKind"
        },
        "question": {
          "type": "string",
          "description": "The clarifying question to ask the user"
        },
        "reason": {
          "type": "string",
          "description": "Why clarification is needed"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optional list of choices for the user"
        },
        "default_answer": {
          "type": "string",
          "description": "Suggested default answer when the server has a preferred choice"
        },
        "affects": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "High-level result areas affected by this decision"
        }
      }
    },
    "AgentQuestionKind": {
      "type": "string",
      "enum": [
        "confirm",
        "single_choice",
        "multi_choice",
        "free_text",
        "field_policy"
      ],
      "description": "UI rendering/answer handling hint for a bounded agent question"
    },
    "AgentStatus": {
      "type": "string",
      "enum": [
        "clarification_required",
        "completed",
        "in_progress",
        "incomplete",
        "failed"
      ],
      "description": "Shared bounded-agent execution status"
    },
    "AgentStep": {
      "type": "object",
      "description": "A step in the shared bounded-agent execution trace",
      "required": [
        "name",
        "action"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique step ID for correlation and tracing"
        },
        "kind": {
          "$ref": "#/$defs/AgentStepKind"
        },
        "name": {
          "type": "string",
          "description": "Stable step name used for correlation across JSON and SSE surfaces"
        },
        "action": {
          "type": "string",
          "description": "What action was taken"
        },
        "status": {
          "$ref": "#/$defs/AgentStepStatus"
        },
        "error_message": {
          "type": "string",
          "description": "Error details when status is \"error\""
        },
        "duration_ms": {
          "type": "integer",
          "description": "Server-side execution time in milliseconds"
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional details about the step"
        }
      }
    },
    "AgentStepKind": {
      "type": "string",
      "enum": [
        "tool_call",
        "planning",
        "classification",
        "generation",
        "validation",
        "clarification"
      ],
      "description": "Shared bounded-agent step category"
    },
    "AgentStepStatus": {
      "type": "string",
      "enum": [
        "success",
        "error",
        "skipped"
      ],
      "description": "Outcome of a shared agent step"
    },
    "ChatMessage": {
      "type": "object",
      "description": "OpenAI-compatible message in a generation/chat conversation.",
      "required": [
        "role"
      ],
      "properties": {
        "extra_content": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque provider message metadata. Preserve unchanged when replaying assistant messages; native Anthropic content retains signed thinking blocks."
        },
        "role": {
          "$ref": "#/$defs/ChatMessageRole"
        },
        "content": {
          "$ref": "#/$defs/ChatMessageContent"
        },
        "tool_calls": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ToolCall"
          },
          "description": "Tool calls made by the assistant (only for role=assistant)."
        },
        "tool_call_id": {
          "type": "string",
          "description": "ID of the tool call this message responds to (only for role=tool)."
        },
        "name": {
          "type": "string",
          "description": "Optional tool name for tool messages when model templates need it."
        }
      }
    },
    "ChatMessageContent": {
      "x-go-type": "stdjson.RawMessage",
      "x-go-type-import": {
        "path": "encoding/json",
        "name": "stdjson"
      },
      "description": "Message content. Supports two formats:\n- Simple string: \"Hello, how are you?\"\n- Array of content parts: [{\"type\": \"text\", \"text\": \"Hello\"}]\n",
      "oneOf": [
        {
          "type": "string",
          "description": "Simple text content."
        },
        {
          "type": "array",
          "description": "Array of multimodal content parts.",
          "items": {
            "$ref": "#/$defs/ContentPart"
          }
        }
      ]
    },
    "ChatMessageRole": {
      "type": "string",
      "enum": [
        "user",
        "assistant",
        "system",
        "tool"
      ],
      "description": "Role of the message sender in a generation/chat conversation"
    },
    "ClassificationTransformationResult": {
      "type": "object",
      "description": "Query classification and transformation result combining all query enhancements including strategy selection and semantic optimization",
      "required": [
        "route_type",
        "improved_query",
        "semantic_query",
        "semantic_mode",
        "strategy",
        "confidence"
      ],
      "properties": {
        "route_type": {
          "x-go-type-skip-optional-pointer": true,
          "$ref": "#/$defs/RouteType"
        },
        "strategy": {
          "x-go-type-skip-optional-pointer": true,
          "$ref": "#/$defs/QueryStrategy"
        },
        "semantic_mode": {
          "x-go-type-skip-optional-pointer": true,
          "$ref": "#/$defs/SemanticQueryMode"
        },
        "improved_query": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "description": "Clarified query with added context for answer generation (human-readable)"
        },
        "semantic_query": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "description": "Optimized query for vector/semantic search. Content style depends on semantic_mode: keywords for 'rewrite', hypothetical answer for 'hypothetical'"
        },
        "step_back_query": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "description": "Broader background query for context (only present when strategy is 'step_back')"
        },
        "sub_questions": {
          "x-go-type-skip-optional-pointer": true,
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Decomposed sub-questions (only present when strategy is 'decompose')"
        },
        "multi_phrases": {
          "x-go-type-skip-optional-pointer": true,
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Alternative phrasings of the query for expanded retrieval coverage"
        },
        "reasoning": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "description": "Pre-retrieval reasoning explaining query analysis and strategy selection (only present when with_classification_reasoning is enabled)"
        },
        "confidence": {
          "x-go-type-skip-optional-pointer": true,
          "type": "number",
          "format": "float",
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Classification confidence (0.0 to 1.0)"
        }
      }
    },
    "ContentPart": {
      "description": "A content part for multimodal input (text, image URL, or inline media).",
      "oneOf": [
        {
          "$ref": "#/$defs/TextContentPart"
        },
        {
          "$ref": "#/$defs/ImageURLContentPart"
        },
        {
          "$ref": "#/$defs/MediaContentPart"
        }
      ]
    },
    "EvalResult": {
      "type": "object",
      "description": "Complete evaluation result",
      "properties": {
        "scores": {
          "$ref": "#/$defs/EvalScores",
          "description": "Scores organized by category"
        },
        "summary": {
          "$ref": "#/$defs/EvalSummary",
          "description": "Aggregate statistics"
        },
        "duration_ms": {
          "type": "integer",
          "description": "Total evaluation duration in milliseconds"
        }
      }
    },
    "EvalScores": {
      "type": "object",
      "description": "Scores organized by category",
      "properties": {
        "retrieval": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/EvaluatorScore"
          },
          "description": "Retrieval metric scores (recall, precision, ndcg, etc.)"
        },
        "generation": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/EvaluatorScore"
          },
          "description": "Generation quality scores (faithfulness, relevance, etc.)"
        }
      }
    },
    "EvalSummary": {
      "type": "object",
      "description": "Aggregate statistics across all evaluators",
      "properties": {
        "average_score": {
          "type": "number",
          "format": "float",
          "description": "Average score across all evaluators"
        },
        "passed": {
          "type": "integer",
          "description": "Number of evaluators that passed"
        },
        "failed": {
          "type": "integer",
          "description": "Number of evaluators that failed"
        },
        "total": {
          "type": "integer",
          "description": "Total number of evaluators run"
        }
      }
    },
    "EvaluatorScore": {
      "type": "object",
      "description": "Result from a single evaluator",
      "properties": {
        "score": {
          "type": "number",
          "format": "float",
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Numeric score (0-1)"
        },
        "pass": {
          "type": "boolean",
          "description": "Whether the evaluation passed the threshold"
        },
        "reason": {
          "type": "string",
          "description": "Human-readable explanation of the result"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional evaluator-specific data"
        }
      }
    },
    "FilterSpec": {
      "type": "object",
      "description": "A filter specification to apply to search queries",
      "required": [
        "field",
        "operator",
        "value"
      ],
      "properties": {
        "field": {
          "type": "string",
          "description": "Field name to filter on"
        },
        "operator": {
          "type": "string",
          "enum": [
            "eq",
            "ne",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "prefix",
            "range",
            "in"
          ],
          "description": "Filter operator:\n- eq: Equals\n- ne: Not equals\n- gt/gte: Greater than (or equal)\n- lt/lte: Less than (or equal)\n- contains: Contains substring\n- prefix: Starts with\n- range: Between two values (value should be array [min, max])\n- in: Value in list (value should be array)\n"
        },
        "value": {
          "description": "Filter value (string, number, boolean, or array for range/in operators)"
        }
      }
    },
    "GraphMetricRerankScoreDetails": {
      "type": "object",
      "required": [
        "index_name",
        "metric_name",
        "base_score",
        "base_weight",
        "metric_score_used",
        "metric_weight",
        "missing_score_used",
        "final_score",
        "published_generation"
      ],
      "properties": {
        "index_name": {
          "type": "string",
          "description": "Graph index that provided the metric score."
        },
        "metric_name": {
          "type": "string",
          "description": "Graph metric used as a score feature."
        },
        "base_score": {
          "type": "number",
          "format": "double",
          "description": "Hit score before graph metric rerank composition."
        },
        "base_weight": {
          "type": "number",
          "format": "double",
          "description": "Weight applied to the base score."
        },
        "metric_score": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "Published metric score for this hit, or null when the hit was missing from the metric generation."
        },
        "metric_score_used": {
          "type": "number",
          "format": "double",
          "description": "Metric feature value used in the formula after applying missing_score fallback if needed."
        },
        "metric_weight": {
          "type": "number",
          "format": "double",
          "description": "Weight applied to the metric score feature."
        },
        "missing_score_used": {
          "type": "boolean",
          "description": "True when metric_score was missing and the request's missing_score fallback was used."
        },
        "final_score": {
          "type": "number",
          "format": "double",
          "description": "Final hit score after graph metric rerank composition."
        },
        "published_generation": {
          "type": "integer",
          "format": "int64",
          "description": "Published graph metric score generation used for this hit."
        }
      }
    },
    "HierarchyAncestor": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "id": {
          "type": "string"
        },
        "document": {
          "type": "object",
          "additionalProperties": true
        },
        "key": {
          "type": "string"
        },
        "artifact_name": {
          "type": "string"
        },
        "source_field": {
          "type": "string"
        },
        "provenance": {}
      }
    },
    "HierarchyArtifact": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "kind"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "chunk",
            "asset",
            "embedding"
          ]
        },
        "chunk_id": {
          "type": "integer",
          "format": "uint32",
          "x-go-type-skip-optional-pointer": false
        },
        "window_index": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Independent media output sub-window within the parent chunk; omitted for an unsplit vector.",
          "x-go-type-skip-optional-pointer": false
        },
        "unit_id": {
          "type": "string"
        },
        "source": {
          "$ref": "#/$defs/HierarchyArtifactSource"
        }
      }
    },
    "HierarchyArtifactSource": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "kind"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "chunk",
            "asset",
            "embedding"
          ]
        },
        "chunk_id": {
          "type": "integer",
          "format": "uint32",
          "x-go-type-skip-optional-pointer": false
        },
        "window_index": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Independent media output sub-window within the parent chunk; omitted for an unsplit vector.",
          "x-go-type-skip-optional-pointer": false
        },
        "unit_id": {
          "type": "string"
        }
      }
    },
    "HierarchyEvidence": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "local_id": {
          "type": "string"
        },
        "decision": {
          "type": "string"
        },
        "confidence": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-type-skip-optional-pointer": false
        },
        "source_artifact": {
          "type": "string"
        },
        "source_artifact_key": {
          "type": "string"
        },
        "resolution_artifact": {
          "type": "string"
        },
        "resolution_artifact_key": {
          "type": "string"
        },
        "resolver": {
          "type": "string"
        },
        "resolver_table": {
          "type": "string"
        },
        "mention": {
          "type": "object",
          "additionalProperties": true
        },
        "canonical": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "HierarchyMatchContext": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "level": {
          "$ref": "#/$defs/QueryHitHierarchyLevel"
        },
        "parent_doc_key": {
          "type": "string"
        },
        "parent_unit_id": {
          "type": "string"
        },
        "artifact": {
          "$ref": "#/$defs/HierarchyArtifact"
        },
        "ancestors": {
          "$ref": "#/$defs/QueryHitHierarchyAncestors"
        }
      }
    },
    "HierarchyMatchHit": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "_id",
        "_score"
      ],
      "properties": {
        "_id": {
          "type": "string",
          "x-go-name": "ID"
        },
        "_score": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-name": "score",
          "description": "Relevance score, normalized so higher values always rank first."
        },
        "_distance": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-name": "distance",
          "x-go-type-skip-optional-pointer": false,
          "description": "Raw vector distance when this hit came directly from a dense-vector search; lower values are better."
        },
        "_source": {
          "type": "object",
          "additionalProperties": true,
          "x-go-name": "source"
        },
        "hierarchy": {
          "$ref": "#/$defs/HierarchyMatchContext"
        }
      }
    },
    "HighlightFragment": {
      "type": "object",
      "required": [
        "text",
        "offset",
        "spans"
      ],
      "properties": {
        "text": {
          "type": "string",
          "description": "The fragment of the stored field value."
        },
        "offset": {
          "type": "integer",
          "description": "Byte offset of the fragment within the field value."
        },
        "item": {
          "type": "integer",
          "description": "Array index for one array; flattened value ordinal for paths through multiple arrays."
        },
        "spans": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/HighlightSpan"
          }
        }
      }
    },
    "HighlightSpan": {
      "type": "object",
      "required": [
        "start",
        "end"
      ],
      "description": "Half-open byte range within the fragment text.",
      "properties": {
        "start": {
          "type": "integer"
        },
        "end": {
          "type": "integer"
        }
      }
    },
    "ImageURL": {
      "type": "object",
      "description": "Image URL or data URI.",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "description": "URL or data URI (data:image/png;base64,...)."
        }
      }
    },
    "ImageURLContentPart": {
      "type": "object",
      "description": "Image content in OpenAI-compatible format.",
      "required": [
        "type",
        "image_url"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "image_url"
          ]
        },
        "image_url": {
          "$ref": "#/$defs/ImageURL"
        }
      }
    },
    "IncompleteDetails": {
      "type": "object",
      "description": "Explains why the agent stopped before completion. Present when status is \"incomplete\".",
      "required": [
        "reason"
      ],
      "properties": {
        "reason": {
          "type": "string",
          "enum": [
            "max_internal_iterations",
            "max_tokens",
            "no_tools",
            "clarification_required"
          ],
          "description": "Why the agent stopped:\n- max_internal_iterations: Hit the configured max_internal_iterations limit\n- max_tokens: LLM output was truncated\n- no_tools: No tools were available for agentic mode\n- clarification_required: The agent needs a user decision before it can continue\n"
        }
      }
    },
    "MediaContentPart": {
      "type": "object",
      "description": "Inline binary media content (audio, image, etc.).",
      "required": [
        "type",
        "data",
        "mime_type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "media"
          ]
        },
        "data": {
          "type": "string",
          "format": "byte",
          "description": "Base64-encoded binary data."
        },
        "mime_type": {
          "type": "string",
          "description": "MIME type (audio/wav, image/gif, image/png, etc.)."
        },
        "sampling": {
          "$ref": "#/$defs/VideoSamplingPolicy"
        }
      }
    },
    "PruneStats": {
      "type": "object",
      "description": "Statistics from token-based document pruning",
      "properties": {
        "resources_kept": {
          "type": "integer",
          "description": "Number of resources kept after pruning"
        },
        "resources_pruned": {
          "type": "integer",
          "description": "Number of resources pruned to fit token budget"
        },
        "tokens_kept": {
          "type": "integer",
          "description": "Estimated tokens in kept resources"
        },
        "tokens_pruned": {
          "type": "integer",
          "description": "Estimated tokens in pruned resources"
        }
      }
    },
    "QueryHit": {
      "type": "object",
      "description": "A single query result hit",
      "required": [
        "_id",
        "_score"
      ],
      "properties": {
        "_table": {
          "type": "string",
          "description": "Source table provenance for composed query hits; equal IDs from union inputs remain distinct."
        },
        "_computed": {
          "type": "object",
          "x-zig-type": "raw_json_object",
          "additionalProperties": true,
          "description": "Named query-time computed values, separate from stored source."
        },
        "_id": {
          "type": "string",
          "description": "ID of the record.",
          "x-go-name": "ID"
        },
        "_score": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "description": "Relevance score of the hit, normalized so higher values always rank first.",
          "x-go-name": "score"
        },
        "_distance": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-name": "distance",
          "x-go-type-skip-optional-pointer": false,
          "description": "Raw vector distance for direct dense-vector hits; lower values are better.\nFor a source group ranked by dense descendants, this is the distance of\nthe best matching descendant that supplied the group score. Omitted for\nnon-dense and fused results.\n"
        },
        "_index_scores": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "format": "double"
          },
          "description": "Scores partitioned by index when using RRF search.",
          "x-go-name": "indexScores"
        },
        "_score_details": {
          "$ref": "#/$defs/QueryScoreDetails",
          "description": "Optional score provenance for ranking features applied to this hit.",
          "x-go-name": "scoreDetails"
        },
        "_source": {
          "type": "object",
          "additionalProperties": true,
          "x-go-name": "source"
        },
        "hierarchy": {
          "$ref": "#/$defs/QueryHitHierarchy",
          "description": "Stable ancestry envelope for derived document hierarchy hits. Present when\nthe hit is a derived unit/chunk/embedding artifact or when a source-level\ngroup includes nested matches. Standard fields include `level`,\n`parent_doc_key`, optional `parent_unit_id`, `artifact` or `matched_artifact`, `matches`, and\n`ancestors` with response-local or requested DB-backed source/unit context when available.\nV0.2-compatible implicit rollup requests continue to use the deprecated\n`chunks` field instead of `matches`.\n"
        },
        "_sort": {
          "type": "array",
          "items": {},
          "description": "Sort key values for this hit. Pass as search_after or search_before\nto paginate to the next/previous page. Values preserve their JSON\ntypes. Present for ordered result pages, including cursor-only\nrequests whose effective order is `_id` ascending.\n",
          "x-go-name": "sort"
        },
        "_highlights": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/HighlightFragment"
            }
          },
          "description": "Highlighted fragments keyed by source field, present when the request\nset `highlight` and the stored document has the field. Highlights are\ncomputed from the unprojected document, so a `fields` projection that\nomits a highlighted field does not suppress its highlights. Each\nfragment is a window of the stored field value with byte-offset spans\nmarking the text the full-text query matched.\n",
          "x-go-name": "highlights"
        }
      }
    },
    "QueryHitHierarchy": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "level": {
          "$ref": "#/$defs/QueryHitHierarchyLevel",
          "description": "Hierarchy level represented by this hit."
        },
        "parent_doc_key": {
          "type": "string",
          "description": "Source document key that owns this derived hit."
        },
        "parent_unit_id": {
          "type": "string",
          "description": "Unit identifier when the hit is attached to a document unit."
        },
        "artifact": {
          "$ref": "#/$defs/HierarchyArtifact"
        },
        "matched_artifact": {
          "$ref": "#/$defs/HierarchyArtifact",
          "description": "Artifact member that supplied the score for a source-level grouped hit."
        },
        "ancestors": {
          "$ref": "#/$defs/QueryHitHierarchyAncestors"
        },
        "evidence": {
          "$ref": "#/$defs/HierarchyEvidence"
        },
        "matches": {
          "type": "array",
          "description": "Matching descendant hits attached by the canonical hierarchy.group_by request.",
          "items": {
            "$ref": "#/$defs/HierarchyMatchHit"
          }
        },
        "position": {
          "type": "string",
    

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://artifacts.apis.io/antfly/json-schema/antfly-retrieval-agent-result-schema.json

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.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/antfly-retrieval-agent-result"
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.