# Search API

Run a vector similarity search on a Spice Cloud dataset with POST /v1/search and get the most relevant matches for a text input.

## Search

`POST /v1/search`

Perform a vector similarity search (VSS) operation on a dataset.

The search operation will return the most relevant matches based on cosine similarity with the input `text`.
The datasets queries should have an embedding column, and the appropriate embedding model loaded.

### Header parameters

- `X-API-Key` (string, required): Your project API key. See [API keys](https://spice.ai/docs/cloud/portal/apps/api-keys).

### Request body

Required.

Search request parameters

Content type: `application/json`

HTTP request schema is separate from AI requests, so that keywords can be supplied as an optional field for HTTP calls.
`schemars` doesn't allow setting `#[serde(default)]` as well as `#[schemars(required)]` - the field does not become required.
When the field is not required, the model ignores it.

- `additional_columns` (array of string): Additional columns to return from the dataset. If the column is a primary key, it will be
  returned within the response under `.primary_key`, not `.data`.
- `datasets` (array of string | null): The datasets to search for similarity. If None, search across all datasets. For available datasets, use the `list_datasets` tool and ensure `can_search_documents==true`.
- `limit` (integer | null): Number of documents to return for each dataset. Minimum: `0`.
- `text` (string, required): The text to search documents for similarity. Must contain at least one non-whitespace character.
- `where` (string | null): An SQL filter predicate to apply. Format: 'WHERE `where_cond`'.
- `keywords` (array of string | null)

### Example request

```bash
curl -X POST "https://data.spiceai.io/v1/search" \
  -H "X-API-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "datasets": [
      "app_messages"
    ],
    "text": "Tokyo plane tickets",
    "where": "user=1234321",
    "additional_columns": [
      "timestamp"
    ],
    "limit": 3,
    "keywords": [
      "plane",
      "tickets"
    ]
  }'
```

```http
POST /v1/search HTTP/1.1
Host: data.spiceai.io
X-API-Key: <project-api-key>
Content-Type: application/json
Content-Length: 211

{
  "datasets": [
    "app_messages"
  ],
  "text": "Tokyo plane tickets",
  "where": "user=1234321",
  "additional_columns": [
    "timestamp"
  ],
  "limit": 3,
  "keywords": [
    "plane",
    "tickets"
  ]
}
```

### Responses

**200 OK**

Search completed successfully

Content type: `application/json`

- `duration_ms` (integer, required): Total time taken to execute the search, in milliseconds. Minimum: `0`.
- `results` (array of object, required): List of matches that were found in the datasets
  - `_score` (number (double), required): The similarity of the match to the query
  - `data` (map of any): Addditional data from the `dataset` requested by the user.
  - `dataset` (string, required): The name of the dataset where the match was found
  - `matches` (map of array of any, required): The matches for this result
  - `metadata` (map of any)
  - `primary_key` (map of any): Primary key(s) identifying the matched item in the dataset

Example:

```json
{
  "results": [
    {
      "matches": {
        "message": "I booked use some tickets"
      },
      "dataset": "app_messages",
      "primary_key": {
        "id": "6fd5a215-0881-421d-ace0-b293b83452b5"
      },
      "data": {
        "timestamp": 1724716542
      },
      "_score": 0.914321
    },
    {
      "matches": {
        "message": "direct to Narata"
      },
      "dataset": "app_messages",
      "primary_key": {
        "id": "8a25595f-99fb-4404-8c82-e1046d8f4c4b"
      },
      "data": {
        "timestamp": 1724715881
      },
      "_score": 0.83221
    },
    {
      "matches": {
        "message": "Yes, we're sitting together"
      },
      "dataset": "app_messages",
      "primary_key": {
        "id": "8421ed84-b86d-4b10-b4da-7a432e8912c0"
      },
      "data": {
        "timestamp": 1724716123
      },
      "_score": 0.787654321
    }
  ],
  "duration_ms": 42
}
```

**400 Bad Request**

Invalid request parameters

Content type: `application/json`

Type: `any`

Example:

```json
{
  "error": "No data sources provided"
}
```

**500 Internal Server Error**

Internal server error

Content type: `application/json`

Type: `any`

Example:

```json
{
  "error": "Unexpected internal server error occurred"
}
```

OpenAPI: [spiceai/spiceai v2.4.0](https://github.com/spiceai/spiceai/blob/v2.4.0/.schema/openapi.json)