---
title: "Semantic search over facts"
method: POST
path: "/pots/{pot_id}/search"
tags: ["search", "search"]
---

# Semantic search over facts

`POST /pots/{pot_id}/search`

Execute semantic search using RAG retrieval strategy.

**Ranking formula:** `combined_score = (similarity × 0.7) + (pot_score × 0.3)`

Results are ordered by combined score descending.

**Filtering:**
- `min_pot_score`: Pre-filter by minimum certainty score
- `filters.domain`: Post-filter by exact domain match
- `filters.level`: Post-filter by POT Index level(s) (OR logic)
- `filters.tags`: Post-filter by tags (AND logic - must have ALL)

## Path parameters

- `pot_id` string, required — POT identifier (UUID or slug)

## Request body

- SearchRequest — Semantic search request. Uses RAG retrieval with hybrid ranking: combined_score = (similarity × 0.7) + (pot_score × 0.3)
  - `query` string, required — Natural language search query
  - `top_k` integer — Maximum number of results to return
  - `min_pot_score` number — Minimum POT Index threshold for results
  - `filters` ScipotApiSchemasSearchSearchFiltersRequest — Optional post-retrieval filters. Filters are applied after vector search for flexibility: - domain: Exact match on domain - level: Any of these levels (OR logic) - tags: Must have ALL tags (AND logic)
    - `domain` string, nullable — Filter by domain (exact match)
    - `level` string[], nullable — Filter by POT Index levels (OR logic)
    - `tags` string[], nullable — Filter by tags (AND logic - must have ALL)
  - `include_content` boolean — Include full fact content in results (set false for compact response)

## Response `200`

Successful search

- object

## Other responses

- `400` — Invalid query (too short, invalid parameters)
- `404` — POT not found
- `422` — Validation Error
- `500` — Search failed (vector store error, embedding error)

---

[API](https://skmtc.dev/scipot/apis/scipot-core-api.md) · [All operations](https://skmtc.dev/scipot/apis/scipot-core-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scipot/scipot-core-api/revisions/e8712e9ffeae/schema)