Skip to main content

TypeScript SDK Getting Started

@gravity-rail/sdk is a typed client for the whole Gravity Rail API: every resource in the API Reference has a corresponding method, with request and response types included. Use it from Node services, scripts, or browser applications.

Install​

npm install @gravity-rail/sdk

Zod schemas for runtime validation are an optional peer dependency (npm install zod). The package is @gravity-rail/sdk on npm.

Create a client​

import { GravityRailClient } from '@gravity-rail/sdk';

const client = new GravityRailClient(
  process.env.GRAVITY_RAIL_API_KEY,
  'https://api.gravityrail.com'
);

Create a scoped API key in workspace settings. Keys can be read-only, workspace-limited, or time-expiring — see the Authentication guide for the scope system, and for the OAuth2 + PKCE flow used by browser apps (pass undefined instead of a key and handle step-up with client.setEnhancedAuthHandler).

First calls​

// Workspaces available to this key
const workspaces = await client.getWorkspaces();
const workspaceId = workspaces[0].id;

// List Workflows in the workspace
const workflows = await client.getWorkflows(workspaceId);

// Active Chats across every channel
const chats = await client.getChats(workspaceId);

// Create a Member
const member = await client.createWorkspaceMember(workspaceId, {
  first_name: 'Jane',
  last_name: 'Rivera',
  email: 'jane.rivera@example.com',
  role_id: roleId,
});

Method names follow the resource names in the API Reference: getWorkflows, getChats, createWorkspaceMember, and so on. The SDK Reference documents every method, type, and builder; the GravityRailClient class page is the best starting point.

Error handling​

API failures throw a typed ApiError carrying the HTTP status code and the server's error details:

import { ApiError } from '@gravity-rail/sdk';

try {
  await client.getWorkflows(workspaceId);
} catch (error) {
  if (error instanceof ApiError && error.statusCode === 403) {
    // key lacks the required scope for this workspace
  }
  throw error;
}

See the Error Handling guide for status codes and retry guidance.

Next steps​