Client Setup

Configure the VertaaUX client with authentication and optional settings.

Synopsis

import { VertaaUX } from '@vertaaux/sdk';

const client = new VertaaUX(config);

Configuration Options

Parameter	Type	Required	Description
apiKey	`string`	required	Your VertaaUX API key (starts with vx_live_ or vx_test_)
baseUrl	`string`	optional	API base URL. Defaults to 'https://vertaaux.ai/api/v1'
fetchFn	`typeof fetch`	optional	Custom fetch implementation for testing or proxying
idempotencyKey	`string`	optional	Idempotency key for request deduplication
retry	`RetryConfig`	optional	Retry configuration for transient failures

Basic Usage

The simplest configuration uses just your API key:

import { VertaaUX } from '@vertaaux/sdk';

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
});

Retry Configuration

The SDK includes built-in retry logic with exponential backoff for transient failures (429 rate limits and 5xx server errors).

RetryConfig Options

Parameter	Type	Required	Description
retries	`number`	optional	Number of retry attempts. Default: 2
baseDelayMs	`number`	optional	Initial delay in milliseconds. Default: 300

Exponential Backoff

Retries use exponential backoff: baseDelayMs * 2^attempt. With defaults:

Attempt	Delay
1	300ms
2	600ms
3	1200ms

If the server returns a Retry-After header, that value is used instead.

Custom Retry Settings

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
  retry: {
    retries: 3,       // Try up to 3 times
    baseDelayMs: 500, // Start with 500ms delay
  },
});

Disable Retries

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
  retry: {
    retries: 0, // No retries
  },
});

Custom Fetch

Provide a custom fetch implementation for testing, proxying, or logging:

Testing with Mock Fetch

import { VertaaUX } from '@vertaaux/sdk';

const mockFetch = async (url: string, init?: RequestInit) => {
  console.log('Request:', url, init?.method);

  // Return mock response
  return new Response(JSON.stringify({
    job_id: 'test_job_123',
    status: 'queued',
    created_at: new Date().toISOString(),
    ruleset_version: '1.0.0',
  }), {
    status: 202,
    headers: { 'Content-Type': 'application/json' },
  });
};

const client = new VertaaUX({
  apiKey: 'vx_test_mock',
  fetchFn: mockFetch,
});

Proxy Requests

import { VertaaUX } from '@vertaaux/sdk';

const proxyFetch = async (url: string, init?: RequestInit) => {
  // Route through your proxy
  const proxyUrl = url.replace('https://vertaaux.ai', 'https://proxy.internal');
  return fetch(proxyUrl, init);
};

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
  fetchFn: proxyFetch,
});

Idempotency Keys

Use idempotency keys to safely retry requests without duplicate side effects:

import { VertaaUX, generateIdempotencyKey } from '@vertaaux/sdk';

// Generate a unique key for this operation
const idempotencyKey = generateIdempotencyKey();

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
  idempotencyKey,
});

// If this request is retried with the same key,
// the server returns the original response
const job = await client.audits.create({ url: 'https://example.com' });

Idempotency keys are valid for 24 hours. The same key always returns the same response within that window.

Full Configuration Example

import { VertaaUX, generateIdempotencyKey } from '@vertaaux/sdk';

const client = new VertaaUX({
  // Required
  apiKey: process.env.VERTAA_API_KEY!,

  // Optional: Custom API URL (enterprise only)
  baseUrl: 'https://api.enterprise.vertaaux.ai/v1',

  // Optional: Retry configuration
  retry: {
    retries: 3,
    baseDelayMs: 500,
  },

  // Optional: Request deduplication
  idempotencyKey: generateIdempotencyKey(),
});

// Use the client
const job = await client.audits.create({
  url: 'https://example.com',
  mode: 'standard',
});

Client Methods

Once initialized, the client exposes these methods:

Method	Description
`client.audits.create(params)`	Create a new audit
`client.audits.get(jobId)`	Get audit status/results
`client.getQuota()`	Check quota and usage
`client.webhooks.create(params)`	Register a webhook
`client.webhooks.list()`	List all webhooks
`client.webhooks.delete(id)`	Delete a webhook

See Audit Methods and Webhook Methods for detailed documentation.

Audit Methods - Create and poll audits
Error Handling - Handle API errors
API Authentication - How API keys work

Was this page helpful?

Client Setup

On this page