Enabling AI search for your AI agents

Updated March 27, 2026

Cashmere's search API lets your chat agents find and cite specific passages from your licensed publications. This turns generic AI responses into authoritative answers backed by your content.

What this unlocks

Your chat agent stops hallucinating and starts citing. When a user asks about "neural network optimization," the agent searches your books, finds the relevant paragraph from Chapter 4 of Advanced Machine Learning, and answers with a direct citation.

The basics

The /search endpoint performs hybrid search: traditional keyword matching plus semantic vector search. You get results ranked by relevance, each containing a content snippet, source URL, and metadata.

Method: GET https://cashmere.io/api/v2/search

Auth: Bearer token (find yours in the Cashmere dashboard)

Cost: Tokens deducted per result returned, based on content length

Implementation flow

1. Get your credentials

Navigate to the Cashmere dashboard. Click "API Keys" in the left sidebar. Generate a new key with search permissions. Copy it immediately; you won't see it again.

2. Make your first search request

curl "https://cashmere.io/api/v2/search?q=machine+learning&limit=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use this first request to confirm that your API key can access licensed content and that search results are available for a known topic. For exact response fields and request options, see the API documentation.

3. Wire it into your chat agent

Here's a minimal implementation in TypeScript that your agent can call as a retrieval tool:

async function searchPublications(query: string): Promise<SearchResult[]> {
  const response = await fetch(
    `https://cashmere.io/api/v2/search?q=${encodeURIComponent(query)}&limit=5&external_ids=${encodeURIComponent("agent-session-id")}`,
    {
      headers: { Authorization: `Bearer ${process.env.CASHMERE_API_KEY}` }
    }
  );

  if (!response.ok) {
    throw new Error(`Search failed: ${response.status}`);
  }

  const results = await response.json();
  return results.filter(r => r.score > 0.7); // Filter out noise
}

4. Handle the response

Pass the most relevant retrieved passages to your LLM along with each result's view_source_url and section context. Instruct the model to cite the view_source_url when it uses a passage in an answer, unmodified. A link expires 24 hours after its first click (except in collections that need no license), so search again for a fresh link rather than caching old ones.

Best practices

Score thresholding: Adjust your score threshold to filter relevant responses to your query. ≥0.7 is usually a sweet spot, but on small data sets, a lower score may work well

Query preprocessing: Don't pass raw user questions to the search API. Use a small LLM to extract keywords first:

const keywords = await extractKeywords(userQuestion);
// "What are the latest trends in deep learning?" → "deep learning trends"

Search model selection: Use the API key's default search model unless you have a specific reason to override it. When you do override the model, use the current public model family:

  • vtups2r-1155: Standard hybrid relevance model without recency boost (the default)
  • vtups2r-1w: Hybrid search with stronger preference for very recent content
  • vtups2r-1m: Hybrid search with a month-scale recency preference
  • vtups2r-2y: Hybrid search with a broader recency preference for fast-moving fields
  • vtups2n-1155: Hybrid search with normalized score fusion instead of rank fusion
  • knn1-1: Semantic/vector-only search when you do not want text matching

The older vtups1-*, vtros1-* and hos1-11 models are deprecated. Responses that use one carry a Deprecation header naming the replacement.

For the complete list of supported values and exact parameter behavior, see the API documentation.

Common mistakes

Searching owned content: The API only searches content you've licensed through Cashmere. If you publish books, you must license them to yourself first: POST /api/v2/licenses with your own organization's target_organization_handle. Check your licenses in the dashboard.

High limits: limit=100 on broad queries returns a large set of results and can crowd the LLMs context window, producing poor results. Limit it and filter with relevance/recency to get the targeted results you want

Testing your implementation

Start with a known query that exists in your licensed content. Verify that:

  1. Results return with the score you set
  2. view_source_url links work
  3. Token consumption appears in your dashboard
  4. The generated answer properly cites sources

If no results appear, check:

  • Is the content licensed? (Check the dashboard)
  • Is the query specific enough? (Try exact phrases from your books)
  • Are you using the correct API key with search permissions?