{
  "openapi": "3.1.0",
  "info": {
    "title": "Pydantic documentation search API",
    "version": "1.0.0",
    "description": "Searches the AI Search documentation index for agent requests, with Pagefind as an availability fallback. The human-facing site continues to use Pagefind directly."
  },
  "servers": [
    {
      "url": "https://pydantic.dev"
    }
  ],
  "paths": {
    "/docs/api/search": {
      "get": {
        "operationId": "searchPydanticDocs",
        "summary": "Search Pydantic documentation",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "\\S"
            }
          },
          {
            "name": "library",
            "in": "query",
            "required": false,
            "description": "Optional repeatable library filter. Canonical values are validation, ai, and logfire; product-name aliases are also accepted.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "validation",
                  "pydantic",
                  "ai",
                  "pydantic-ai",
                  "pydantic_ai",
                  "logfire",
                  "pydantic-logfire"
                ]
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of results to return (default 10, maximum 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          },
          {
            "name": "goal",
            "in": "query",
            "required": true,
            "description": "Required. Every search request MUST include a non-empty goal. Telling us the overall goal you're trying to achieve helps us steer the right search results to you in addition to the provided keywords. It works best when provided as a sentence or two in English. It is recorded with request analytics; do not include secrets or personal data.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500,
              "pattern": "\\S"
            },
            "example": "Understand why a model validation failed"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked documentation results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "503": {
            "$ref": "#/components/responses/SearchUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Library": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "validation",
              "ai",
              "logfire"
            ]
          },
          "name": {
            "type": "string"
          }
        }
      },
      "Section": {
        "type": "object",
        "required": [
          "title",
          "url",
          "excerpt"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "excerpt": {
            "type": "string"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "rank",
          "title",
          "url",
          "excerpt",
          "score",
          "library",
          "sections"
        ],
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 1
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "excerpt": {
            "type": "string"
          },
          "score": {
            "type": "number"
          },
          "library": {
            "$ref": "#/components/schemas/Library"
          },
          "sections": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "$ref": "#/components/schemas/Section"
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "schema_version",
          "query",
          "goal",
          "filters",
          "total",
          "returned",
          "results"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1"
          },
          "query": {
            "type": "string"
          },
          "goal": {
            "type": "string"
          },
          "filters": {
            "type": "object",
            "required": [
              "libraries"
            ],
            "properties": {
              "libraries": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "validation",
                    "ai",
                    "logfire"
                  ]
                }
              }
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "returned": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20
          },
          "results": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          }
        }
      },
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "parameter": {
            "type": "string"
          },
          "valid_values": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "constraints": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          },
          "example": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid query parameters.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "Unsupported HTTP method.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "RateLimitExceeded": {
        "description": "More than 30 search requests were made by one client within 60 seconds.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "const": 60
            }
          },
          "RateLimit": {
            "description": "The current search quota, remaining requests, and reset time.",
            "schema": {
              "type": "string"
            }
          },
          "RateLimit-Policy": {
            "description": "The search request quota and window.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "SearchUnavailable": {
        "description": "The generated search index is temporarily unavailable.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "const": 30
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    }
  }
}