Catalog V2

Manage and browse catalog resources.

This endpoint is in beta, released for early testing but excluded from our backwards compatibility guarantee at this time. Contact support@incident.io if you have questions about availability or want to try this out.

Use the incident.io catalog to track services, teams, product features and anything else that helps build a map of your organisation.

The catalog has a number of types which are synced from your connected integrations, such as GitHub Repositories or PagerDuty Services, but you can also create custom types specifically tailored to your company.

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.

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 <= 500
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 for a type in the catalog.


Request 
Request Body schema: application/json
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 resource


 
 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 resource


 
 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 resource


 
 Example:  01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
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


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.


Request 
Request Body schema: application/json
object
Annotations that can track metadata about this type


 
color
string
Sets the display color of this type in the dashboard


 Enum: "slate" "red" "yellow" "green" "blue" "violet"  
description
required
string
Human readble description of this type


 
icon
string
Sets the display icon of this type in the dashboard


 Enum: "bolt" "box" "briefcase" "browser" "bulb" "clock" "cog" "database" "doc" "email" "server" "severity" "star" "tag" "user" "users"  
name
required
string
Name is the human readable name of this type


 
ranked
boolean
If this type should be ranked


 
semantic_type
string
Semantic type of this resource


 
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": {
    },
  • "color": "slate",
  • "description": "Represents Kubernetes clusters that we run inside of GKE.",
  • "icon": "bolt",
  • "name": "Kubernetes Cluster",
  • "ranked": true,
  • "semantic_type": "custom",
  • "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 resource


 
 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 resource


 
 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.


Request 
path Parameters
id
required
string
ID of this resource


 
 Example:  01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
object
Annotations that can track metadata about this type


 
color
string
Sets the display color of this type in the dashboard


 Enum: "slate" "red" "yellow" "green" "blue" "violet"  
description
required
string
Human readble description of this type


 
icon
string
Sets the display icon of this type in the dashboard


 Enum: "bolt" "box" "briefcase" "browser" "bulb" "clock" "cog" "database" "doc" "email" "server" "severity" "star" "tag" "user" "users"  
name
required
string
Name is the human readable name of this type


 
ranked
boolean
If this type should be ranked


 
semantic_type
string
Semantic type of this resource


 
Responses 
200
OK response.


put/v2/catalog_types/{id}
Request samples 
application/json
{
  • "annotations": {
    },
  • "color": "slate",
  • "description": "Represents Kubernetes clusters that we run inside of GKE.",
  • "icon": "bolt",
  • "name": "Kubernetes Cluster",
  • "ranked": true,
  • "semantic_type": "custom"
}
Response samples 
application/json
{
  • "catalog_type": {
    }
}
UpdateTypeSchema Catalog V2
Update an existing catalog types schema, adding or removing attributes.


Request 
path Parameters
id
required
string
ID of this resource


 
 Example:  01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
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