# Search Knowledge Base

`POST /api/v1/knowledge/search`

## Description
Perform vector similarity search across one or more knowledge bases. Supports semantic search via query text, tag-based filtering, or a combination of both.

## Request Body

```json
{
  "type": "object",
  "required": [
    "workspaceId",
    "knowledgeBaseIds"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "description": "The workspace containing the knowledge bases."
    },
    "knowledgeBaseIds": {
      "oneOf": [
        {
          "type": "string",
          "description": "A single knowledge base ID."
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "An array of knowledge base IDs to search across."
        }
      ],
      "description": "Array of knowledge base IDs to search across."
    },
    "query": {
      "type": "string",
      "description": "Search query text for semantic similarity search. Either query or tagFilters must be provided."
    },
    "topK": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 10,
      "description": "Maximum number of results to return."
    },
    "tagFilters": {
      "type": "array",
      "description": "Tag-based filters. Either query or tagFilters must be provided.",
      "items": {
        "type": "object",
        "description": "A tag-based filter for knowledge base search.",
        "required": [
          "tagName",
          "value"
        ],
        "properties": {
          "tagName": {
            "type": "string",
            "description": "Display name of the tag to filter by."
          },
          "fieldType": {
            "type": "string",
            "enum": [
              "text",
              "number",
              "date",
              "boolean"
            ],
            "default": "text",
            "description": "Data type of the tag field."
          },
          "operator": {
            "type": "string",
            "default": "eq",
            "description": "Comparison operator (e.g. eq, neq, gt, lt, gte, lte, contains, between)."
          },
          "value": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ],
            "description": "Value to filter by."
          },
          "valueTo": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ],
            "description": "Upper bound value for 'between' operator."
          }
        }
      }
    }
  }
}
```

## Responses

### 200 — Search results.

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the request was successful."
    },
    "data": {
      "type": "object",
      "properties": {
        "results": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A single search result from knowledge base vector search.",
            "properties": {
              "documentId": {
                "type": "string",
                "description": "ID of the source document."
              },
              "documentName": {
                "type": "string",
                "description": "Filename of the source document."
              },
              "content": {
                "type": "string",
                "description": "The matched chunk content."
              },
              "chunkIndex": {
                "type": "integer",
                "description": "Index of the chunk within the document."
              },
              "metadata": {
                "type": "object",
                "description": "Tag metadata associated with the chunk (display names mapped to values)."
              },
              "similarity": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Similarity score (0-1, where 1 is most similar)."
              }
            }
          },
          "description": "Array of search result objects ranked by similarity."
        },
        "query": {
          "type": "string",
          "description": "The search query used."
        },
        "knowledgeBaseIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Knowledge base IDs that were searched."
        },
        "topK": {
          "type": "integer",
          "description": "Maximum results requested."
        },
        "totalResults": {
          "type": "integer",
          "description": "Number of results returned."
        }
      },
      "description": "Response payload containing the search results and metadata."
    }
  }
}
```

### 400 — Invalid request parameters. Check the details array for specific validation errors.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message describing the validation failure."
    },
    "details": {
      "type": "array",
      "description": "List of specific validation errors with field-level details.",
      "items": {
        "type": "object"
      }
    }
  }
}
```

### 401 — Invalid or missing API key. Ensure the X-API-Key header is set with a valid key.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 403 — Access denied. You do not have permission to access this resource. For audit log endpoints, this requires an Enterprise subscription and organization admin/owner role.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 404 — The requested resource was not found. Verify the ID is correct and belongs to your workspace.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 429 — Rate limit exceeded. Wait for the duration specified in the Retry-After header before retrying.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message with rate limit details."
    }
  }
}
```
