Search API documentation.

Sprigr supports hybrid search that combines traditional keyword matching with AI-powered vector search. When enabled, every query returns results ranked by both exact keyword relevance and semantic meaning, merged using Reciprocal Rank Fusion (RRF).

What is hybrid semantic search?

Standard full-text search matches keywords literally. A query for "frustrated conversation" only finds records containing those exact words. Hybrid semantic search adds a vector layer: Sprigr generates embeddings for your data and compares the meaning of queries against the meaning of your records. The two result sets are merged with RRF so you get the best of both worlds, precise keyword hits and semantically related matches.

Enabling semantic search

Enable it per index by setting semantic_search to true in your index settings:

PUT /1/indexes/my-index/settings
Content-Type: application/json

{
  "searchable_attributes": ["title", "content"],
  "attributes_for_faceting": ["category"],
  "semantic_search": true
}

How it works

When semantic_search is enabled on an index:

1. On import: Sprigr generates vector embeddings for each record automatically. Embeddings are stored alongside the full-text index.
2. On query: The search query is embedded in real time. Sprigr runs both a keyword search and a vector similarity search in parallel.
3. Merging: Results from both searches are combined using Reciprocal Rank Fusion (RRF). This produces a single ranked list that surfaces records matching by keywords, by meaning, or both.

API usage

Use the POST /1/indexes/{index}/query endpoint with the semantic parameter:

POST /1/indexes/docs/query
Content-Type: application/json

{
  "query": "frustrated conversation",
  "semantic": true,
  "hits_per_page": 10
}

You can also generate an embedding directly without searching, using the POST /1/embed endpoint:

POST /1/embed
Content-Type: application/json

{
  "text": "frustrated conversation about billing"
}

This returns an embedding vector (384 dimensions) that you can use for custom similarity logic or external vector stores.

Notes

• Semantic search is opt-in per index. Indexes without semantic_search: true continue to use keyword-only search with no changes.
• Embeddings are generated automatically on import. There is no separate embedding step required.
• Semantic search is included on Starter plans and above.
• The semantic query parameter can be omitted to fall back to keyword-only search even on indexes with semantic search enabled.

Permission levels

Every key is admin, write, or search. Admin keys manage indexes and keys, write keys import and delete data, search keys only query. Create and revoke keys from the dashboard or the /admin/keys endpoints. Key listings return masked previews and revocation works by key id, so full key values never travel in URLs.

Index ACLs

Restrict any key to specific indexes with allowed_indexes: exact names or trailing-* prefix patterns like acme-*. A key with no ACL sees every index in the account. ACLs are alias-aware and enforced on both reads and writes.

Scoped keys: row-level access control

For multi-user apps and AI agents, mint a secured key from a search key. The secured key carries a locked filter that the engine ANDs into every query, on both the keyword and semantic paths. The holder can narrow results further but can never remove or widen the filter.

POST /1/keys/secured
X-Sprigr-API-Key: your-search-key

{
  "filters": "acl_principals:user:alice@corp.com
              OR acl_principals:public",
  "restrictIndices": ["docs"],
  "validUntil": 1893456000
}

The response contains a securedApiKey (sk_...) used exactly like any key. Scoped keys are stateless, signed by the parent key, so there is nothing to store or sync: revoke them by rotating the parent key or by letting validUntil (Unix seconds) expire. An optional userToken attributes analytics to the end user.

Scoped keys are search-only. Direct object reads, exports, and writes are refused, and rows that lack the filtered attribute never match, so access fails closed. Filter values may contain colons, which makes principal-style values like acl_principals:user:alice@corp.com work as row-level grants.