{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/serpkite-com/json-schema/serpkite-com-rank-response-schema.json",
  "title": "RankResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/serpkite-com-rank-api-openapi.yml#/components/schemas/RankResponse",
  "type": "object",
  "required": [
    "request",
    "domain",
    "position",
    "matches",
    "checked",
    "meta"
  ],
  "properties": {
    "request": {
      "$ref": "#/$defs/RequestEcho"
    },
    "domain": {
      "type": "string"
    },
    "position": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Best organic position",
      "null when not in the checked results": null
    },
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "position",
          "title",
          "link"
        ],
        "properties": {
          "position": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "link": {
            "type": "string"
          }
        }
      }
    },
    "checked": {
      "type": "integer",
      "description": "Organic results inspected"
    },
    "meta": {
      "$ref": "#/$defs/Meta"
    }
  },
  "$defs": {
    "LLMUsage": {
      "type": "object",
      "description": "The model that wrote this response's AI part and the tokens it used",
      "properties": {
        "provider": {
          "type": "string"
        },
        "model": {
          "type": "string"
        },
        "input_tokens": {
          "type": "integer"
        },
        "output_tokens": {
          "type": "integer"
        }
      }
    },
    "Meta": {
      "type": "object",
      "required": [
        "request_id",
        "credits_used",
        "cached"
      ],
      "properties": {
        "request_id": {
          "type": "string"
        },
        "credits_used": {
          "type": "number"
        },
        "engine": {
          "type": "string",
          "description": "The provider that produced the result (`consensus` for a merged engine=consensus answer)"
        },
        "route": {
          "type": "array",
          "description": "Provider attempts in order (fresh results only; absent on cache hits). With engine=consensus, every provider started; ones stopped early are `canceled`, ones cut off by the deadline `timeout`",
          "items": {
            "$ref": "#/$defs/RouteStep"
          }
        },
        "cached": {
          "type": "boolean"
        },
        "cached_at": {
          "type": "string",
          "format": "date-time"
        },
        "resolved_urls": {
          "type": "boolean"
        },
        "parse_quality": {
          "type": "string",
          "enum": [
            "ok",
            "partial",
            "empty"
          ]
        },
        "latency_ms": {
          "type": "integer"
        },
        "llm": {
          "$ref": "#/$defs/LLMUsage"
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Non-fatal problems, e.g. an include_answer that failed (and was refunded)"
        }
      }
    },
    "RequestEcho": {
      "type": "object",
      "description": "The normalised request that produced this response (defaults filled in)",
      "required": [
        "endpoint",
        "engine"
      ],
      "additionalProperties": true,
      "properties": {
        "endpoint": {
          "type": "string"
        },
        "engine": {
          "description": "The engine policy as asked (google, auto, one provider or a list)",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ]
        },
        "q": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "country": {
          "type": "string"
        },
        "language": {
          "type": "string"
        },
        "location": {
          "type": "string"
        },
        "num": {
          "type": "integer"
        },
        "page": {
          "type": "integer"
        },
        "device": {
          "type": "string"
        },
        "autocorrect": {
          "type": "boolean"
        },
        "tbs": {
          "type": "string"
        },
        "start_date": {
          "type": "string",
          "format": "date"
        },
        "end_date": {
          "type": "string",
          "format": "date"
        },
        "safe": {
          "type": "string"
        },
        "place_id": {
          "type": "string"
        },
        "cid": {
          "type": "string"
        },
        "fid": {
          "type": "string"
        },
        "oid": {
          "type": "string"
        },
        "sort": {
          "type": "string"
        },
        "include_content": {
          "type": "integer"
        },
        "format": {
          "type": "string"
        },
        "include_domains": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "exclude_domains": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "boost_domains": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "highlights": {
          "type": "boolean"
        },
        "include_answer": {
          "type": "boolean"
        },
        "prompt": {
          "type": "string",
          "description": "AI assistant endpoints"
        },
        "web_search": {
          "type": "boolean",
          "description": "/v1/chatgpt"
        },
        "include_html": {
          "type": "boolean"
        }
      }
    },
    "RouteStep": {
      "type": "object",
      "description": "One provider attempt behind this answer.",
      "required": [
        "provider",
        "outcome",
        "ms"
      ],
      "properties": {
        "provider": {
          "type": "string"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "ok",
            "partial",
            "empty",
            "soft_empty",
            "blocked",
            "timeout",
            "error",
            "unsupported",
            "bad_param",
            "bad_target",
            "canceled"
          ]
        },
        "ms": {
          "type": "integer",
          "description": "Duration of the attempt in milliseconds"
        }
      }
    }
  }
}