> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinrefine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Refine SDK in your project

## Package Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @refine-ai/sdk
  ```

  ```bash yarn theme={null}
  yarn add @refine-ai/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @refine-ai/sdk
  ```
</CodeGroup>

## Basic Setup

```typescript theme={null}
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 |

<Warning>
  Never expose your API key in client-side code for production. Use environment variables and server-side rendering for sensitive operations.
</Warning>

## Environment Variables

### Next.js

```bash title=".env.local" theme={null}
REFINE_API_KEY=your_api_key_here
NEXT_PUBLIC_REFINE_ORG_ID=org_abc123
NEXT_PUBLIC_REFINE_CATALOG_ID=cat_xyz789
```

```typescript title="lib/refine.ts" theme={null}
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

```bash title=".env" theme={null}
VITE_REFINE_API_KEY=your_api_key_here
VITE_REFINE_ORG_ID=org_abc123
VITE_REFINE_CATALOG_ID=cat_xyz789
```

```typescript title="src/lib/refine.ts" theme={null}
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.

```typescript theme={null}
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:

```typescript title="lib/refine.ts" theme={null}
import { Refine } from '@refine-ai/sdk';

export const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789'
});
```

```typescript title="pages/search.tsx" theme={null}
import { refine } from '@/lib/refine';

const results = await refine.search.text({ query, topK: 24 });
```

## CDN Usage

For non-bundled environments, load directly via CDN:

```html theme={null}
<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>
```

<Note>
  CDN usage exposes your API key. Only use this for prototyping or internal tools.
</Note>

## Verify Installation

Test your setup:

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/sdk/configuration">
    Explore all configuration options
  </Card>

  <Card title="Quickstart" icon="rocket" href="/getting-started/quickstart">
    Build your first search
  </Card>
</CardGroup>