SearchResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/git-top/json-schema/git-top-search-response-schema.json",
  "title": "SearchResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/git-top-search-api-openapi.yml#/components/schemas/SearchResponse",
  "type": "object",
  "required": [
    "profile",
    "query",
    "search",
    "projects",
    "page",
    "metadata"
  ],
  "properties": {
    "profile": {
      "type": "string",
      "enum": [
        "full",
        "compact",
        "decision",
        "evidence"
      ],
      "default": "full"
    },
    "query": {
      "type": "object",
      "additionalProperties": true
    },
    "search": {
      "type": "object",
      "properties": {
        "applied_filters": {
          "type": "object",
          "additionalProperties": true
        },
        "known_filter_values": {
          "type": "object",
          "additionalProperties": true
        },
        "empty_reason": {
          "type": "string"
        },
        "suggestions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "query_interpretation": {
          "type": "object",
          "properties": {
            "original": {
              "type": "string"
            },
            "normalized": {
              "type": "string"
            },
            "transformations": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      },
      "additionalProperties": true
    },
    "projects": {
      "type": "array",
      "description": "Project cards shaped by profile. compact returns bounded identity, fit, score, and verification fields; full preserves the complete project card.",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "knowledge": {
      "type": "array",
      "description": "Raw project knowledge rows retained only for the default full profile.",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "page": {
      "$ref": "#/$defs/CursorPage"
    },
    "metadata": {
      "$ref": "#/$defs/Metadata"
    }
  },
  "additionalProperties": true,
  "$defs": {
    "CursorPage": {
      "type": "object",
      "required": [
        "offset",
        "limit",
        "has_more",
        "next_cursor",
        "snapshot_id"
      ],
      "properties": {
        "offset": {
          "type": "integer",
          "minimum": 0
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        },
        "has_more": {
          "type": "boolean"
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque cursor for the next page, or null on the final page."
        },
        "snapshot_id": {
          "type": "string",
          "description": "Corpus snapshot to which this page and cursor are bound."
        }
      }
    },
    "Metadata": {
      "type": "object",
      "description": "Common provenance envelope for agent-facing responses. Agents should require source=d1 for high-confidence production claims and disclose seed fallback.",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "d1",
            "seed"
          ]
        },
        "reason": {
          "type": "string"
        },
        "project_count": {
          "type": "integer"
        },
        "generated_at": {
          "type": "string",
          "format": "date-time"
        },
        "snapshot_id": {
          "type": "string",
          "description": "Stable identity for the corpus snapshot used by this response."
        },
        "latest_synced_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "schema_version": {
          "type": "string",
          "enum": [
            "git-top.knowledge.v1"
          ]
        },
        "loaded_project_limit": {
          "type": "integer",
          "description": "Maximum D1 knowledge or search-candidate rows loaded into the bounded ranking set when present."
        },
        "truncated": {
          "type": "boolean",
          "description": "Whether the D1-backed ranking or candidate set reached its limit and may omit additional matching rows."
        },
        "candidate_retrieval": {
          "type": "string",
          "enum": [
            "d1_first"
          ],
          "description": "Search-only marker indicating that deterministic filters and broad query matching ran in D1 before TypeScript ranking."
        },
        "candidate_count": {
          "type": "integer",
          "description": "Number of D1 search candidates passed to the authoritative TypeScript filter and ranking stage."
        },
        "candidate_limit": {
          "type": "integer",
          "description": "Maximum number of D1 search candidates passed to the ranking stage."
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Fallback, count, freshness, or trust caveats that agents should account for before citing results."
        }
      }
    }
  }
}