JavaScript SDK Getting Started | SocialRails Documentation

The official JavaScript/TypeScript SDK for the SocialRails API. Zero dependencies, full TypeScript support, works in Node.js 18+, Deno, Bun, and modern browsers.

Installation

npm install @socialrails/js

yarn add @socialrails/js

pnpm add @socialrails/js

Quick Start

 
const sr = new SocialRails({ apiKey: 'sr_live_...' });
 
const post = await sr.posts.create({
  content: 'Hello from SocialRails!',
  platform: 'twitter',
  scheduled_for: '2026-03-10T14:00:00Z',
});
 
console.log(post.id, post.status);

Configuration

Option	Type	Default	Description
`apiKey`	`string`	`process.env.SOCIALRAILS_API_KEY`	Your API key (starts with `sr_live_`)
`baseUrl`	`string`	`https://socialrails.com/api/v1`	API base URL

You can also set the SOCIALRAILS_API_KEY environment variable:

export SOCIALRAILS_API_KEY=sr_live_your_key_here

const sr = new SocialRails(); // picks up the env var

Error Handling

All API errors are thrown as SocialRailsError instances:

 
try {
  await sr.posts.create({ content: '', platform: 'twitter' });
} catch (error) {
  if (error instanceof SocialRailsError) {
    console.error(error.message); // Human-readable message
    console.error(error.code);    // e.g. "validation_error"
    console.error(error.status);  // e.g. 422
  }
}

Code	Status	Description
`invalid_api_key`	401	API key is missing or invalid
`rate_limit_exceeded`	429	Too many requests
`validation_error`	422	Request body failed validation
`not_found`	404	Resource does not exist
`server_error`	500	Internal server error

TypeScript

The SDK ships with complete type definitions:

Requirements

Node.js 18+ (uses native fetch)
Deno — works out of the box
Bun — works out of the box
Browsers — any modern browser with fetch support

Next Steps

See the JavaScript SDK Reference for the full API reference.