Skip to main content

​
Overview

For most use cases, the default cuey instance with environment variables is sufficient. This section covers advanced configuration options, including creating custom instances and using multiple API keys.

​
Configuration Options

The Cuey class accepts optional configuration options:
​
CueyConfig
object
Configuration options for creating a custom Cuey instance.

​
Environment Variables

The SDK supports the following environment variables:
​
CUEY_API_KEY
string
required
API key for authentication. Required if not provided in constructor config.
​
CUEY_BASE_URL
string
Base URL for resolving relative webhook URLs. Optional. Used when webhook URLs are provided as relative paths (starting with /).

​
Creating Custom Instances

​
Explicit Configuration

Create a custom instance with explicit configuration: 
import { Cuey } from "cuey";

const cuey = new Cuey({
  apiKey: "your-api-key-here",
  baseUrl: "https://api.example.com",
});

// Relative URL will be resolved to https://api.example.com/webhook
await cuey.events.create({
  webhook_url: "/webhook",
  scheduled_at: "2024-12-31T23:59:59Z",
});

​
Mixed Configuration

You can mix explicit config with environment variables (see examples above).

​
Webhook URL Resolution

The baseUrl configuration affects how webhook URLs are resolved:

​
Full URLs

If you provide a full URL (starting with http:// or https://), baseUrl is ignored (see example above).

​
Relative URLs

If you provide a relative URL (starting with /), it’s resolved against baseUrl (see example above).
If baseUrl is not configured and you use a relative URL, an error will be thrown.

​
Base URL Configuration Examples

If most of your webhooks target the same base URL, set CUEY_BASE_URL as an environment variable. This lets you use relative paths instead of full URLs.
CUEY_BASE_URLwebhook_urlValidResolved URL
https://api.example.com/v1/api/webhook✅https://api.example.com/v1/api/webhook
https://api.example.com/v1/api/webhook/endpoint✅https://api.example.com/v1/api/webhook/endpoint
https://api.example.com/v1/apihttps://api.example.com/v1/api/webhook✅https://api.example.com/v1/api/webhook
https://api.example.com/v1/apihttps://other-domain.com/webhook✅https://other-domain.com/webhook
not sethttps://api.example.com/webhook✅https://api.example.com/webhook
https://api.example.com/v1/apiwebhook (no leading slash)❌Error: relative paths must start with /
not set/webhook❌Error: CUEY_BASE_URL must be set when using relative paths
https://api.example.com/v1/api/ (trailing slash)/webhook⚠️https://api.example.com/v1/api//webhook (double slash)

​
API Key Resolution

The API key is resolved in the following order:
  1. Explicit apiKey in constructor config
  2. CUEY_API_KEY environment variable
  3. Error thrown if neither is provided
If neither apiKey nor CUEY_API_KEY is set, creating a client instance will throw an error.

​
Use Cases

​
Multiple API Keys

Create multiple instances with different API keys (see example above).

​
Environment-Specific Configuration

Use different configurations for different environments (see example above).

​
Using dotenv

Load environment variables from a .env file (see example above).
Never commit .env files containing API keys to version control.

Error Handling

Understand error handling patterns.

Types Reference

See all available TypeScript types.