{"id":12163,"library":"trieve-ts-sdk","title":"Trieve TypeScript SDK","description":"The `trieve-ts-sdk` is a TypeScript SDK designed to interact with the Trieve API, providing a comprehensive and type-safe interface for integrating Trieve's search, RAG (Retrieval Augmented Generation), and analytics capabilities into applications. As of version 0.0.124, it offers functionalities like semantic and hybrid search, support for MMR (Maximum Marginal Relevance) and recency bias, dataset management, and advanced analytics tracking. The SDK facilitates common operations such as creating chunks, performing queries, and managing topics. It also ships with React components for search and RAG, enabling quicker integration into front-end projects. The Trieve ecosystem, which this SDK interfaces with, has a frequent release cadence, with major updates often introducing new API features like improved analytics, scraping support, and refined API key scoping. Its key differentiators include its focus on search relevance, rich API feature set for RAG, and first-class TypeScript support, making it an ideal choice for developers building AI-powered search experiences.","status":"active","version":"0.0.124","language":"javascript","source_language":"en","source_url":"https://github.com/devflowinc/trieve","tags":["javascript","trieve","sdk","typescript","search","api"],"install":[{"cmd":"npm install trieve-ts-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add trieve-ts-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add trieve-ts-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The SDK is primarily designed for ESM environments, leveraging TypeScript for type safety. While CommonJS might technically work via transpilation, ESM is the canonical usage.","wrong":"const TrieveSDK = require('trieve-ts-sdk').TrieveSDK;","symbol":"TrieveSDK","correct":"import { TrieveSDK } from 'trieve-ts-sdk';"},{"note":"Types are exported directly from the main package entry point. Using `import type` is recommended for type-only imports in TypeScript for better tree-shaking.","wrong":"import SearchPayload from 'trieve-ts-sdk/dist/types/SearchPayload';","symbol":"SearchPayload","correct":"import type { SearchPayload } from 'trieve-ts-sdk';"},{"note":"All core types and function interfaces are exposed at the top level of the SDK for convenience.","wrong":"import { SuggestedQueriesResponse } from 'trieve-ts-sdk/functions/chunks';","symbol":"SuggestedQueriesResponse","correct":"import type { SuggestedQueriesResponse } from 'trieve-ts-sdk';"},{"note":"While functions might reside in sub-directories internally, they are re-exported at the package root.","wrong":"import { getChunksByTrackingIds } from 'trieve-ts-sdk/functions/chunks/index';","symbol":"getChunksByTrackingIds","correct":"import { getChunksByTrackingIds } from 'trieve-ts-sdk';"}],"quickstart":{"code":"import { TrieveSDK } from \"trieve-ts-sdk\";\nimport type { SearchPayload } from \"trieve-ts-sdk\"; // Explicitly import a type for clarity\n\n// Initialize the Trieve SDK client with your API key and dataset ID.\n// It's recommended to load these from environment variables for production applications.\nconst trieve = new TrieveSDK({\n  apiKey: process.env.TRIEVE_API_KEY ?? \"\", // Replace with your actual Trieve API Key\n  datasetId: process.env.TRIEVE_DATASET_ID ?? \"\", // Replace with your actual Trieve Dataset ID\n});\n\nasync function performSearch(queryText: string) {\n  if (!process.env.TRIEVE_API_KEY || !process.env.TRIEVE_DATASET_ID) {\n    console.error(\"Missing TRIEVE_API_KEY or TRIEVE_DATASET_ID environment variables. Please set them.\");\n    return;\n  }\n\n  const searchPayload: SearchPayload = {\n    query: queryText,\n    search_type: \"hybrid\", // You can also use \"semantic\" or \"fulltext\"\n    filters: {}, // Optional: Add filters to narrow down search results\n    page: 1,\n    page_size: 10,\n    highlight_results: true,\n  };\n\n  try {\n    console.log(`Searching for: \"${queryText}\" in dataset \"${trieve.datasetId}\"...`);\n    const data = await trieve.search(searchPayload);\n    console.log(\"Search Results:\", JSON.stringify(data, null, 2));\n\n    if (data.hits && data.hits.length > 0) {\n      console.log(`Found ${data.hits.length} relevant results.`);\n      data.hits.forEach((hit, index) => {\n        console.log(`Result ${index + 1}: ${hit.chunk_html ?? hit.link ?? 'No content preview'}`);\n      });\n    } else {\n      console.log(\"No results found for your query.\");\n    }\n  } catch (error) {\n    console.error(\"Error during Trieve search:\", error);\n  }\n}\n\n// Example usage:\nperformSearch(\"What are the key features of the Trieve API and how do I use them?\");","lang":"typescript","description":"Initializes the Trieve TypeScript SDK and demonstrates how to perform a hybrid search query against a Trieve dataset using environment variables for credentials."},"warnings":[{"fix":"Review your Trieve dashboard for API key management and ensure your `apiKey` is correctly configured for your organization and dataset. Update API keys if they were previously tied to individual users rather than organizations.","message":"The underlying Trieve API, which this SDK communicates with, underwent a significant change in v0.13.0 where API keys were refactored to be scoped to organizations. This may require reconfiguring how API keys are generated and used within your Trieve account and subsequently with the SDK.","severity":"breaking","affected_versions":">=0.0.124 (Trieve API v0.13.0+)"},{"fix":"Migrate direct `fetch` or `axios` calls to the Trieve API by instantiating `TrieveSDK` and using its provided methods (e.g., `trieve.search()`, `trieve.createChunk()`). Leverage the SDK's exported types for full type-checking.","message":"The `trieve-ts-sdk` itself was newly introduced around Trieve project version v0.11.8. Projects previously integrating with the Trieve API via direct REST calls will need to refactor their codebase to utilize the SDK's typed client and methods for improved maintainability and type safety.","severity":"breaking","affected_versions":"<0.0.1 (prior to SDK existence)"},{"fix":"Always check both the `trieve-ts-sdk` npm page and the main Trieve GitHub repository/documentation for the latest compatibility information and changelogs before upgrading or developing.","message":"The `trieve-ts-sdk` package versioning (e.g., `0.0.124`) might not directly align with the main `trieve` project's API versioning (e.g., `v0.13.0`). Users should consult both the SDK's changelog and the main Trieve project's release notes for a complete understanding of breaking changes or new features that might affect the SDK's behavior or available API surface.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Consult Trieve API documentation for current limits and best practices for batch operations. Implement retry logic or chunk large payloads to stay within configured limits.","message":"When performing batch chunk creation or other operations that might be resource-intensive, be aware that the underlying Trieve API might have limits configurable via environment flags (e.g., `BATCH_CHUNK_LIMIT` as of Trieve v0.13.0). Exceeding these limits without proper handling can lead to API errors.","severity":"gotcha","affected_versions":">=0.0.1 (Trieve API v0.13.0+)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `process.env.TRIEVE_API_KEY` (or direct `apiKey` value) is correctly set with a valid, active API key obtained from your Trieve dashboard. Verify the API key has the required permissions for your dataset and organization.","cause":"The `apiKey` provided to the `TrieveSDK` constructor is invalid, expired, or missing, or lacks the necessary permissions for the requested operation.","error":"TrieveAPIError: Missing or invalid API key"},{"fix":"Double-check the `process.env.TRIEVE_DATASET_ID` (or direct `datasetId` value) for typos. Confirm the dataset exists in your Trieve account and that the associated API key has the necessary read/write permissions for that dataset.","cause":"The `datasetId` provided to the `TrieveSDK` constructor does not correspond to an existing dataset in your Trieve account, or the provided API key does not have access to it.","error":"TrieveAPIError: Dataset with ID '<dataset-id>' not found"},{"fix":"Ensure you are using `import { TrieveSDK } from 'trieve-ts-sdk';` at the top of your file. If in a Node.js CommonJS environment, configure your project for ESM or consider an older SDK version/wrapper if available for CJS compatibility (though this SDK is primarily ESM-first).","cause":"This error typically occurs when attempting to use a CommonJS `require` syntax (`const { TrieveSDK } = require(...)`) in an environment expecting ESM `import`s, or if `TrieveSDK` is not properly imported from the package.","error":"TypeError: TrieveSDK is not a constructor"},{"fix":"Implement nullish coalescing (`?? ''`), optional chaining (`?.`), or explicit type guards (`if (variable) { ... }`) to ensure the value is of the expected type before passing it to SDK methods. For example, `apiKey: process.env.TRIEVE_API_KEY ?? ''`.","cause":"This is a common TypeScript error indicating that a variable could be `undefined` (or `null`) but the function or property expects a definite `string` (or other non-nullable type). This often happens when reading environment variables.","error":"Argument of type 'string | undefined' is not assignable to parameter of type 'string'."}],"ecosystem":"npm"}