> ## 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.

# Configuration

> Complete reference for SDK configuration options

## Full Configuration

```typescript theme={null}
import { Refine } from '@refine-ai/sdk';

const refine = new Refine({
  // Required
  apiKey: 'your-api-key',
  organizationId: 'org-uuid',
  catalogId: 'catalog-uuid',
  
  // Optional
  applicationType: 'web',
  debug: false,
  
  // Event tracking configuration
  events: {
    enabled: true,
    batchSize: 10,
    flushInterval: 5000,
    maxQueueSize: 1000,
    maxRetries: 3,
    persistence: 'localStorage',
    sessionTimeout: 30 * 60 * 1000
  },
  
  // Privacy configuration
  privacy: {
    respectDoNotTrack: false,
    anonymizeIp: false,
    requireConsent: false
  },
  
  // Global error handler
  onError: (error) => {
    console.error('Refine error:', error);
  }
});
```

## Required Options

<ResponseField name="apiKey" type="string" required>
  Your Refine API key. Obtain from Dashboard → Settings → API Keys.
</ResponseField>

<ResponseField name="organizationId" type="string" required>
  Your organization UUID. Find at Dashboard → Settings → Organization.
</ResponseField>

<ResponseField name="catalogId" type="string" required>
  The catalog to search. Find at Dashboard → Catalogs.
</ResponseField>

## Optional Options

<ResponseField name="applicationType" type="string" default="web">
  Application type identifier. Values: `'web'`, `'mobile'`, `'server'`.
</ResponseField>

<ResponseField name="debug" type="boolean" default="false">
  Enable debug logging. Logs all requests, responses, and events to the console.
</ResponseField>

<ResponseField name="onError" type="(error: RefineError) => void">
  Global error handler called for all SDK errors. Useful for centralized error reporting.
</ResponseField>

## Events Configuration

Control how events are batched, stored, and transmitted.

```typescript theme={null}
events: {
  enabled: true,
  batchSize: 10,
  flushInterval: 5000,
  maxQueueSize: 1000,
  maxRetries: 3,
  persistence: 'localStorage',
  sessionTimeout: 30 * 60 * 1000
}
```

<ResponseField name="events.enabled" type="boolean" default="true">
  Enable or disable event tracking entirely.
</ResponseField>

<ResponseField name="events.batchSize" type="number" default="10">
  Number of events to batch before sending. Lower values = more frequent requests but fresher data.
</ResponseField>

<ResponseField name="events.flushInterval" type="number" default="5000">
  Maximum time (ms) between flushes, regardless of batch size.
</ResponseField>

<ResponseField name="events.maxQueueSize" type="number" default="1000">
  Maximum events to queue. Oldest events are dropped when exceeded.
</ResponseField>

<ResponseField name="events.maxRetries" type="number" default="3">
  Retry attempts for failed event submissions.
</ResponseField>

<ResponseField name="events.persistence" type="string" default="localStorage">
  Where to persist the event queue. Options:

  * `'localStorage'` — Survives page refreshes (browser only)
  * `'sessionStorage'` — Cleared on tab close
  * `'memory'` — No persistence (lost on refresh)
  * `'none'` — Disable persistence
</ResponseField>

<ResponseField name="events.sessionTimeout" type="number" default="1800000">
  Session timeout in milliseconds. Default is 30 minutes (30 \* 60 \* 1000).
</ResponseField>

## Privacy Configuration

GDPR and privacy-related options.

```typescript theme={null}
privacy: {
  respectDoNotTrack: false,
  anonymizeIp: false,
  requireConsent: false
}
```

<ResponseField name="privacy.respectDoNotTrack" type="boolean" default="false">
  When `true`, disables tracking if the browser's Do Not Track setting is enabled.
</ResponseField>

<ResponseField name="privacy.anonymizeIp" type="boolean" default="false">
  When `true`, IP addresses are anonymized before storage.
</ResponseField>

<ResponseField name="privacy.requireConsent" type="boolean" default="false">
  When `true`, event tracking is paused until consent is granted via the ConsentPlugin.
</ResponseField>

## Configuration Patterns

### Development vs Production

```typescript theme={null}
const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: process.env.REFINE_ORG_ID,
  catalogId: process.env.REFINE_CATALOG_ID,
  debug: process.env.NODE_ENV === 'development',
  events: {
    enabled: process.env.NODE_ENV === 'production',
    persistence: process.env.NODE_ENV === 'production' 
      ? 'localStorage' 
      : 'memory'
  }
});
```

### GDPR Compliance

```typescript theme={null}
import { Refine, ConsentPlugin } from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789',
  privacy: {
    respectDoNotTrack: true,
    anonymizeIp: true,
    requireConsent: true
  }
});

const consentPlugin = new ConsentPlugin({
  required: true,
  onConsentRequired: () => {
    showConsentBanner();
  }
});

refine.use(consentPlugin);

// When user grants consent
function handleConsentGranted() {
  consentPlugin.grant();
}
```

### High-Volume Sites

For high-traffic applications, increase batch size and queue limits:

```typescript theme={null}
const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789',
  events: {
    batchSize: 50,
    flushInterval: 10000,
    maxQueueSize: 5000,
    maxRetries: 5
  }
});
```

### Server-Side Rendering

For SSR environments where localStorage isn't available:

```typescript theme={null}
const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789',
  applicationType: 'server',
  events: {
    persistence: 'memory'
  }
});
```

## Updating Configuration

The SDK doesn't support runtime configuration changes. Create a new instance if you need different settings:

```typescript theme={null}
// Don't do this
refine.config.debug = true; // ❌ Won't work

// Do this instead
const debugRefine = new Refine({
  ...baseConfig,
  debug: true
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Text Search" icon="magnifying-glass" href="/sdk/search/text-search">
    Start searching
  </Card>

  <Card title="Plugins" icon="plug" href="/sdk/plugins/overview">
    Extend SDK functionality
  </Card>
</CardGroup>