# Semantic Search
Semantic search finds documents by meaning instead of exact words, using the Microsoft 365 Copilot Retrieval API. Users switch between Literal search and Semantic search with the toggle next to the search box in the Matter view, Contracts and All Documents.
# Requirements
- The Epona365 API is deployed (
api.urlset in DMS Configuration), with theaccess_as_userpermission granted. See Permissions Reference. - Semantic search is switched on for the organization in the Epona365 API portal. It is on by default.
- Each user who runs a semantic search needs one of:
- a Microsoft 365 Copilot license, or
- Microsoft 365 Copilot pay-as-you-go for the Retrieval API, set up in the Microsoft 365 admin center.
Epona365 cannot see in advance whether a user has a license or is covered by pay-as-you-go. The toggle is therefore shown to everyone in the organization once semantic search is switched on. The first semantic search tells Epona365 whether the user can use it (see When a semantic search fails).
# Functionality
- Inside a matter, the search covers the current matter, or the selected folder and its subfolders. Outside a matter (for example in All Documents) it is not limited to a folder and covers the SharePoint content the user can access.
- A semantic search returns at most 25 results.
- The filter (refiners) panel is hidden while semantic search results are shown.
- Switching between Literal and Semantic search clears the search box, because a query written for one mode does not work well in the other. Opening a different folder also clears a semantic search.
- Epona365 remembers the mode each user last chose.
# When a semantic search fails
| Situation | What the user sees | Toggle |
|---|---|---|
| User has no Microsoft 365 Copilot license and no pay-as-you-go | "A Microsoft 365 Copilot license is required to use semantic search." | Switches back to Literal search and is hidden for the rest of the session |
| Semantic search is switched off for the organization | "Semantic search is turned off for your organization." | Switches back to Literal search and is hidden for the rest of the session |
| The semantic search service (Microsoft Graph or the Epona365 API) is busy or temporarily unavailable | "Semantic search is temporarily unavailable. Try again in a moment." | Stays available |
| Any other failure | "Could not complete search" | Stays available |
The session ends when the browser tab is closed, or, in Teams or Outlook, when Epona365 is closed. After a license or pay-as-you-go is assigned, or the organization switch is turned back on, users open a new browser tab (or close and reopen Epona365 in Teams or Outlook) to get the toggle back. Nobody needs to clear a setting.
The license and organization messages, and hiding the toggle, need a recent Epona365 API version. With an older version, a missing license or a switched-off organization shows "Could not complete search" and the toggle stays available.
# Troubleshooting
- Toggle not shown for anyone: check that the Epona365 API is deployed and that semantic search is switched on for the organization in the Epona365 API portal.
- Toggle disappeared for one user: that user's last semantic search reported no license (or the organization switch was off). Assign a Microsoft 365 Copilot license or pay-as-you-go, then have the user open a new browser tab (or close and reopen Epona365 in Teams or Outlook).
- "Could not complete search" for every user: check the
access_as_usergrant in Permissions Reference and the Epona365 API logs.