Catalog V2

Manage and browse catalog resources.

Use the incident.io catalog to track services, teams, product features and anything else that helps build a map of your organisation. These different categories of thing become catalog types, and each instance (like a particular service or team) is a catalog entry.

Each type is made up of a series of attributes, and each attribute has a type. Types can even have attributes that refer to other catalog types.

We automatically create catalog types when you connect an integration, such as GitHub repositories or PagerDuty services and teams. You can use this API to create custom types, that are specifically tailored to your organisation.

Examples might be a 'Service' type with an 'Alert channel' which you can point at a Slack channel, or 'Team' which specifies its 'Manager' and 'Technical Lead' as Slack users. You can then use these types to create powerful new workflows.

Consider using our official catalog importer. It can be used to sync catalog data from sources like local files or GitHub and push them into the incident.io catalog without having to directly interact with our public API.

ListEntries Catalog V2

List entries for a catalog type.

Request
query Parameters
catalog_type_id
required
string

ID of this catalog type

Example: catalog_type_id=01FCNDV6P870EA6S7TK1DSYDG0
page_size
integer <int64> <= 250
Default: 25

Integer number of records to return

Example: page_size=25
after
string

An record's ID. This endpoint will return a list of records after this ID in relation to the API response order.

Example: after=01FDAG4SAP5TYPT98WGR2N7W91
Responses
200

OK response.

get/v2/catalog_entries
Request samples
Response samples
application/json
{
  • "catalog_entries": [
    ],
  • "catalog_type": {
    },
  • "pagination_meta": {
    }
}

CreateEntry Catalog V2

Create an entry within the catalog. We support a maximum of 50,000 entries per type.

If you call this API with a payload where the external_id and catalog_type_id match an existing entry, the existing entry will be updated.

Request
Request Body schema: application/json
required
aliases
Array of strings

Optional aliases that can be used to reference this entry

required
object

Values of this entry

catalog_type_id
required
string

ID of this catalog type

external_id
string

An optional alternative ID for this entry, which is ensured to be unique for the type

name
required
string

Name is the human readable name of this entry

rank
integer <int32>

When catalog type is ranked, this is used to help order things

Responses
201

Created response.

post/v2/catalog_entries
Request samples
application/json
{
  • "aliases": [
    ],
  • "attribute_values": {
    },
  • "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0",
  • "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33",
  • "name": "Primary On-call",
  • "rank": 3
}
Response samples
application/json
{
  • "catalog_entry": {
    }
}

DestroyEntry Catalog V2

Archives a catalog entry.

Request
path Parameters
id
required
string

ID of this catalog entry

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
204

No Content response.

delete/v2/catalog_entries/{id}
Request samples

ShowEntry Catalog V2

Show a single catalog entry.

Request
path Parameters
id
required
string

ID of this catalog entry

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
200

OK response.

get/v2/catalog_entries/{id}
Request samples
Response samples
application/json
{
  • "catalog_entry": {
    },
  • "catalog_type": {
    }
}

UpdateEntry Catalog V2

Updates an existing catalog entry.

Request
path Parameters
id
required
string

ID of this catalog entry

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
required
aliases
Array of strings

Optional aliases that can be used to reference this entry

required
object

Values of this entry

external_id
string

An optional alternative ID for this entry, which is ensured to be unique for the type

name
required
string

Name is the human readable name of this entry

rank
integer <int32>

When catalog type is ranked, this is used to help order things

Responses
200

OK response.

put/v2/catalog_entries/{id}
Request samples
application/json
{
  • "aliases": [
    ],
  • "attribute_values": {
    },
  • "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33",
  • "name": "Primary On-call",
  • "rank": 3
}
Response samples
application/json
{
  • "catalog_entry": {
    },
  • "catalog_type": {
    }
}

ListResources Catalog V2

List available engine resources for the catalog.

A resource represents a type of data that can be held within the catalog, so this endpoint can be used to see what attribute types can be used when updating the schema of a catalog type.

Responses
200

OK response.

get/v2/catalog_resources
Request samples
Response samples
application/json
{
  • "resources": [
    ]
}

ListTypes Catalog V2

List all catalog types for an organisation, including those synced from external resources.

Responses
200

OK response.

get/v2/catalog_types
Request samples
Response samples
application/json
{
  • "catalog_types": [
    ]
}

CreateType Catalog V2

Create a catalog type. The schema must be updated using the UpdateTypeSchema endpoint.

Request
Request Body schema: application/json
required
object

Annotations that can track metadata about this type

categories
Array of strings

What categories is this type considered part of

Items Enum: "customer" "issue-tracker" "product-feature" "service" "on-call" "team" "user"
color
string

Sets the display color of this type in the dashboard

Enum: "yellow" "green" "blue" "violet" "pink" "cyan" "orange"
description
required
string

Human readble description of this type

icon
string

Sets the display icon of this type in the dashboard

Enum: "alert" "bolt" "box" "briefcase" "browser" "bulb" "calendar" "clock" "cog" "components" "database" "doc" "email" "escalation-path" "files" "flag" "folder" "globe" "money" "server" "severity" "status-page" "store" "star" "tag" "user" "users"
name
required
string

Name is the human readable name of this type

ranked
boolean

If this type should be ranked

source_repo_url
string

The url of the external repository where this type is managed

type_name
string

The type name of this catalog type, to be used when defining attributes. This is immutable once a CatalogType has been created. For non-externally sync types, it must follow the pattern Custom["SomeName "]

Responses
201

Created response.

post/v2/catalog_types
Request samples
application/json
{
  • "annotations": {
    },
  • "categories": [
    ],
  • "color": "yellow",
  • "description": "Represents Kubernetes clusters that we run inside of GKE.",
  • "icon": "alert",
  • "name": "Kubernetes Cluster",
  • "ranked": true,
  • "type_name": "Custom[\"BackstageGroup\"]"
}
Response samples
application/json
{
  • "catalog_type": {
    }
}

DestroyType Catalog V2

Archives a catalog type and associated entries.

Request
path Parameters
id
required
string

ID of this catalog type

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
204

No Content response.

delete/v2/catalog_types/{id}
Request samples

ShowType Catalog V2

Show a single catalog type.

Request
path Parameters
id
required
string

ID of this catalog type

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
200

OK response.

get/v2/catalog_types/{id}
Request samples
Response samples
application/json
{
  • "catalog_type": {
    }
}

UpdateType Catalog V2

Updates an existing catalog type. The schema must be updated using the UpdateTypeSchema endpoint.

Request
path Parameters
id
required
string

ID of this catalog type

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
required
object

Annotations that can track metadata about this type

categories
Array of strings

What categories is this type considered part of

Items Enum: "customer" "issue-tracker" "product-feature" "service" "on-call" "team" "user"
color
string

Sets the display color of this type in the dashboard

Enum: "yellow" "green" "blue" "violet" "pink" "cyan" "orange"
description
required
string

Human readble description of this type

icon
string

Sets the display icon of this type in the dashboard

Enum: "alert" "bolt" "box" "briefcase" "browser" "bulb" "calendar" "clock" "cog" "components" "database" "doc" "email" "escalation-path" "files" "flag" "folder" "globe" "money" "server" "severity" "status-page" "store" "star" "tag" "user" "users"
name
required
string

Name is the human readable name of this type

ranked
boolean

If this type should be ranked

source_repo_url
string

The url of the external repository where this type is managed

Responses
200

OK response.

put/v2/catalog_types/{id}
Request samples
application/json
{
  • "annotations": {
    },
  • "categories": [
    ],
  • "color": "yellow",
  • "description": "Represents Kubernetes clusters that we run inside of GKE.",
  • "icon": "alert",
  • "name": "Kubernetes Cluster",
  • "ranked": true,
}
Response samples
application/json
{
  • "catalog_type": {
    }
}

UpdateTypeSchema Catalog V2

Update an existing catalog types schema, adding or removing attributes.

Updating the schema is handled separately from creating and updating types, so that you don't have to worry about dependencies between types. For example, if type A has an attribute that relies on type B, you would have to create type B first.

By allowing the creation of types without a schema, they can be created in any order, but it means that you need to make a separate call to this endpoint to update the schema.

Request
path Parameters
id
required
string

ID of this catalog type

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
required
required
Array of objects (CatalogTypeAttributePayloadV2)
version
required
integer <int64>
Responses
200

OK response.

post/v2/catalog_types/{id}/actions/update_schema
Request samples
application/json
{
  • "attributes": [
    ],
  • "version": 1
}
Response samples
application/json
{
  • "catalog_type": {
    }
}