> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#custom-fetch)).

## Installation

```bash theme={null}
npm install @rootly/ts
```

```bash theme={null}
yarn add @rootly/ts
```

```bash theme={null}
pnpm add @rootly/ts
```

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

```javascript theme={null}
const { RootlyClient } = require("@rootly/ts");
```

## Quick Start

```typescript theme={null}
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

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

### Get an Incident

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

### Create an Incident

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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

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

### Custom Fetch

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

```typescript theme={null}
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:

```typescript theme={null}
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](https://www.npmjs.com/package/@rootly/ts)
* **Source Code**: [GitHub Repository](https://github.com/rootlyhq/rootly-ts)
* **Issues**: [GitHub Issues](https://github.com/rootlyhq/rootly-ts/issues)