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,
  • "source_repo_url": "https://github.com/my-company/incident-io-catalog",
  • "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,
  • "source_repo_url": "https://github.com/my-company/incident-io-catalog"
}
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": {
    }
}
➔ Next to Custom Field Options V1