# AI Search
{% hint style="info" %}
**Requires** [**AI Search**](https://eagle.cool/support/article/ai-search) **Plugin.** The AI Search features require the Eagle AI Search plugin to be installed and running. Use the status endpoints to check availability before performing searches.
{% endhint %}
## Endpoints Overview
| Method | Endpoint | Description |
| ------ | ------------------------------------- | ---------------------------------- |
| GET | `/api/v2/aiSearch/isInstalled` | Check if AI Search is installed |
| GET | `/api/v2/aiSearch/isReady` | Check if AI Search is ready |
| GET | `/api/v2/aiSearch/isStarting` | Check if AI Search is starting up |
| GET | `/api/v2/aiSearch/isSyncing` | Check if AI Search is syncing data |
| GET | `/api/v2/aiSearch/getSyncStatus` | Get detailed sync status |
| GET | `/api/v2/aiSearch/checkServiceHealth` | Check service health |
| POST | `/api/v2/aiSearch/searchByText` | Search by text description |
| POST | `/api/v2/aiSearch/searchByBase64` | Search by image (Base64) |
| POST | `/api/v2/aiSearch/searchByItemId` | Find similar items by item ID |
***
## Status Endpoints
### GET /api/v2/aiSearch/isInstalled
Check whether the AI Search plugin is installed.
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isInstalled").then(r => r.json());
```
**Response:**
```json
{
"status": "success",
"data": true
}
```
***
### GET /api/v2/aiSearch/isReady
Check whether AI Search is fully initialized and ready to accept search queries.
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isReady").then(r => r.json());
```
**Response:**
```json
{
"status": "success",
"data": true
}
```
***
### GET /api/v2/aiSearch/isStarting
Check whether the AI Search service is currently starting up.
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isStarting").then(r => r.json());
```
**Response:**
```json
{
"status": "success",
"data": false
}
```
***
### GET /api/v2/aiSearch/isSyncing
Check whether AI Search is currently syncing (indexing) library data.
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isSyncing").then(r => r.json());
```
**Response:**
```json
{
"status": "success",
"data": false
}
```
***
### GET /api/v2/aiSearch/getSyncStatus
Get detailed synchronization status, including progress information.
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/getSyncStatus").then(r => r.json());
```
**Response:**
```json
{
"status": "success",
"data": {
"isSyncing": false,
"syncedCount": 12500,
"totalCount": 12500,
"progress": 1.0
}
}
```
***
### GET /api/v2/aiSearch/checkServiceHealth
Perform a health check on the AI Search service.
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/checkServiceHealth").then(r => r.json());
```
**Response:**
```json
{
"status": "success",
"data": {
"healthy": true
}
}
```
***
## Search Endpoints
### POST /api/v2/aiSearch/searchByText
Search for items using a natural language text description. The AI model finds visually or semantically matching items.
#### Request Body
* `query` string (required) — Text description to search for
* `options` Object (optional)
* `limit` integer — Maximum number of results (default varies by AI Search config)
#### Response
```json
{
"status": "success",
"data": {
"results": [
{
"item": {
"id": "M3QSGJNQTC2DG",
"name": "sunset-beach",
"ext": "jpg",
"width": 1920,
"height": 1080,
"tags": ["nature", "sunset"],
"star": 4
},
"score": 0.892
},
{
"item": {
"id": "K7XPWQBN9TC3F",
"name": "golden-hour",
"ext": "png",
"width": 2560,
"height": 1440,
"tags": ["photography"],
"star": 3
},
"score": 0.756
}
]
}
}
```
#### Examples
```javascript
// Search by text description
await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ query: "an orange cat sitting on a windowsill" })
}).then(r => r.json());
// Search with result limit
await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
query: "minimalist logo design",
options: { limit: 20 }
})
}).then(r => r.json());
```
***
### POST /api/v2/aiSearch/searchByBase64
Find visually similar items by providing a Base64-encoded image.
#### Request Body
* `base64` string (required) — Base64-encoded image data
* `options` Object (optional)
* `limit` integer — Maximum number of results
#### Response
Same format as `searchByText` — returns an array of `{ item, score }` results sorted by similarity.
#### Example
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/searchByBase64", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
base64: "/9j/4AAQSkZJRg...",
options: { limit: 10 }
})
}).then(r => r.json());
```
***
### POST /api/v2/aiSearch/searchByItemId
Find items visually similar to an existing item in the library.
#### Request Body
* `itemId` string (required) — The item ID to find similar items for
* `options` Object (optional)
* `limit` integer — Maximum number of results
#### Response
Same format as `searchByText` — returns an array of `{ item, score }` results sorted by similarity.
#### Example
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/searchByItemId", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
itemId: "M3QSGJNQTC2DG",
options: { limit: 10 }
})
}).then(r => r.json());
```
***
## Recommended Workflow
1. **Check availability** — Call `isInstalled` and `isReady` before searching
2. **Wait if starting** — If `isStarting` returns `true`, poll until `isReady` becomes `true`
3. **Check sync status** — Use `getSyncStatus` to verify the index is up to date
4. **Search** — Use `searchByText` for description-based search, `searchByBase64` for reverse image search, or `searchByItemId` to find similar items
```javascript
// Step 1: Verify AI Search is ready
const { data: isReady } = await fetch("http://localhost:41595/api/v2/aiSearch/isReady")
.then(r => r.json());
if (isReady) {
// Step 2: Perform search
const results = await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ query: "sunset landscape", options: { limit: 10 } })
}).then(r => r.json());
console.log(results.data.results);
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.eagle.cool/web-api/api/ai-search.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.