Search API

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

NameTypeRequiredDescription
X-API-KeystringYes

Your project API key. See API keys.

Request body

Required

Search request parameters

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_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

  • wherestring | null

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

  • keywordsarray of string | null

Example request

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

Responses

  • 200OK

    Search completed successfully

    application/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

    Example

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

  • 400Bad Request

    Invalid request parameters

    application/json

    any

    Example

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

  • 500Internal Server Error

    Internal server error

    application/json

    any

    Example

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

OpenAPIspiceai/spiceai v2.3.2