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

POSThttps://data.spiceai.io/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.

Authorizations

  • X-API-KeystringRequired

    Your project API key. See API keys.

Body

application/jsonRequired

Search request parameters

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_columnsarray 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.

  • datasetsarray 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.

  • limitinteger | null

    Number of documents to return for each dataset

    • Minimum: 0

  • textstringRequired

    The text to search documents for similarity. Must contain at least one non-whitespace character.

  • wherestring | null

    An SQL filter predicate to apply. Format: 'WHERE where_cond'.

  • keywordsarray of string | null

Responses

200Search completed successfullyapplication/json

  • duration_msintegerRequired

    Total time taken to execute the search, in milliseconds

    • Minimum: 0

  • resultsarray of objectRequired

    List of matches that were found in the datasets

    6 properties

    • _scorenumber (double)Required

      The similarity of the match to the query

    • datamap of any

      Addditional data from the dataset requested by the user.

    • datasetstringRequired

      The name of the dataset where the match was found

    • matchesmap of array of anyRequired

      The matches for this result

    • metadatamap of any

    • primary_keymap of any

      Primary key(s) identifying the matched item in the dataset

400Invalid request parametersapplication/json

any

500Internal server errorapplication/json

any

OpenAPIspiceai/spiceai v2.4.0

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"
    ]
  }'
{
  "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
}

application/json