Skip to main content
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