incidentio

On-call, incident response and status pages all under one roof.

[!NOTE]
Please note this SDK has not been tested and is not yet for production use. It is primarily to showcase Speakeasy's generation capabilities using the Incident.io OpenAPI specification

Summary

incident.io: This is the API reference for incident.io.

It documents available API endpoints, provides examples of how to use it, and instructions around things like authentication and error handling.

The API is hosted at:

• https://api.incident.io/

And you will need to create an API key via your incident.io dashboard to make requests.

Making requests

Here are the key concepts required to make requests to the incident.io API.

Authentication

For all requests made to the incident.io API, you'll need an API key.

To create an API key, head to the incident dashboard and visit API keys. When you create the key, you'll be able to choose what actions it can take for your account: choose carefully, as those roles can only be set when you first create the key. We'll only show you the token once, so make sure you store it somewhere safe.

Once you have the key, you should make requests to the API that set the Authorization request header using a "Bearer" authentication scheme:

Authorization: Bearer <YOUR_API_KEY>

Errors

We use standard HTTP response codes to indicate the status or failure of API requests.

The API response body will be JSON, and contain more detailed information on the nature of the error.

An example error when a request is made without an API key:

{
  "type": "authentication_error",
  "status": 401,
  "request_id": "8e3cc412-b49d-4957-9073-2c19d2c61804",
  "errors": [
    {
      "code": "missing_authorization_material",
      "message": "No authorization material provided in request"
    }
  ]
}

Note that the error:

• Contains the HTTP status (401)
• References the type of error (authentication_error)
• Includes a request_id that can be provided to incident.io support to help debug questions with your API request
• Provides a list of individual errors, which go into detail about why the error occurred

The most common error will be a 422 Validation Error, which is returned when the request was rejected due to failing validations.

These errors look like this:

{
  "type": "validation_error",
  "status": 422,
  "request_id": "631766c4-4afd-4803-997c-cd700928fa4b",
  "errors": [
    {
      "code": "is_required",
      "message": "A severity is required to open an incident",
      "source": {
        "field": "severity_id"
      }
    }
  ]
}

This error is caused by not providing a severity identifier, which should be at the severity_id field of the request payload. Errors like these can be mapped to forms, should you be integrating with the API from a user-interface.

Compatibility

We won't make breaking changes to existing API services or endpoints, but will expect integrators to upgrade themselves to the latest API endpoints within 3 months of us deprecating the old service.

We will make changes that are considered backwards compatible, which include:

• Adding new API endpoints and services
• Adding new properties to responses from existing API endpoints
• Reordering properties returned from existing API endpoints
• Adding optional request parameters to existing API endpoints
• Altering the format or length of IDs
• Adding new values to enums

It is important that clients are robust to these changes, to ensure reliable integrations.

As an example, if you are generating a client using an openapi-generator, ensure the generated client is configured to support unknown enum values, often configured via the enumUnknownDefaultCase parameter.

When breaking changes are unavoidable, we'll create a new service version on a separate path, and run them in parallel.

For example:

• https://api.incident.io/v1/incidents
• https://api.incident.io/v2/incidents

For any questions, email [e-mail].

Table of Contents

• SDK Installation
• Requirements
• SDK Example Usage
• Available Resources and Operations
• Standalone functions
• Retries
• Error Handling
• Server Selection
• Custom HTTP Client
• Debugging

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add incidentio

PNPM

pnpm add incidentio

Bun

bun add incidentio

Yarn

yarn add incidentio zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

SDK Example Usage

Example

import { Incidentio } from "incidentio";

const incidentio = new Incidentio();

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  });

  // Handle the result
  console.log(result);
}

run();

Available Resources and Operations

Available methods

actions

• list - List Actions V1 :warning: Deprecated
• get - Show Actions V1 :warning: Deprecated

actionsV2

• list - List Actions V2
• get - Show Actions V2

alertEvents

• createHTTP - CreateHTTP Alert Events V2

alertRoutes

• create - Create Alert Routes V2
• delete - Destroy Alert Routes V2
• show - Show Alert Routes V2
• update - Update Alert Routes V2

catalogEntries

• list - ListEntries Catalog V2
• create - CreateEntry Catalog V2
• delete - DestroyEntry Catalog V2
• show - ShowEntry Catalog V2
• update - UpdateEntry Catalog V2

catalogResources

• list - ListResources Catalog V2

catalogTypes

• list - ListTypes Catalog V2
• create - CreateType Catalog V2
• delete - DestroyType Catalog V2
• show - ShowType Catalog V2
• update - UpdateType Catalog V2
• updateSchema - UpdateTypeSchema Catalog V2

customFieldOptions

• list - List Custom Field Options V1
• create - Create Custom Field Options V1
• delete - Delete Custom Field Options V1
• get - Show Custom Field Options V1
• update - Update Custom Field Options V1

customFields

• create - Create Custom Fields V2
• delete - Delete Custom Fields V2
• get - Show Custom Fields V2
• update - Update Custom Fields V2

customFieldsV2

• list - List Custom Fields V2

escalationPaths

• create - CreatePath Escalations V2
• delete - DestroyPath Escalations V2
• get - ShowPath Escalations V2
• update - UpdatePath Escalations V2

followUps

• list - List Follow-ups V2
• get - Show Follow-ups V2

incidentAttachments

• list - List Incident Attachments V1
• create - Create Incident Attachments V1
• delete - Delete Incident Attachments V1

incidentMemberships

• create - Create Incident Memberships V1
• revoke - Revoke Incident Memberships V1

incidentRoles

• list - List Incident Roles V2
• create - Create Incident Roles V2
• delete - Delete Incident Roles V2
• get - Show Incident Roles V2
• update - Update Incident Roles V2

incidents

• list - List Incidents V2
• create - Create Incidents V2
• get - Show Incidents V2
• update - Edit Incidents V2

incidentStatuses

• list - List Incident Statuses V1
• create - Create Incident Statuses V1
• delete - Delete Incident Statuses V1
• get - Show Incident Statuses V1
• update - Update Incident Statuses V1

incidentsV1

• list - List Incidents V1 :warning: Deprecated
• create - Create Incidents V1 :warning: Deprecated
• get - Show Incidents V1 :warning: Deprecated

incidentTimestamps

• list - List Incident Timestamps V2
• get - Show Incident Timestamps V2

incidentTypes

• list - List Incident Types V1
• get - Show Incident Types V1

incidentUpdates

• list - List Incident Updates V2

scheduleEntries

• list - ListScheduleEntries Schedules V2

schedules

• list - List Schedules V2
• create - Create Schedules V2
• delete - Destroy Schedules V2
• get - Show Schedules V2
• update - Update Schedules V2

severities

• list - List Severities V1
• create - Create Severities V1
• delete - Delete Severities V1
• get - Show Severities V1
• update - Update Severities V1

users

• list - List Users V2
• get - Show Users V2

utilities

• identity - Identity Utilities V1
• getOpenAPI - OpenAPI Utilities V1
• getOpenApiv3 - OpenAPIV3 Utilities V1

workflows

• list - ListWorkflows Workflows V2
• create - CreateWorkflow Workflows V2
• delete - DestroyWorkflow Workflows V2
• get - ShowWorkflow Workflows V2
• update - UpdateWorkflow Workflows V2

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

Available standalone functions

• actionsGet
• actionsList
• actionsV2Get
• actionsV2List
• alertEventsCreateHTTP
• alertRoutesCreate
• alertRoutesDelete
• alertRoutesShow
• alertRoutesUpdate
• catalogEntriesCreate
• catalogEntriesDelete
• catalogEntriesList
• catalogEntriesShow
• catalogEntriesUpdate
• catalogResourcesList
• catalogTypesCreate
• catalogTypesDelete
• catalogTypesList
• catalogTypesShow
• catalogTypesUpdateSchema
• catalogTypesUpdate
• customFieldOptionsCreate
• customFieldOptionsDelete
• customFieldOptionsGet
• customFieldOptionsList
• customFieldOptionsUpdate
• customFieldsCreate
• customFieldsDelete
• customFieldsGet
• customFieldsUpdate
• customFieldsV2List
• escalationPathsCreate
• escalationPathsDelete
• escalationPathsGet
• escalationPathsUpdate
• followUpsGet
• followUpsList
• incidentAttachmentsCreate
• incidentAttachmentsDelete
• incidentAttachmentsList
• incidentMembershipsCreate
• incidentMembershipsRevoke
• incidentRolesCreate
• incidentRolesDelete
• incidentRolesGet
• incidentRolesList
• incidentRolesUpdate
• incidentStatusesCreate
• incidentStatusesDelete
• incidentStatusesGet
• incidentStatusesList
• incidentStatusesUpdate
• incidentTimestampsGet
• incidentTimestampsList
• incidentTypesGet
• incidentTypesList
• incidentUpdatesList
• incidentsCreate
• incidentsGet
• incidentsList
• incidentsUpdate
• incidentsV1Create
• incidentsV1Get
• incidentsV1List
• scheduleEntriesList
• schedulesCreate
• schedulesDelete
• schedulesGet
• schedulesList
• schedulesUpdate
• severitiesCreate
• severitiesDelete
• severitiesGet
• severitiesList
• severitiesUpdate
• usersGet
• usersList
• utilitiesGetOpenAPI
• utilitiesGetOpenApiv3
• utilitiesIdentity
• workflowsCreate
• workflowsDelete
• workflowsGet
• workflowsList
• workflowsUpdate

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

import { Incidentio } from "incidentio";

const incidentio = new Incidentio();

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  }, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  // Handle the result
  console.log(result);
}

run();

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

import { Incidentio } from "incidentio";

const incidentio = new Incidentio({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  });

  // Handle the result
  console.log(result);
}

run();

Error Handling

All SDK methods return a response object or throw an error. If Error objects are specified in your OpenAPI Spec, the SDK will throw the appropriate Error type.

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The SDKValidationError that is thrown as a result will capture the raw value that failed validation in an attribute called rawValue. Additionally, a pretty() method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.

import { Incidentio } from "incidentio";
import { SDKValidationError } from "incidentio/models/errors";

const incidentio = new Incidentio();

async function run() {
  let result;
  try {
    result = await incidentio.actions.list({
      incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
      isFollowUp: true,
      incidentMode: "real",
    });

    // Handle the result
    console.log(result);
  } catch (err) {
    switch (true) {
      case (err instanceof SDKValidationError): {
        // Validation errors can be pretty-printed
        console.error(err.pretty());
        // Raw value may also be inspected
        console.error(err.rawValue);
        return;
      }
      default: {
        throw err;
      }
    }
  }
}

run();

Server Selection

Select Server by Index

You can override the default server globally by passing a server index to the serverIdx optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:

#	Server	Variables
0	https://api.incident.io	None

import { Incidentio } from "incidentio";

const incidentio = new Incidentio({
  serverIdx: 0,
});

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  });

  // Handle the result
  console.log(result);
}

run();

Override Server URL Per-Client

The default server can also be overridden globally by passing a URL to the serverURL optional parameter when initializing the SDK client instance. For example:

import { Incidentio } from "incidentio";

const incidentio = new Incidentio({
  serverURL: "https://api.incident.io",
});

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  });

  // Handle the result
  console.log(result);
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to use the "beforeRequest" hook to to add a custom header and a timeout to requests and how to use the "requestError" hook to log errors:

import { Incidentio } from "incidentio";
import { HTTPClient } from "incidentio/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Incidentio({ httpClient });

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

[!WARNING] Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

import { Incidentio } from "incidentio";

const sdk = new Incidentio({ debugLogger: console });

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy