{ "openapi": "3.0.3", "info": { "description": "This is the API reference for incident.io.\n\nIt documents available API endpoints, provides examples of how to use it, and\ninstructions around things like authentication and error handling.\n\nThe API is hosted at:\n\n- https://api.incident.io/\n\nAnd you will need to create an API key via your [incident.io\ndashboard](https://app.incident.io/settings/api-keys) to make requests.\n\n# Making requests\n\nHere are the key concepts required to make requests to the incident.io API.\n\n## Authentication\n\nFor all requests made to the incident.io API, you'll need an API key.\n\nTo create an API key, head to the incident dashboard and visit [API\nkeys](https://app.incident.io/settings/api-keys). When you create the key, you'll be able to choose what actions it\ncan take for your account: choose carefully, as those roles can only be set\nwhen you first create the key. We'll only show you the token once, so make sure\nyou store it somewhere safe.\n\nAPI keys are global to your incident.io account, and can be managed by anyone\nwho has the right permissions. We display the user that created the API key,\nand the API key will remain valid if that user becomes deactivated.\n\nOnce you have the key, you should make requests to the API that set the\n`Authorization` request header using a \"Bearer\" authentication scheme:\n\n```\nAuthorization: Bearer \n```\n\n## Rate Limits\n\nThe incident.io API enforces rate limits to ensure consistent performance for all users.\n\nThe default rate limit is 1200 requests/minute per API key. This limit applies to most endpoints across the API.\n\nLimits are token buckets that refill continuously rather than resetting on a fixed window boundary. The default\nbucket holds 1200 requests and refills at 20 per second, so you can burst up to the full bucket and then sustain\n20 requests/second indefinitely. There is no boundary at which your quota resets to full in one step.\n\nSome endpoints have lower rate limits, particularly those that interact with external third-party systems that impose\ntheir own limitations. These specific limits vary by endpoint.\n\n### Rate limit headers\n\nResponses to requests authenticated with an API key carry your current allowance, so you can pace yourself rather\nthan waiting to be throttled:\n\n```\nX-RateLimit-Limit: 60, 1200;window=60, 60;window=60\nX-RateLimit-Remaining: 59\nX-RateLimit-Used: 1\nX-RateLimit-Reset: 1785173199\n```\n\n| Header | Meaning |\n| --- | --- |\n| `X-RateLimit-Limit` | The quota that binds this request, followed by every limit that applied and the window it applies over |\n| `X-RateLimit-Remaining` | Requests you can make right now against the binding limit |\n| `X-RateLimit-Used` | Requests you have spent against it |\n| `X-RateLimit-Reset` | Unix timestamp (seconds) at which that limit will be back to full |\n\nMore than one limit can apply to a request: your API key's overall limit, and for some endpoints a lower limit of\ntheir own. `X-RateLimit-Limit` lists all of them, each with its window, so `1200;window=60` means 1200 requests per\nminute. Because our limits refill continuously rather than resetting on a boundary, that window is what tells you\nthe rate you can sustain: 1200 per 60 seconds is 20 requests/second indefinitely.\n\n`Remaining`, `Used` and `Reset` describe whichever limit has the least allowance left, since that is the one you\nwill hit first.\n\n`X-RateLimit-Remaining` may lag by a small number of requests under high concurrency, and can move by more than the\nrequests you made, because limits scoped to your whole organisation are shared with your other API keys.\n\nHeaders are omitted rather than guessed if we cannot determine your allowance for a request.\n\n### Exceeding a rate limit\n\nWhen you exceed a rate limit the API responds with `429 Too Many Requests` and a `Retry-After` header giving the\nnumber of seconds to wait:\n\n```\nX-RateLimit-Limit: 1200, 1200;window=60\nX-RateLimit-Remaining: 0\nX-RateLimit-Used: 1200\nX-RateLimit-Reset: 1785173199\nRetry-After: 1\n```\n\nPrefer `Retry-After` over `X-RateLimit-Reset` when deciding how long to back off. `Retry-After` is when a single\nrequest will succeed; `X-RateLimit-Reset` is the later point at which your whole allowance has returned. It is a\nduration rather than a timestamp, so it does not depend on your clock agreeing with ours.\n\nThe 429 also carries a JSON body with the same information:\n\n```json\n{\n \"type\": \"too_many_requests\",\n \"status\": 429,\n \"request_id\": \"b839a403-7704-41c1-bf6a-39a2d68caefa\",\n \"rate_limit\": {\n \"name\": \"api_key_name\",\n \"limit\": 1200,\n \"remaining\": 0,\n \"retry_after\": \"2025-04-17T11:17:18Z\"\n },\n \"errors\": [\n {\n \"code\": \"too_many_requests\",\n \"message\": \"Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.\"\n }\n ]\n}\n```\n\nThe response includes:\n* The name of the API key (`name`)\n* The bucket limit (`limit`)\n* The number of requests remaining (`remaining`)\n* When you can retry requests (`retry_after`), as an RFC3339 timestamp\n\n## Errors\n\nWe use standard HTTP response codes to indicate the status or failure of API\nrequests.\n\nThe API response body will be JSON, and contain more detailed information on the\nnature of the error.\n\nAn example error when a request is made without an API key:\n\n```json\n{\n \"type\": \"authentication_error\",\n \"status\": 401,\n \"request_id\": \"8e3cc412-b49d-4957-9073-2c19d2c61804\",\n \"errors\": [\n {\n \"code\": \"missing_authorization_material\",\n \"message\": \"No authorization material provided in request\"\n }\n ]\n}\n```\n\nNote that the error:\n\n- Contains the HTTP status (`401`)\n- References the type of error (`authentication_error`)\n- Includes a `request_id` that can be provided to incident.io support to help\n\tdebug questions with your API request\n- Provides a list of individual errors, which go into detail about why the error\n\toccurred\n\nThe most common error will be a 422 Validation Error, which is returned when the\nrequest was rejected due to failing validations.\n\nThese errors look like this:\n\n```json\n{\n \"type\": \"validation_error\",\n \"status\": 422,\n \"request_id\": \"631766c4-4afd-4803-997c-cd700928fa4b\",\n \"errors\": [\n {\n \"code\": \"is_required\",\n \"message\": \"A severity is required to open an incident\",\n \"source\": {\n \"field\": \"severity_id\"\n }\n }\n ]\n}\n```\n\nThis error is caused by not providing a severity identifier, which should be at\nthe `severity_id` field of the request payload. Errors like these can be mapped to\nforms, should you be integrating with the API from a user-interface.\n\n## Compatibility\n\nWe won't make breaking changes to existing API services or endpoints, but will\nexpect integrators to upgrade themselves to the latest API endpoints within 3\nmonths of us deprecating the old service.\n\nWe will make changes that are considered backwards compatible, which include:\n\n- Adding new API endpoints and services\n- Adding new properties to responses from existing API endpoints\n- Reordering properties returned from existing API endpoints\n- Adding optional request parameters to existing API endpoints\n- Altering the format or length of IDs\n- Adding new values to enums\n\nIt is important that clients are robust to these changes, to ensure reliable\nintegrations.\n\nAs an example, if you are generating a client using an openapi-generator, ensure\nthe generated client is configured to support unknown enum values, often\nconfigured via the `enumUnknownDefaultCase` parameter.\n\nWhen breaking changes are unavoidable, we'll create a new service version on a\nseparate path, and run them in parallel.\n\nFor example:\n\n- https://api.incident.io/v1/incidents\n- https://api.incident.io/v2/incidents\n\nFor any questions, email support@incident.io.\n", "title": "incident.io", "version": "1.0.0" }, "servers": [ { "url": "https://api.incident.io" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "description": "Manage and browse catalog resources.\n\nUse the incident.io catalog to track services, teams, product features and anything\nelse that helps build a map of your organisation. These different categories of thing\nbecome catalog types, and each instance (like a particular service or team) is a\ncatalog entry.\n\nEach type is made up of a series of attributes, and each attribute has a type. Types\ncan even have attributes that refer to other catalog types.\n\nWe automatically create catalog types when you connect an integration, such as GitHub\nrepositories or PagerDuty services and teams. You can use this API to create custom\ntypes, that are specifically tailored to your organisation.\n\nExamples might be a 'Service' type with an 'Alert channel' which you can point at a\nSlack channel, or 'Team' which specifies its 'Manager' and 'Technical Lead' as Slack\nusers. You can then use these types to create powerful new workflows.\n\nConsider using our official [catalog importer](https://github.com/incident-io/catalog-importer).\nIt can be used to sync catalog data from sources like local files or GitHub and push\nthem into the incident.io catalog without having to directly interact with our public API.\n", "name": "Catalog Entries V3" } ], "paths": { "/v3/catalog_entries": { "get": { "description": "List entries for a catalog type.", "operationId": "Catalog V3_ListEntries", "parameters": [ { "allowEmptyValue": true, "description": "ID of this catalog type", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "in": "query", "name": "catalog_type_id", "required": true, "schema": { "description": "ID of this catalog type", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" } }, { "allowEmptyValue": true, "description": "The integer number of records to return", "examples": { "default": { "summary": "default", "value": 25 } }, "in": "query", "name": "page_size", "required": true, "schema": { "default": 25, "description": "The integer number of records to return", "example": 25, "format": "int64", "maximum": 250, "minimum": 1, "type": "integer" } }, { "allowEmptyValue": true, "description": "An record's ID. This endpoint will return a list of records after this ID in relation to the API response order.", "examples": { "default": { "summary": "default", "value": "01FDAG4SAP5TYPT98WGR2N7W91" } }, "in": "query", "name": "after", "schema": { "description": "An record's ID. This endpoint will return a list of records after this ID in relation to the API response order.", "example": "01FDAG4SAP5TYPT98WGR2N7W91", "type": "string" } }, { "allowEmptyValue": true, "description": "If specified, only entries with this identifier will be returned. This will search by ID, external ID, and aliases.\n\nIf 'use name as identifier' is enabled for the catalog type, this will also match on name.", "example": "abc123", "in": "query", "name": "identifier", "schema": { "description": "If specified, only entries with this identifier will be returned. This will search by ID, external ID, and aliases.\n\nIf 'use name as identifier' is enabled for the catalog type, this will also match on name.", "example": "abc123", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "catalog_entries": [ { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" } ], "catalog_type": { "annotations": { "incident.io/catalog-importer/id": "id-of-config" }, "categories": [ "customer" ], "color": "yellow", "created_at": "2021-08-17T13:28:57.801578Z", "description": "Represents Kubernetes clusters that we run inside of GKE.", "dynamic_resource_parameter": "abc123", "engine_resource_type": "CatalogEntry[\"PagerDutyService\"]", "estimated_count": 7, "icon": "alert", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "is_editable": false, "is_team_type": false, "last_synced_at": "2021-08-17T13:28:57.801578Z", "name": "Kubernetes Cluster", "owning_team_ids": [ "01G0J1EXE7AXZ2C93K61WBPYEH" ], "ranked": true, "registry_type": "PagerDutyService", "required_integrations": [ "pager_duty" ], "schema": { "attributes": [ { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" } ], "version": 1 }, "source_repo_url": "https://github.com/my-company/incident-io-catalog", "supports_custom_aliases": true, "type_name": "Custom[\"BackstageGroup\"]", "updated_at": "2021-08-17T13:28:57.801578Z", "use_name_as_identifier": true }, "pagination_meta": { "after": "01FCNDV6P870EA6S7TK1DSYDG0", "page_size": 25, "total_record_count": 238 } }, "schema": { "$ref": "#/components/schemas/CatalogListEntriesResultV3" } } }, "description": "OK response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn't exist." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "authentication_error: Authentication failed." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "resource_forbidden: Access to this resource is forbidden for the authenticated user." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_found: The referenced resource could not be found." }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "method_not_allowed: The endpoint does not support this operation for the specified resource." }, "406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_acceptable: Requested a media type this endpoint does not support." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "request_timeout: The request took too long to process.\n\nclient_timeout: The request was cancelled by the client." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "conflict: Request conflicted with current state of the resource, likely a concurrent update." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "precondition_failed: A required condition hasn't been met." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "payload_too_large: The request payload is too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "validation_error: A required field was not provided, or the provided data was invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.\n\nrate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "api_error: Something went wrong and has been reported internally." } }, "summary": "List Entries", "tags": [ "Catalog Entries V3" ], "x-docs-display-name": "List Entries", "x-docs-group-name": "Catalog Entries V3", "x-docs-resource-type": "CatalogEntryV3", "x-mint": { "content": "🔑 Requires the `catalog_entries.view` scope." }, "x-rbac-scopes": [ "catalog_entries.view" ] }, "post": { "description": "Create an entry within the catalog. We support a maximum of 50,000 entries per type.\n\nIf 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.", "operationId": "Catalog V3_CreateEntry", "requestBody": { "content": { "application/json": { "example": { "aliases": [ "lawrence@incident.io", "lawrence" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "name": "Primary On-call", "rank": 3 }, "schema": { "$ref": "#/components/schemas/CatalogCreateEntryPayloadV3" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "catalog_entry": { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" } }, "schema": { "$ref": "#/components/schemas/CatalogCreateEntryResultV3" } } }, "description": "Created response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn't exist." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "authentication_error: Authentication failed." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "resource_forbidden: Access to this resource is forbidden for the authenticated user." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_found: The referenced resource could not be found." }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "method_not_allowed: The endpoint does not support this operation for the specified resource." }, "406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_acceptable: Requested a media type this endpoint does not support." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "request_timeout: The request took too long to process.\n\nclient_timeout: The request was cancelled by the client." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "conflict: Request conflicted with current state of the resource, likely a concurrent update." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "precondition_failed: A required condition hasn't been met." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "payload_too_large: The request payload is too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "validation_error: A required field was not provided, or the provided data was invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.\n\nrate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "api_error: Something went wrong and has been reported internally." } }, "summary": "Create Entry", "tags": [ "Catalog Entries V3" ], "x-docs-display-name": "Create Entry", "x-docs-group-name": "Catalog Entries V3", "x-docs-resource-type": "CatalogEntryV3", "x-mint": { "content": "🔑 Requires the `catalog_entries.create` scope." }, "x-rbac-scopes": [ "catalog_entries.create" ] } }, "/v3/catalog_entries/{id}": { "delete": { "description": "Archives a catalog entry.", "operationId": "Catalog V3_DestroyEntry", "parameters": [ { "description": "ID of this catalog entry", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "in": "path", "name": "id", "required": true, "schema": { "description": "ID of this catalog entry", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" } } ], "responses": { "204": { "description": "No Content response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn't exist." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "authentication_error: Authentication failed." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "resource_forbidden: Access to this resource is forbidden for the authenticated user." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_found: The referenced resource could not be found." }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "method_not_allowed: The endpoint does not support this operation for the specified resource." }, "406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_acceptable: Requested a media type this endpoint does not support." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "request_timeout: The request took too long to process.\n\nclient_timeout: The request was cancelled by the client." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "conflict: Request conflicted with current state of the resource, likely a concurrent update." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "precondition_failed: A required condition hasn't been met." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "payload_too_large: The request payload is too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "validation_error: A required field was not provided, or the provided data was invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.\n\nrate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "api_error: Something went wrong and has been reported internally." } }, "summary": "Delete Entry", "tags": [ "Catalog Entries V3" ], "x-docs-display-name": "Delete Entry", "x-docs-group-name": "Catalog Entries V3", "x-docs-resource-type": "CatalogEntryV3", "x-mint": { "content": "🔑 Requires the `catalog_entries.destroy` scope." }, "x-rbac-scopes": [ "catalog_entries.destroy" ] }, "get": { "description": "Show a single catalog entry.", "operationId": "Catalog V3_ShowEntry", "parameters": [ { "allowEmptyValue": true, "description": "Whether to include details of all attribute links (forwards and backwards) within the response. Default behaviour (no query param) is to include only forward links. When expand is false, we only show attributes of the catalog entry itself.When expand is true, we show forward and backward links", "example": true, "in": "query", "name": "expand", "schema": { "description": "Whether to include details of all attribute links (forwards and backwards) within the response. Default behaviour (no query param) is to include only forward links. When expand is false, we only show attributes of the catalog entry itself.When expand is true, we show forward and backward links", "example": true, "type": "boolean" } }, { "description": "ID of this catalog entry", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "in": "path", "name": "id", "required": true, "schema": { "description": "ID of this catalog entry", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "catalog_entry": { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" }, "catalog_type": { "annotations": { "incident.io/catalog-importer/id": "id-of-config" }, "categories": [ "customer" ], "color": "yellow", "created_at": "2021-08-17T13:28:57.801578Z", "description": "Represents Kubernetes clusters that we run inside of GKE.", "dynamic_resource_parameter": "abc123", "engine_resource_type": "CatalogEntry[\"PagerDutyService\"]", "estimated_count": 7, "icon": "alert", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "is_editable": false, "is_team_type": false, "last_synced_at": "2021-08-17T13:28:57.801578Z", "name": "Kubernetes Cluster", "owning_team_ids": [ "01G0J1EXE7AXZ2C93K61WBPYEH" ], "ranked": true, "registry_type": "PagerDutyService", "required_integrations": [ "pager_duty" ], "schema": { "attributes": [ { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" } ], "version": 1 }, "source_repo_url": "https://github.com/my-company/incident-io-catalog", "supports_custom_aliases": true, "type_name": "Custom[\"BackstageGroup\"]", "updated_at": "2021-08-17T13:28:57.801578Z", "use_name_as_identifier": true } }, "schema": { "$ref": "#/components/schemas/CatalogShowEntryResultV3" } } }, "description": "OK response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn't exist." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "authentication_error: Authentication failed." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "resource_forbidden: Access to this resource is forbidden for the authenticated user." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_found: The referenced resource could not be found." }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "method_not_allowed: The endpoint does not support this operation for the specified resource." }, "406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_acceptable: Requested a media type this endpoint does not support." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "request_timeout: The request took too long to process.\n\nclient_timeout: The request was cancelled by the client." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "conflict: Request conflicted with current state of the resource, likely a concurrent update." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "precondition_failed: A required condition hasn't been met." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "payload_too_large: The request payload is too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "validation_error: A required field was not provided, or the provided data was invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.\n\nrate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "api_error: Something went wrong and has been reported internally." } }, "summary": "Show Entry", "tags": [ "Catalog Entries V3" ], "x-docs-display-name": "Show Entry", "x-docs-group-name": "Catalog Entries V3", "x-docs-resource-type": "CatalogEntryV3", "x-mint": { "content": "🔑 Requires the `catalog_entries.view` scope." }, "x-rbac-scopes": [ "catalog_entries.view" ] }, "put": { "description": "Updates an existing catalog entry.", "operationId": "Catalog V3_UpdateEntry", "parameters": [ { "description": "ID of this catalog entry", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "in": "path", "name": "id", "required": true, "schema": { "description": "ID of this catalog entry", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "aliases": [ "lawrence@incident.io", "lawrence" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "name": "Primary On-call", "rank": 3, "update_attributes": [ "abc123" ] }, "schema": { "$ref": "#/components/schemas/CatalogUpdateEntryPayloadV3" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "catalog_entry": { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" }, "catalog_type": { "annotations": { "incident.io/catalog-importer/id": "id-of-config" }, "categories": [ "customer" ], "color": "yellow", "created_at": "2021-08-17T13:28:57.801578Z", "description": "Represents Kubernetes clusters that we run inside of GKE.", "dynamic_resource_parameter": "abc123", "engine_resource_type": "CatalogEntry[\"PagerDutyService\"]", "estimated_count": 7, "icon": "alert", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "is_editable": false, "is_team_type": false, "last_synced_at": "2021-08-17T13:28:57.801578Z", "name": "Kubernetes Cluster", "owning_team_ids": [ "01G0J1EXE7AXZ2C93K61WBPYEH" ], "ranked": true, "registry_type": "PagerDutyService", "required_integrations": [ "pager_duty" ], "schema": { "attributes": [ { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" } ], "version": 1 }, "source_repo_url": "https://github.com/my-company/incident-io-catalog", "supports_custom_aliases": true, "type_name": "Custom[\"BackstageGroup\"]", "updated_at": "2021-08-17T13:28:57.801578Z", "use_name_as_identifier": true } }, "schema": { "$ref": "#/components/schemas/CatalogUpdateEntryResultV3" } } }, "description": "OK response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn't exist." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "authentication_error: Authentication failed." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "resource_forbidden: Access to this resource is forbidden for the authenticated user." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_found: The referenced resource could not be found." }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "method_not_allowed: The endpoint does not support this operation for the specified resource." }, "406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_acceptable: Requested a media type this endpoint does not support." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "request_timeout: The request took too long to process.\n\nclient_timeout: The request was cancelled by the client." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "conflict: Request conflicted with current state of the resource, likely a concurrent update." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "precondition_failed: A required condition hasn't been met." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "payload_too_large: The request payload is too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "validation_error: A required field was not provided, or the provided data was invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.\n\nrate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "api_error: Something went wrong and has been reported internally." } }, "summary": "Update Entry", "tags": [ "Catalog Entries V3" ], "x-docs-display-name": "Update Entry", "x-docs-group-name": "Catalog Entries V3", "x-docs-resource-type": "CatalogEntryV3", "x-mint": { "content": "🔑 Requires the `catalog_entries.edit` scope." }, "x-rbac-scopes": [ "catalog_entries.edit" ] } }, "/v3/catalog_entries/actions/bulk_update": { "post": { "description": "Update multiple catalog entries in a single operation. You can update up to 250 entries at once. This operation is atomic - either all entries are updated successfully, or none are updated.", "operationId": "Catalog V3_BulkUpdateEntries", "requestBody": { "content": { "application/json": { "example": { "catalog_type_id": "01GW2G3V0S59R238FAHPDS1R66", "entries": [ { "aliases": [ "abc123" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "entry_id": "abc123", "external_id": "abc123", "name": "abc123", "rank": 1 }, { "aliases": [ "abc123" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "entry_id": "abc123", "external_id": "abc123", "name": "abc123", "rank": 1 } ], "update_attributes": [ "01GW2G3V0S59R238FAHPDS1R66", "01GW2G3V0S59R238FAHPDS1R67" ] }, "schema": { "$ref": "#/components/schemas/CatalogBulkUpdateEntriesPayloadV3" } } }, "required": true }, "responses": { "204": { "description": "No Content response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn't exist." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "authentication_error: Authentication failed." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "resource_forbidden: Access to this resource is forbidden for the authenticated user." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_found: The referenced resource could not be found." }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "method_not_allowed: The endpoint does not support this operation for the specified resource." }, "406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "not_acceptable: Requested a media type this endpoint does not support." }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "request_timeout: The request took too long to process.\n\nclient_timeout: The request was cancelled by the client." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "conflict: Request conflicted with current state of the resource, likely a concurrent update." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "precondition_failed: A required condition hasn't been met." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "payload_too_large: The request payload is too large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "validation_error: A required field was not provided, or the provided data was invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.\n\nrate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "api_error: Something went wrong and has been reported internally." } }, "summary": "Bulk Update Entries", "tags": [ "Catalog Entries V3" ], "x-docs-display-name": "Bulk Update Entries", "x-docs-group-name": "Catalog Entries V3", "x-docs-resource-type": "CatalogEntryV3", "x-mint": { "content": "🔑 Requires the `catalog_entries.edit` scope." }, "x-rbac-scopes": [ "catalog_entries.edit" ] } } }, "components": { "schemas": { "CatalogListEntriesResultV3": { "example": { "catalog_entries": [ { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" } ], "catalog_type": { "annotations": { "incident.io/catalog-importer/id": "id-of-config" }, "categories": [ "customer" ], "color": "yellow", "created_at": "2021-08-17T13:28:57.801578Z", "description": "Represents Kubernetes clusters that we run inside of GKE.", "dynamic_resource_parameter": "abc123", "engine_resource_type": "CatalogEntry[\"PagerDutyService\"]", "estimated_count": 7, "icon": "alert", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "is_editable": false, "is_team_type": false, "last_synced_at": "2021-08-17T13:28:57.801578Z", "name": "Kubernetes Cluster", "owning_team_ids": [ "01G0J1EXE7AXZ2C93K61WBPYEH" ], "ranked": true, "registry_type": "PagerDutyService", "required_integrations": [ "pager_duty" ], "schema": { "attributes": [ { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" } ], "version": 1 }, "source_repo_url": "https://github.com/my-company/incident-io-catalog", "supports_custom_aliases": true, "type_name": "Custom[\"BackstageGroup\"]", "updated_at": "2021-08-17T13:28:57.801578Z", "use_name_as_identifier": true }, "pagination_meta": { "after": "01FCNDV6P870EA6S7TK1DSYDG0", "page_size": 25, "total_record_count": 238 } }, "properties": { "catalog_entries": { "example": [ { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" } ], "items": { "$ref": "#/components/schemas/CatalogEntryV3" }, "type": "array" }, "catalog_type": { "$ref": "#/components/schemas/CatalogTypeV3" }, "pagination_meta": { "$ref": "#/components/schemas/PaginationMetaResultWithTotalV3" } }, "required": [ "catalog_type", "catalog_entries", "pagination_meta" ], "type": "object" }, "ErrorResponse": { "example": { "debug": { "message": "Something broke: and something else: and something else", "stacktrace": [ "thing.go:123" ] }, "errors": [ { "code": "trial_expired", "message": "Default incident call link must be a valid URL", "metadata": { "abc123": "abc123" }, "source": { "field": "default_call_url", "pointer": "/settings/default_call_url" } } ], "rate_limit": { "limit": 100, "name": "client_ip", "remaining": 98, "retry_after": "2020-01-01T00:00:00Z" }, "request_id": "2T1p0e3j", "status": 408, "type": "invalid_request_error" }, "properties": { "debug": { "$ref": "#/components/schemas/ErrorDebug" }, "errors": { "description": "List of errors that caused this request to fail", "example": [ { "code": "trial_expired", "message": "Default incident call link must be a valid URL", "metadata": { "abc123": "abc123" }, "source": { "field": "default_call_url", "pointer": "/settings/default_call_url" } } ], "items": { "$ref": "#/components/schemas/ErrorSingle" }, "type": "array" }, "rate_limit": { "$ref": "#/components/schemas/ErrorRateLimit" }, "request_id": { "description": "Unique identifier of the request", "example": "2T1p0e3j", "type": "string" }, "status": { "description": "HTTP status of the response", "example": 408, "format": "int64", "type": "integer" }, "type": { "description": "Machine-readable identifier for the general category of error", "enum": [ "invalid_request_error", "authentication_error", "resource_forbidden", "not_found", "not_acceptable", "method_not_allowed", "request_timeout", "conflict", "precondition_failed", "payload_too_large", "validation_error", "too_many_requests", "api_error", "rate_limit_reached", "client_timeout" ], "example": "invalid_request_error", "type": "string" } }, "required": [ "type", "status", "request_id", "errors" ], "type": "object" }, "CatalogCreateEntryPayloadV3": { "example": { "aliases": [ "lawrence@incident.io", "lawrence" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "name": "Primary On-call", "rank": 3 }, "properties": { "aliases": { "description": "Optional aliases that can be used to reference this entry", "example": [ "lawrence@incident.io", "lawrence" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "attribute_values": { "additionalProperties": { "$ref": "#/components/schemas/CatalogEngineParamBindingPayloadV3" }, "description": "Values of this entry", "example": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "type": "object" }, "catalog_type_id": { "description": "ID of this catalog type", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" }, "external_id": { "description": "An optional alternative ID for this entry, which is ensured to be unique for the type", "example": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "type": "string" }, "name": { "description": "Name is the human readable name of this entry", "example": "Primary On-call", "type": "string" }, "rank": { "description": "When catalog type is ranked, this is used to help order things", "example": 3, "format": "int32", "type": "integer" } }, "required": [ "catalog_type_id", "name", "attribute_values" ], "type": "object" }, "CatalogCreateEntryResultV3": { "example": { "catalog_entry": { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" } }, "properties": { "catalog_entry": { "$ref": "#/components/schemas/CatalogEntryV3" } }, "required": [ "catalog_entry" ], "type": "object" }, "CatalogShowEntryResultV3": { "example": { "catalog_entry": { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" }, "catalog_type": { "annotations": { "incident.io/catalog-importer/id": "id-of-config" }, "categories": [ "customer" ], "color": "yellow", "created_at": "2021-08-17T13:28:57.801578Z", "description": "Represents Kubernetes clusters that we run inside of GKE.", "dynamic_resource_parameter": "abc123", "engine_resource_type": "CatalogEntry[\"PagerDutyService\"]", "estimated_count": 7, "icon": "alert", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "is_editable": false, "is_team_type": false, "last_synced_at": "2021-08-17T13:28:57.801578Z", "name": "Kubernetes Cluster", "owning_team_ids": [ "01G0J1EXE7AXZ2C93K61WBPYEH" ], "ranked": true, "registry_type": "PagerDutyService", "required_integrations": [ "pager_duty" ], "schema": { "attributes": [ { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" } ], "version": 1 }, "source_repo_url": "https://github.com/my-company/incident-io-catalog", "supports_custom_aliases": true, "type_name": "Custom[\"BackstageGroup\"]", "updated_at": "2021-08-17T13:28:57.801578Z", "use_name_as_identifier": true } }, "properties": { "catalog_entry": { "$ref": "#/components/schemas/CatalogEntryV3" }, "catalog_type": { "$ref": "#/components/schemas/CatalogTypeV3" } }, "required": [ "catalog_type", "catalog_entry" ], "type": "object" }, "CatalogUpdateEntryPayloadV3": { "example": { "aliases": [ "lawrence@incident.io", "lawrence" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "name": "Primary On-call", "rank": 3, "update_attributes": [ "abc123" ] }, "properties": { "aliases": { "description": "Optional aliases that can be used to reference this entry", "example": [ "lawrence@incident.io", "lawrence" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "attribute_values": { "additionalProperties": { "$ref": "#/components/schemas/CatalogEngineParamBindingPayloadV3" }, "description": "Values of this entry", "example": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "type": "object" }, "custom_aliases": { "description": "Aliases your organisation has added to an entry of a catalog type that incident.io syncs, such as a schedule or escalation path, which you can't change aliases on directly. Syncs keep them, and they are also listed in aliases. When you update an entry, omit this or send null to keep its current custom aliases, send an empty list to clear them, or send a list to replace them.", "example": [ "primary-on-call" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "external_id": { "description": "An optional alternative ID for this entry, which is ensured to be unique for the type", "example": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "type": "string" }, "name": { "description": "Name is the human readable name of this entry", "example": "Primary On-call", "type": "string" }, "rank": { "description": "When catalog type is ranked, this is used to help order things", "example": 3, "format": "int32", "type": "integer" }, "update_attributes": { "description": "If provided, only update these attribute_values keys. If not provided, update all attribute values.\nIf you specify an attribute key that's not in your payload, the associated attribute value will be cleared.", "example": [ "abc123" ], "items": { "example": "abc123", "type": "string" }, "type": "array" } }, "required": [ "name", "attribute_values" ], "type": "object" }, "CatalogUpdateEntryResultV3": { "example": { "catalog_entry": { "aliases": [ "lawrence@incident.io", "lawrence" ], "archived_at": "2021-08-17T14:28:57.801578Z", "attribute_values": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0", "created_at": "2021-08-17T13:28:57.801578Z", "custom_aliases": [ "primary-on-call" ], "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "name": "Primary On-call", "rank": 3, "updated_at": "2021-08-17T13:28:57.801578Z" }, "catalog_type": { "annotations": { "incident.io/catalog-importer/id": "id-of-config" }, "categories": [ "customer" ], "color": "yellow", "created_at": "2021-08-17T13:28:57.801578Z", "description": "Represents Kubernetes clusters that we run inside of GKE.", "dynamic_resource_parameter": "abc123", "engine_resource_type": "CatalogEntry[\"PagerDutyService\"]", "estimated_count": 7, "icon": "alert", "id": "01FCNDV6P870EA6S7TK1DSYDG0", "is_editable": false, "is_team_type": false, "last_synced_at": "2021-08-17T13:28:57.801578Z", "name": "Kubernetes Cluster", "owning_team_ids": [ "01G0J1EXE7AXZ2C93K61WBPYEH" ], "ranked": true, "registry_type": "PagerDutyService", "required_integrations": [ "pager_duty" ], "schema": { "attributes": [ { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" } ], "version": 1 }, "source_repo_url": "https://github.com/my-company/incident-io-catalog", "supports_custom_aliases": true, "type_name": "Custom[\"BackstageGroup\"]", "updated_at": "2021-08-17T13:28:57.801578Z", "use_name_as_identifier": true } }, "properties": { "catalog_entry": { "$ref": "#/components/schemas/CatalogEntryV3" }, "catalog_type": { "$ref": "#/components/schemas/CatalogTypeV3" } }, "required": [ "catalog_type", "catalog_entry" ], "type": "object" }, "CatalogBulkUpdateEntriesPayloadV3": { "example": { "catalog_type_id": "01GW2G3V0S59R238FAHPDS1R66", "entries": [ { "aliases": [ "abc123" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "entry_id": "abc123", "external_id": "abc123", "name": "abc123", "rank": 1 }, { "aliases": [ "abc123" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "entry_id": "abc123", "external_id": "abc123", "name": "abc123", "rank": 1 } ], "update_attributes": [ "01GW2G3V0S59R238FAHPDS1R66", "01GW2G3V0S59R238FAHPDS1R67" ] }, "properties": { "catalog_type_id": { "description": "The unique identifier of the catalog type containing the entries", "example": "01GW2G3V0S59R238FAHPDS1R66", "type": "string" }, "entries": { "description": "A list of entries to update with their new values. Maximum 250 entries per request.", "example": [ { "aliases": [ "abc123" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "entry_id": "abc123", "external_id": "abc123", "name": "abc123", "rank": 1 }, { "aliases": [ "abc123" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "entry_id": "abc123", "external_id": "abc123", "name": "abc123", "rank": 1 } ], "items": { "$ref": "#/components/schemas/PartialEntryPayloadV3" }, "maxItems": 250, "minItems": 1, "type": "array" }, "update_attributes": { "description": "Optional list of specific attribute IDs to update across all entries. When provided, only these attributes in attribute_values will be updated and all other attributes will be preserved. This parameter only affects attribute_values - it does not affect core entry fields like name, rank, aliases, or external_id, which follow their individual omission rules.", "example": [ "01GW2G3V0S59R238FAHPDS1R66", "01GW2G3V0S59R238FAHPDS1R67" ], "items": { "example": "abc123", "type": "string" }, "type": "array" } }, "required": [ "catalog_type_id", "entries" ], "type": "object" }, "CatalogEntryV3": { "properties": { "aliases": { "description": "Optional aliases that can be used to reference this entry", "example": [ "lawrence@incident.io", "lawrence" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "archived_at": { "description": "When this entry was archived", "example": "2021-08-17T14:28:57.801578Z", "format": "date-time", "type": "string" }, "attribute_values": { "additionalProperties": { "$ref": "#/components/schemas/CatalogEntryEngineParamBindingV3" }, "description": "Values of this entry", "example": { "abc123": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } } }, "type": "object" }, "catalog_type_id": { "description": "ID of this catalog type", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" }, "created_at": { "description": "When this entry was created", "example": "2021-08-17T13:28:57.801578Z", "format": "date-time", "type": "string" }, "custom_aliases": { "description": "Aliases your organisation has added to an entry of a catalog type that incident.io syncs, such as a schedule or escalation path, which you can't change aliases on directly. Syncs keep them, and they are also listed in aliases. When you update an entry, omit this or send null to keep its current custom aliases, send an empty list to clear them, or send a list to replace them.", "example": [ "primary-on-call" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "external_id": { "description": "An optional alternative ID for this entry, which is ensured to be unique for the type", "example": "761722cd-d1d7-477b-ac7e-90f9e079dc33", "type": "string" }, "id": { "description": "ID of this catalog entry", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" }, "name": { "description": "Name is the human readable name of this entry", "example": "Primary On-call", "type": "string" }, "rank": { "description": "When catalog type is ranked, this is used to help order things", "example": 3, "format": "int32", "type": "integer" }, "updated_at": { "description": "When this entry was last updated", "example": "2021-08-17T13:28:57.801578Z", "format": "date-time", "type": "string" } }, "required": [ "id", "catalog_type_id", "name", "aliases", "custom_aliases", "rank", "attribute_values", "created_at", "updated_at" ], "type": "object" }, "CatalogTypeV3": { "properties": { "annotations": { "additionalProperties": { "example": "abc123", "type": "string" }, "description": "Annotations that can track metadata about this type", "example": { "incident.io/catalog-importer/id": "id-of-config" }, "type": "object" }, "categories": { "description": "What categories is this type considered part of", "example": [ "customer" ], "items": { "enum": [ "customer", "issue-tracker", "product-feature", "service", "on-call", "team", "user" ], "example": "customer", "type": "string", "x-public-api-version": "v3" }, "type": "array" }, "color": { "description": "Sets the display color of this type in the dashboard", "enum": [ "yellow", "green", "blue", "violet", "pink", "cyan", "orange" ], "example": "yellow", "type": "string" }, "created_at": { "description": "When this type was created", "example": "2021-08-17T13:28:57.801578Z", "format": "date-time", "type": "string" }, "description": { "description": "Human readble description of this type", "example": "Represents Kubernetes clusters that we run inside of GKE.", "type": "string" }, "dynamic_resource_parameter": { "description": "If this is a dynamic catalog type, this will be the unique parameter for identitfying this resource externally.", "example": "abc123", "type": "string" }, "engine_resource_type": { "description": "The way this resource type is referenced in the engine, as used when setting the type of an alert attribute", "example": "CatalogEntry[\"PagerDutyService\"]", "type": "string" }, "estimated_count": { "description": "If populated, gives an estimated count of entries for this type", "example": 7, "format": "int64", "type": "integer" }, "icon": { "description": "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", "incident-template", "money", "server", "severity", "status-page", "store", "star", "tag", "user", "users" ], "example": "alert", "type": "string" }, "id": { "description": "ID of this catalog type", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" }, "is_editable": { "description": "Catalog types that are synced with external resources can't be edited", "example": false, "type": "boolean" }, "is_team_type": { "description": "Whether this catalog type is the designated team type in team settings", "example": false, "type": "boolean" }, "last_synced_at": { "description": "When this type was last synced (if it's ever been sync'd)", "example": "2021-08-17T13:28:57.801578Z", "format": "date-time", "type": "string" }, "name": { "description": "Name is the human readable name of this type", "example": "Kubernetes Cluster", "type": "string" }, "owning_team_ids": { "description": "IDs of the teams that own this catalog type", "example": [ "01G0J1EXE7AXZ2C93K61WBPYEH" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "ranked": { "description": "If this type should be ranked", "example": true, "type": "boolean" }, "registry_type": { "description": "The registry resource this type is synced from, if any", "example": "PagerDutyService", "type": "string" }, "required_integrations": { "description": "If populated, the integrations required for this type", "example": [ "pager_duty" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "schema": { "$ref": "#/components/schemas/CatalogTypeSchemaV3" }, "source_repo_url": { "description": "The url of the external repository where this type is managed", "example": "https://github.com/my-company/incident-io-catalog", "type": "string" }, "supports_custom_aliases": { "description": "Whether entries of this type take custom_aliases. Only catalog types that incident.io syncs do, as you can't change their aliases directly, and not those whose aliases you edit elsewhere, such as alert priorities.", "example": true, "type": "boolean" }, "type_name": { "description": "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\"]", "example": "Custom[\"BackstageGroup\"]", "type": "string" }, "updated_at": { "description": "When this type was last updated", "example": "2021-08-17T13:28:57.801578Z", "format": "date-time", "type": "string" }, "use_name_as_identifier": { "description": "If enabled, you can refer to entries of this type by their name, as well as their external ID and any aliases.", "example": true, "type": "boolean" } }, "required": [ "id", "name", "description", "type_name", "engine_resource_type", "ranked", "schema", "icon", "categories", "color", "is_editable", "supports_custom_aliases", "annotations", "created_at", "updated_at", "use_name_as_identifier" ], "type": "object" }, "PaginationMetaResultWithTotalV3": { "example": { "after": "01FCNDV6P870EA6S7TK1DSYDG0", "page_size": 25, "total_record_count": 238 }, "properties": { "after": { "description": "If provided, pass this as the 'after' param to load the next page", "example": "01FCNDV6P870EA6S7TK1DSYDG0", "type": "string" }, "page_size": { "default": 25, "description": "What was the maximum number of results requested", "example": 25, "format": "int64", "maximum": 250, "type": "integer" }, "total_record_count": { "description": "How many matching records were there in total, if known", "example": 238, "format": "int64", "type": "integer" } }, "required": [ "page_size" ], "type": "object" }, "ErrorDebug": { "example": { "message": "Something broke: and something else: and something else", "stacktrace": [ "thing.go:123" ] }, "properties": { "message": { "description": "Original internal error message", "example": "Something broke: and something else: and something else", "type": "string" }, "stacktrace": { "description": "Stacktrace of the error, if applicable", "example": [ "thing.go:123" ], "items": { "example": "thing.go:123", "type": "string" }, "type": "array" } }, "required": [ "message", "stacktrace" ], "type": "object" }, "ErrorSingle": { "example": { "code": "trial_expired", "message": "Default incident call link must be a valid URL", "metadata": { "abc123": "abc123" }, "source": { "field": "default_call_url", "pointer": "/settings/default_call_url" } }, "properties": { "code": { "description": "Machine-readable identifier for this specific error", "example": "trial_expired", "type": "string" }, "message": { "description": "Human readable description of the error", "example": "Default incident call link must be a valid URL", "type": "string" }, "metadata": { "additionalProperties": { "example": "abc123", "type": "string" }, "description": "Additional metadata about the error, keyed by a string identifier", "example": { "abc123": "abc123" }, "type": "object" }, "source": { "$ref": "#/components/schemas/ErrorSource" } }, "required": [ "code", "message" ], "type": "object" }, "ErrorRateLimit": { "example": { "limit": 100, "name": "client_ip", "remaining": 98, "retry_after": "2020-01-01T00:00:00Z" }, "properties": { "limit": { "description": "The maximum number of requests that the consumer is permitted to make per minute", "example": 100, "format": "int64", "type": "integer" }, "name": { "description": "Which rate limit was exceeded", "example": "client_ip", "type": "string" }, "remaining": { "description": "The number of requests remaining in the current rate limit window", "example": 98, "format": "int64", "type": "integer" }, "retry_after": { "description": "When the client can retry, as an RFC3339 timestamp in UTC. Prefer the Retry-After response header, which carries the same instant as a number of seconds", "example": "2020-01-01T00:00:00Z", "type": "string" } }, "required": [ "name", "limit", "remaining", "retry_after" ], "type": "object" }, "CatalogEngineParamBindingPayloadV3": { "example": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } }, "properties": { "array_value": { "description": "If set, this is the array value of the step parameter", "example": [ { "literal": "SEV123" } ], "items": { "$ref": "#/components/schemas/CatalogEngineParamBindingValuePayloadV3" }, "type": "array" }, "value": { "$ref": "#/components/schemas/CatalogEngineParamBindingValuePayloadV3" } }, "type": "object" }, "PartialEntryPayloadV3": { "description": "Represents a partial entry update, allowing selective field updates", "example": { "aliases": [ "abc123" ], "attribute_values": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "custom_aliases": [ "primary-on-call" ], "entry_id": "abc123", "external_id": "abc123", "name": "abc123", "rank": 1 }, "properties": { "aliases": { "description": "If specified, will update the aliases of the entry. When omitted, preserves the existing aliases.", "example": [ "abc123" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "attribute_values": { "additionalProperties": { "$ref": "#/components/schemas/CatalogEngineParamBindingPayloadV3" }, "description": "The attribute values to apply to this entry", "example": { "abc123": { "array_value": [ { "literal": "SEV123" } ], "value": { "literal": "SEV123" } } }, "type": "object" }, "custom_aliases": { "description": "Aliases your organisation adds to an entry of a catalog type that incident.io syncs, such as a schedule or escalation path, which you can't change aliases on directly. Omit this or send null to keep the entry's current custom aliases, send an empty list to clear them, or send a list to replace them. Only available on catalog types where supports_custom_aliases is true.", "example": [ "primary-on-call" ], "items": { "example": "abc123", "type": "string" }, "type": "array" }, "entry_id": { "description": "ID of the relevant catalog entry", "example": "abc123", "type": "string" }, "external_id": { "description": "If specified, will update the external ID of the entry. When omitted, preserves the existing external ID.", "example": "abc123", "type": "string" }, "name": { "description": "If specified, will update the name of the entry. When omitted, preserves the existing name.", "example": "abc123", "type": "string" }, "rank": { "description": "If specified, will update the rank of the entry. When omitted, rank will be set to null (allowing rank removal), unless incident.io syncs the catalog type, in which case the existing rank is preserved.", "example": 1, "format": "int32", "type": "integer" } }, "required": [ "entry_id", "attribute_values" ], "type": "object" }, "CatalogEntryEngineParamBindingV3": { "example": { "array_value": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "value": { "label": "Lawrence Jones", "literal": "SEV123" } }, "properties": { "array_value": { "description": "If the attribute is multi-valued, the value will be returned here.", "example": [ { "label": "Lawrence Jones", "literal": "SEV123" } ], "items": { "$ref": "#/components/schemas/CatalogEntryEngineParamBindingValueV3" }, "type": "array" }, "value": { "$ref": "#/components/schemas/CatalogEntryEngineParamBindingValueV3" } }, "type": "object" }, "CatalogTypeSchemaV3": { "example": { "attributes": [ { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" } ], "version": 1 }, "properties": { "attributes": { "description": "Attributes of this catalog type", "example": [ { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" } ], "items": { "$ref": "#/components/schemas/CatalogTypeAttributeV3" }, "type": "array" }, "version": { "description": "The version number of this schema", "example": 1, "format": "int64", "type": "integer" } }, "required": [ "attributes", "version" ], "type": "object" }, "ErrorSource": { "example": { "field": "default_call_url", "pointer": "/settings/default_call_url" }, "properties": { "field": { "description": "Field name that is the source of the error", "example": "default_call_url", "type": "string" }, "pointer": { "description": "JSON pointer to the request field that is the source of the error", "example": "/settings/default_call_url", "type": "string" } }, "required": [ "field", "pointer" ], "type": "object" }, "CatalogEngineParamBindingValuePayloadV3": { "example": { "literal": "SEV123" }, "properties": { "literal": { "description": "If set, this is the literal value of the step parameter", "example": "SEV123", "type": "string" } }, "type": "object" }, "CatalogEntryEngineParamBindingValueV3": { "example": { "label": "Lawrence Jones", "literal": "SEV123" }, "properties": { "label": { "description": "A label for this attribute value. If the attribute refers to another Catalog entry, this will be the name of that entry.", "example": "Lawrence Jones", "type": "string" }, "literal": { "description": "The underlying value of the attribute, serialized as a string.\n\nFor String, Text, Number, and Bool typed attributes, this will be empty. For attributes that refer to another catalog entry, this can be the ID, external ID, or one of the aliases of that catalog entry.", "example": "SEV123", "type": "string" } }, "required": [ "label" ], "type": "object" }, "CatalogTypeAttributeV3": { "example": { "array": false, "backlink_attribute": "abc123", "id": "01GW2G3V0S59R238FAHPDS1R66", "mode": "", "name": "tier", "path": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "type": "Custom[\"Service\"]" }, "properties": { "array": { "description": "Whether this attribute is an array", "example": false, "type": "boolean" }, "backlink_attribute": { "description": "The attribute to use (if this is a backlink)", "example": "abc123", "type": "string" }, "id": { "description": "The ID of this attribute", "example": "01GW2G3V0S59R238FAHPDS1R66", "type": "string" }, "mode": { "description": "Controls how this attribute is modified", "enum": [ "", "api", "dashboard", "external", "internal", "dynamic", "backlink", "path" ], "example": "", "type": "string", "x-public-api-version": "v3" }, "name": { "description": "Unique name of this attribute", "example": "tier", "type": "string" }, "path": { "description": "The path to use (if this is a path attribute)", "example": [ { "attribute_id": "abc123", "attribute_name": "abc123" } ], "items": { "$ref": "#/components/schemas/CatalogTypeAttributePathItemV3" }, "type": "array" }, "type": { "description": "Catalog type name for this attribute", "example": "Custom[\"Service\"]", "type": "string" } }, "required": [ "id", "mode", "name", "type", "array" ], "type": "object" }, "CatalogTypeAttributePathItemV3": { "example": { "attribute_id": "abc123", "attribute_name": "abc123" }, "properties": { "attribute_id": { "description": "the ID of the attribute to use", "example": "abc123", "type": "string" }, "attribute_name": { "description": "the name of the attribute to use", "example": "abc123", "type": "string" } }, "required": [ "attribute_id", "attribute_name" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from your incident.io dashboard (Settings → API keys)" } } } }