TypeScript SDK

The TypeScript SDK gives you a typed client for the whole incident.io API. There’s a method for every endpoint and a type for every request and response, all generated from our OpenAPI specification, so your editor can complete field names and the compiler catches mistakes before you run anything. It works from TypeScript or plain JavaScript, with both import and require, and has no runtime dependencies. It needs Node 20 or later (we recommend 22 or 24), or any runtime with a global fetch, and TypeScript 5.0 or later if you use TypeScript. The SDK is for server-side code. An API key in a browser is readable by anyone who loads the page, and the API doesn’t send the CORS headers a browser would need to call it directly.

Installing

npm install @incident-io/sdk

Your first request

You’ll need an API key from Settings > API keys (see API keys). Then:

import { Configuration, IncidentsV2Api } from '@incident-io/sdk';

const config = new Configuration({ accessToken: 'my-api-key' });
const client = new IncidentsV2Api(config);

const result = await client.incidentsV2List({ page_size: 25 });
for (const incident of result.incidents) {
  console.log(incident.reference, incident.name);
}

Finding an endpoint

Endpoints are grouped into one class per API resource and version, all built from the same Configuration. The endpoint the API reference calls Incidents V2 › List is incidentsV2List on IncidentsV2Api, and Alert Routes V2 › Create is alertRoutesV2Create on AlertRoutesV2Api. Field and parameter names are the API’s own, in snake_case, so they match the reference exactly. Each method takes one object holding the endpoint’s parameters. A request body goes under body:

const created = await client.incidentsV2Create({
  body: {
    idempotency_key: 'a-unique-key',
    visibility: 'public',
    name: 'Checkout is down',
  },
});
console.log(created.incident.reference);

If you need the status code or headers, every method has a ...Raw variant that returns the Response alongside the parsed body.

Pagination

List endpoints are cursor-paginated. Read the next cursor from pagination_meta.after and pass it back until there isn’t one:

let after: string | undefined;
do {
  const page = await client.incidentsV2List({ page_size: 100, after });
  for (const incident of page.incidents) {
    console.log(incident.reference, incident.name);
  }
  after = page.pagination_meta?.after;
} while (after);

Filtering

List endpoints take filters as nested objects, keyed by operator:

const live = await client.incidentsV2List({
  status_category: { one_of: ['live'] },
  created_at: { gte: ['2026-01-01'] },
});

Each list endpoint’s page in the API reference describes the filters and operators it accepts.

Errors

A response with a non-2xx status throws a ResponseError. Its body is the API’s standard error format, and ErrorResponseFromJSON gives you a typed version of it:

import { ErrorResponseFromJSON, ResponseError } from '@incident-io/sdk';

try {
  await client.incidentsV2Show({ id: '01ABC...' });
} catch (error) {
  if (error instanceof ResponseError) {
    const body = ErrorResponseFromJSON(await error.response.json());
    console.error(error.response.status, body.type, body.request_id, body.errors);
  } else {
    throw error;
  }
}

If you contact us about a failed request, include the request_id. A network failure throws a FetchError instead.

Configuration

const config = new Configuration({
  accessToken: 'my-api-key',
  basePath: 'https://api.incident.io', // the default
  headers: { 'User-Agent': 'my-app/1.0.0' }, // identify your integration
});

There’s no default timeout. Pass an AbortSignal in a request’s options, for example { signal: AbortSignal.timeout(10_000) } as the second argument to any method. The client makes a single attempt per request and doesn’t retry. When you hit the rate limit, the API answers with a 429 and a Retry-After header in seconds. The simplest place to retry is a wrapper around fetch, passed as fetchApi in the configuration. The README has an example.

Enums and new values

Enum fields are typed as a union of their known values. We add enum values as a backwards-compatible change, and a value your version doesn’t know about comes through as the string the API sent rather than failing the response. So if you switch over an enum, give it a default branch.

Deprecated endpoints

Endpoints we’ve deprecated stay available, but they’re marked @deprecated, so your editor strikes them through and linters can flag them. Don’t go by the version in the name: some v2 endpoints are deprecated too.

Versioning

The SDK is kept up to date with the API automatically. Additions to the API are minor versions. A change that would break your code, like a removed field, is released as a new major version, and its release notes list what changed.

Resources

npm

The @incident-io/sdk package and its versions.

GitHub

Source, README, and issues for the TypeScript SDK.

API reference

Endpoints, authentication, rate limits, and errors.

All SDKs

Clients for Go, Python, Rust, Ruby, PHP, and .NET.

Getting started

Alerts

On-call

Incident response

Post-incident

Status pages

Nexus

Investigations

AI features

Catalog

Workflows

Insights

Integrations

Administration

Need more help?

Installing

Your first request

Finding an endpoint

Filtering

Errors

Configuration

Enums and new values

Deprecated endpoints

Versioning

Resources

npm

GitHub

API reference

All SDKs

​Installing

​Your first request

​Finding an endpoint

​Pagination

​Filtering

​Errors

​Configuration

​Enums and new values

​Deprecated endpoints

​Versioning

​Resources

npm

GitHub

API reference

All SDKs

Installing

Your first request

Finding an endpoint

Pagination

Filtering

Errors

Configuration

Enums and new values

Deprecated endpoints

Versioning

Resources