AI Search on Licensed Content

The /search endpoint allows you to perform both text and semantic search over publication blocks from your licensed content. The endpoint converts your query into an embedding and performs vector search alongside traditional text search to find the most relevant results.

Endpoint Overview

Method: GET

Path: /search

Authorization: API key required

Important Considerations

Token Consumption: This endpoint tracks and deducts tokens for each result returned, based on the content length of each publication block accessed.

Licensed Content Only: Search results are limited to licensed Omnipubs and collections, not books you own. Publishers can issue themselves a license to see their own content in search results.

How Search Works

Cashmere search combines semantic matching with text relevance so applications can find passages even when users do not use the exact wording from the source material. Search runs only against content your API key is allowed to access, and filters can narrow results to specific collections, Omnipubs, or sections.

Each search creates a tracked query record and returns source links that preserve context for downstream reading and citation workflows. When a result is returned, Cashmere records the accessed content blocks for reporting, token accounting, and license compliance.

Choosing a Search Strategy

Most integrations should use the default search model configured on the API key. If no default is set, Cashmere falls back to the current standard hybrid model.

Specialized search models are available for use cases that need different ranking behavior, such as stronger recency preference, semantic-only retrieval, or alternate hybrid ranking strategies. Use these only when you have a clear reason to override the API key default.

Filtering Results

Filters are useful when your application already knows the scope of a request. For example, a user may be searching within a selected collection, a specific Omnipub, or a section they are currently reading.

Filtering also helps control token consumption by limiting returned results to the subset of licensed content that is relevant to the current workflow.

Tracking and Reporting

External tracking IDs let you connect Cashmere search activity to your own application context, such as a user, tenant, session, workspace, or request ID. These identifiers appear in usage reporting so you can reconcile Cashmere activity with your internal analytics and billing systems.

For exact parameter names, supported search model values, field options, and response schemas, see the API documentation.

Usage Patterns

GET /search?q=machine+learning&limit=10

Use a basic search when you want to retrieve the most relevant licensed content blocks for a user query without narrowing the result set. This is the simplest option for discovery, question answering, and retrieval-augmented generation workflows.

Search with Filters and Additional Fields

GET /search?q=neural+networks&limit=5&search_model=vtups1-1m&fields=omnipub_publisher,omnipub_creators

Use filters when your application needs to search within a specific collection, Omnipub, or section rather than across all licensed content. Request additional fields when your UI or downstream workflow needs more metadata, such as publisher, creator, cover image, or external identifier information.

Search with External Tracking IDs

GET /search?q=deep+learning&external_ids=user123,session456

Use external tracking IDs when you need to associate search activity with your own users, sessions, tenants, or application events. These identifiers support later reporting and analytics without requiring Cashmere to know your internal user model.

For exact request and response examples, see the API documentation.