Skip to main content
The NarrativeApi class accepts a configuration object that controls authentication, environment targeting, and request behavior.

​
Constructor options

import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';

const api = new NarrativeApi({
  apiKey: 'your-api-key',
  environment: 'prod',
  headers: {},
  verbose: false,
});
OptionTypeDefaultDescription
apiKeystringundefinedAPI key for authentication. Passed as a Bearer token.
environment'prod' | 'dev' | string'prod'Target environment or custom base URL
headersRecord<string, string>{}Additional HTTP headers to include in requests
verbosebooleanfalseEnable verbose logging (automatically enabled in dev)

​
Environment URLs

The SDK supports two built-in environments, or you can specify a custom URL:
EnvironmentBase URL
prodhttps://api.narrative.io/
devhttps://api-dev.narrative.io/
CustomAny valid URL you provide

​
Configuration examples

​
Production (default)

const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
});

​
Development environment

const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
  environment: 'dev',
});

​
Custom base URL

For self-hosted or custom deployments: 
const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
  environment: 'https://custom.narrative.example.com/',
});

​
Enable verbose logging

Useful for debugging API requests: 
const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
  verbose: true,
});
When verbose mode is enabled, the SDK logs:
  • Request URLs and methods
  • Request payloads
  • Response data
  • Configuration details
Verbose mode is automatically enabled when using the dev environment.

​
Custom headers

Add custom headers to all requests: 
const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
  headers: {
    'X-Custom-Header': 'custom-value',
  },
});

​
Runtime configuration

You can update the API key after initialization: 
const api = new NarrativeApi({});

// Set API key later
api.setApiKey('new-api-key');

// Get current API key
const currentKey = api.getApiKey();

// Get current environment
const environment = api.getEnvironment();

// Get base URL
const baseUrl = api.getBaseUrl();

​
Environment variables

While the SDK doesn’t automatically read environment variables, the recommended pattern is: 
const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
  environment: process.env.NARRATIVE_ENVIRONMENT || 'prod',
});
VariableDescription
NARRATIVE_API_KEYYour API key for authentication
NARRATIVE_ENVIRONMENTTarget environment (prod, dev, or custom URL)

​
TypeScript types

The SDK exports configuration types for TypeScript users: 
import type { Config, Environment } from '@narrative.io/data-collaboration-sdk-ts';

const config: Config = {
  apiKey: process.env.NARRATIVE_API_KEY,
  environment: 'prod' as Environment,
};

const api = new NarrativeApi(config);

​
Related content

API Keys

Create and manage API keys

Authentication Guide

Authentication best practices

SDK Overview

TypeScript SDK overview

API Modules

Available API methods