TypeScript SDK

Type-safe TypeScript client for the Rootly API, powered by openapi-typescript and openapi-fetch, for incident, alert, and on-call automation in Node.js.

The Rootly TypeScript SDK (@rootly/ts) is a type-safe client for the Rootly API. Types are generated directly from the OpenAPI specification, giving you full autocomplete and compile-time safety for every endpoint, parameter, and response.

Features

• Zero runtime overhead — types are generated at build time, not runtime
• Full type safety — every endpoint, parameter, and response is typed from the OpenAPI spec
• Tiny footprint — openapi-fetch is ~6 KB and wraps the native fetch
• ESM and CommonJS — works in Node.js, Deno, Bun, and modern bundlers
• Typed errors — API error responses are typed per status code

Requirements

Any JavaScript runtime with a native fetch implementation:

• Node.js 20+
• Deno, Bun, or modern bundlers (Vite, webpack, esbuild, etc.)
• Modern browsers

On older Node.js versions, supply a fetch polyfill via the fetch option (see Custom Fetch).

Installation

npm install @rootly/ts

yarn add @rootly/ts

pnpm add @rootly/ts

The package ships both ESM and CommonJS builds. In a CommonJS project, use require:

const { RootlyClient } = require("@rootly/ts");

Quick Start

import { RootlyClient } from "@rootly/ts";

const rootly = new RootlyClient({
  token: process.env.ROOTLY_API_TOKEN!,
});

Getting an API Key

1. Log in to your Rootly account
2. Navigate to Settings > API Keys
3. Create a new API key with the permissions you need

Usage

List Incidents

const { data, error } = await rootly.client.GET("/v1/incidents", {
  params: {
    query: {
      "page[number]": 1,
      "page[size]": 10,
      "filter[status]": "started",
    },
  },
});

Get an Incident

const { data, error } = await rootly.client.GET("/v1/incidents/{id}", {
  params: { path: { id: "abc123" } },
});

Create an Incident

const { data, error } = await rootly.client.POST("/v1/incidents", {
  body: {
    data: {
      type: "incidents",
      attributes: {
        title: "Service degradation",
        kind: "normal",
        summary: "Users are experiencing elevated latency",
        severity_id: "sev-1",
      },
    },
  },
});

Update an Incident

const { data, error } = await rootly.client.PATCH("/v1/incidents/{id}", {
  params: { path: { id: "abc123" } },
  body: {
    data: {
      type: "incidents",
      attributes: {
        summary: "Root cause identified",
      },
    },
  },
});

Error Handling

async function fetchIncident(id: string) {
  const { data, error } = await rootly.client.GET("/v1/incidents/{id}", {
    params: { path: { id } },
  });

  if (error) {
    console.error("Request failed:", error);
    throw error;
  }

  return data;
}

error is typed per status code (e.g. 401, 404), and data is typed with the endpoint’s response schema.

Using Types

Import generated schemas directly for DTOs, validation, or UI code:

import type { components } from "@rootly/ts";

type Incident = components["schemas"]["incident"];
type IncidentResponse = components["schemas"]["incident_response"];
type NewIncident = components["schemas"]["new_incident"];
type Service = components["schemas"]["service"];
type ErrorsList = components["schemas"]["errors_list"];

Configuration

Custom Base URL

const rootly = new RootlyClient({
  token: "your-token",
  baseUrl: "https://custom.rootly.com",
});

Custom Fetch

Pass a custom fetch implementation for testing, retries, or logging:

const rootly = new RootlyClient({
  token: "your-token",
  fetch: customFetchImplementation,
});

Advanced Usage

For direct access to the underlying openapi-fetch client with full type inference and middleware support:

import { createClient, createAuthMiddleware, type paths } from "@rootly/ts";

const client = createClient<paths>({
  baseUrl: "https://api.rootly.com",
});

client.use(createAuthMiddleware("your-token"));

Feedback & Support

• Package: @rootly/ts on npm
• Source Code: GitHub Repository
• Issues: GitHub Issues