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": {
    }
}