# Search technical knowledge (/api/search-index/search)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 2559 · updated: 2026-09-23 -->
Related: [Mintlify Index REST API](/api/search-index/introduction.md), [Build implementation context](/api/search-index/context.md), [Get result contents](/api/search-index/contents.md)



`POST /v1/search`

Returns ranked results from publisher-maintained documentation or the web. Use Mintlify result IDs or any result URL with the contents endpoint when you need more content.

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "query",
            "numResults"
          ],
          "properties": {
            "query": {
              "type": "string",
              "minLength": 1,
              "description": "Search query."
            },
            "numResults": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "description": "Maximum number of results to return."
            },
            "text": {
              "default": false,
              "description": "Controls result content. Set to `true` to include matched content, `false` to omit it, or provide `maxCharacters` to include truncated content. When omitted, defaults to `false`.",
              "oneOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "maxCharacters"
                  ],
                  "properties": {
                    "maxCharacters": {
                      "type": "integer",
                      "minimum": 1,
                      "description": "Maximum number of content characters to include per result."
                    }
                  }
                }
              ]
            },
            "includeDomains": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Domains to include in search results."
            },
            "excludeDomains": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Domains to exclude from search results."
            }
          }
        },
        "example": {
          "query": "Next.js 16 caching and revalidation",
          "numResults": 5,
          "text": {
            "maxCharacters": 4000
          },
          "includeDomains": [
            "nextjs.org"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Search completed successfully.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "requestId",
              "results"
            ],
            "properties": {
              "requestId": {
                "type": "string",
                "description": "Unique identifier for the request."
              },
              "results": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "url",
                    "title",
                    "text",
                    "score",
                    "source",
                    "siteName",
                    "breadcrumbs",
                    "publishedDate"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Result identifier. Pass IDs from Mintlify results in the contents request's `ids` field. For web results, pass the result URL in `urls`."
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Canonical source URL."
                    },
                    "title": {
                      "type": "string",
                      "description": "Source title."
                    },
                    "text": {
                      "type": "string",
                      "description": "Matched content when requested. Otherwise, an empty string."
                    },
                    "truncated": {
                      "type": "boolean",
                      "description": "Whether the returned content is shorter than the available content."
                    },
                    "totalCharacters": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Number of available characters before truncation. Present when available."
                    },
                    "score": {
                      "type": "number",
                      "description": "Relative relevance score. Contents responses use `0` because they retrieve selected items rather than rank results."
                    },
                    "source": {
                      "type": "string",
                      "enum": [
                        "mintlify",
                        "web"
                      ],
                      "description": "Retrieval source."
                    },
                    "siteName": {
                      "type": "string",
                      "description": "Documentation site or web hostname."
                    },
                    "breadcrumbs": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Documentation hierarchy for the result."
                    },
                    "publishedDate": {
                      "type": "string",
                      "nullable": true,
                      "description": "Published date when the source provides one, otherwise `null`. `search` results normalize this to a full ISO 8601 timestamp. `contents` results retrieved by `urls` pass the source's original date string through unnormalized, which can be a full timestamp or a date-only string."
                    }
                  }
                },
                "description": "Ranked search results."
              }
            }
          },
          "example": {
            "requestId": "3d8ed0aa-c21c-4a18-b995-207aa6315ea8",
            "results": [
              {
                "id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
                "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating",
                "title": "Caching and revalidating",
                "text": "Caching is a technique for storing the result of data fetching and other computations.",
                "truncated": false,
                "totalCharacters": 92,
                "score": 0.91,
                "source": "mintlify",
                "siteName": "nextjs",
                "breadcrumbs": [
                  "App Router",
                  "Getting started"
                ],
                "publishedDate": null
              }
            ]
          }
        }
      }
    },
    "400": {
      "description": "The request body is invalid.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          },
          "example": {
            "error": "Invalid request body"
          }
        }
      }
    },
    "401": {
      "description": "The API key is missing or invalid, or the organization does not have Index REST API access.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          },
          "example": {
            "error": "Unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "The request IP is not allowed by the API key.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          },
          "example": {
            "error": "IP address is not allowed for this API key"
          }
        }
      }
    },
    "429": {
      "description": "The organization exceeded a rate limit.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          },
          "example": {
            "error": "Rate limit exceeded. Please try again later"
          }
        }
      }
    },
    "500": {
      "description": "Index could not complete the request.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      }
    }
  }
}
```