Package Installation
npm install @refine-ai/sdk
Basic Setup
import { Refine } from '@refine-ai/sdk';
const refine = new Refine({
apiKey: process.env.REFINE_API_KEY,
organizationId: 'org_abc123',
catalogId: 'cat_xyz789'
});
Credentials
You’ll need three credentials from your Refine dashboard:
| Credential | Description | Where to Find |
|---|
apiKey | Authentication key | Dashboard → Settings → API Keys |
organizationId | Your organization UUID | Dashboard → Settings → Organization |
catalogId | Target catalog UUID | Dashboard → Catalogs → Select Catalog |
Never expose your API key in client-side code for production. Use environment variables and server-side rendering for sensitive operations.
Environment Variables
Next.js
REFINE_API_KEY=your_api_key_here
NEXT_PUBLIC_REFINE_ORG_ID=org_abc123
NEXT_PUBLIC_REFINE_CATALOG_ID=cat_xyz789
import { Refine } from '@refine-ai/sdk';
export const refine = new Refine({
apiKey: process.env.REFINE_API_KEY,
organizationId: process.env.NEXT_PUBLIC_REFINE_ORG_ID,
catalogId: process.env.NEXT_PUBLIC_REFINE_CATALOG_ID
});
Vite
VITE_REFINE_API_KEY=your_api_key_here
VITE_REFINE_ORG_ID=org_abc123
VITE_REFINE_CATALOG_ID=cat_xyz789
import { Refine } from '@refine-ai/sdk';
export const refine = new Refine({
apiKey: import.meta.env.VITE_REFINE_API_KEY,
organizationId: import.meta.env.VITE_REFINE_ORG_ID,
catalogId: import.meta.env.VITE_REFINE_CATALOG_ID
});
TypeScript Support
The SDK is written in TypeScript and includes full type definitions. No additional @types packages are needed.
import {
Refine,
SearchResponse,
RecommendationResponse,
RefineValidationError
} from '@refine-ai/sdk';
const results: SearchResponse = await refine.search.text({
query: 'shoes',
topK: 20
});
Singleton Pattern
For most applications, create a single SDK instance and export it:
import { Refine } from '@refine-ai/sdk';
export const refine = new Refine({
apiKey: process.env.REFINE_API_KEY,
organizationId: 'org_abc123',
catalogId: 'cat_xyz789'
});
import { refine } from '@/lib/refine';
const results = await refine.search.text({ query, topK: 24 });
CDN Usage
For non-bundled environments, load directly via CDN:
<script src="https://unpkg.com/@refine-ai/sdk@latest/dist/refine.min.js"></script>
<script>
const refine = new Refine.default({
apiKey: 'your-api-key',
organizationId: 'org_abc123',
catalogId: 'cat_xyz789'
});
</script>
CDN usage exposes your API key. Only use this for prototyping or internal tools.
Verify Installation
Test your setup:
import { Refine } from '@refine-ai/sdk';
const refine = new Refine({
apiKey: process.env.REFINE_API_KEY,
organizationId: 'org_abc123',
catalogId: 'cat_xyz789',
debug: true // Enables console logging
});
// This should log request details and return results
const results = await refine.search.text({
query: 'test',
topK: 5
});
console.log('SDK working:', results.results.length > 0);
Next Steps
