From fd8423a5e80408f37b6b9d492e7b375b15842b01 Mon Sep 17 00:00:00 2001 From: Flashduty AI-SRE Date: Fri, 25 Sep 2026 08:17:56 +0000 Subject: [PATCH] =?UTF-8?q?docs(api):=20daily=20audit=202026-09-25=20?= =?UTF-8?q?=E2=80=94=20document=20the=20new=20/integration=20API=20family?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nine public operations registered in fc-pgy after the last regeneration (merged with #1025, 2026-09-22) are now documented: the /integration/* family manages alert- and change-source integrations through app_key — type/list, list, info, create, update, delete, enable, disable, key/rotate. Handlers live on fc-datasource main (cmd/datasource/routes.go:70); the read permission is Integrations Read, the writes Integrations Manage (on-call). Also repairs the on-call notification-template contract: TemplateCreateRequest, TemplateUpdateRequest and TemplateItem were missing dingtalk_app_war_room_enabled and slack_app_war_room_enabled, which fc-event's template structs and the DingTalk/Slack card renderer have carried since e43bbcbf5. Operations were added, so docs.json (both languages) and both api-catalog.mdx files were reconciled: On-call 193 -> 202, total 338 -> 347. Diff is purely additive (1359/0 per spec file under the default algorithm) with every pre-existing key keeping its relative order; EN/ZH structurally identical. --- api-reference/on-call.openapi.en.json | 1359 +++++++++++++++++++++++++ api-reference/on-call.openapi.zh.json | 1359 +++++++++++++++++++++++++ api-reference/openapi.en.json | 1359 +++++++++++++++++++++++++ api-reference/openapi.zh.json | 1359 +++++++++++++++++++++++++ docs.json | 22 +- en/openapi/api-catalog.mdx | 13 +- zh/openapi/api-catalog.mdx | 13 +- 7 files changed, 5478 insertions(+), 6 deletions(-) diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index a76fc6d4..394acfc5 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -142,6 +142,745 @@ } } }, + "/integration/type/list": { + "post": { + "operationId": "integration-api-read-type-list", + "summary": "List integration types", + "description": "List the integration types the account can configure.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- When `orderby` is omitted, types come back in console ranking order and `p`/`limit` still apply.\n- `supports_api_create` tells you which types `POST /integration/create` accepts.", + "href": "/en/api-reference/on-call/integrations/integration-api-read-type-list", + "metadata": { + "sidebarTitle": "List integration types" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListIntegrationTypesResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 2, + "items": [ + { + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "plugin_type_logo_url": "https://cdn.flashcat.cloud/plugin/standard-alert.svg", + "category": "event.alert", + "status": "enabled", + "supports_api_create": true + }, + { + "plugin_type": "jira.change", + "plugin_type_name": "Jira", + "plugin_type_logo_url": "https://cdn.flashcat.cloud/plugin/jira.svg", + "category": "event.change", + "status": "enabled", + "supports_api_create": true + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationTypeListRequest" + }, + "example": { + "p": 1, + "limit": 20, + "category": "event.alert" + } + } + } + } + } + }, + "/integration/list": { + "post": { + "operationId": "integration-api-read-list", + "summary": "List integrations", + "description": "List the account's alert-source and change-source integrations.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- `orderby` defaults to `created_at`; `plugin_type` is sorted by the underlying plugin.\n- `plugin_type`, `status` and `category` accept comma-separated values; `ref_ids` values must start with `c_`, `a_` or `w_`.\n- With `is_my_team` set, results are limited to your teams and `team_ids` narrows that set further.", + "href": "/en/api-reference/on-call/integrations/integration-api-read-list", + "metadata": { + "sidebarTitle": "List integrations" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListIntegrationsResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 1, + "items": [ + { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775203200, + "last_time": 1775298600 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListIntegrationsRequest" + }, + "example": { + "p": 1, + "limit": 20, + "status": "enabled" + } + } + } + } + } + }, + "/integration/info": { + "post": { + "operationId": "integration-api-read-info", + "summary": "Get integration detail", + "description": "Return one integration, including its settings with sensitive values masked.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- Sensitive settings (endpoint, headers, secrets, passwords) come back masked as `******`.", + "href": "/en/api-reference/on-call/integrations/integration-api-read-info", + "metadata": { + "sidebarTitle": "Get integration detail" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/IntegrationDetail" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775203200, + "last_time": 1775298600, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ], + "labels": { + "source": "prometheus" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetIntegrationRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/create": { + "post": { + "operationId": "integration-api-write-create", + "summary": "Create integration", + "description": "Create an integration for an alert source or change source.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `plugin_type` must be one of the types listed by `POST /integration/type/list` with `supports_api_create: true`; anything else returns `InvalidParameter`.\n- `integration_key` is returned once. Store it at creation time — it is not part of `POST /integration/info`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-create", + "metadata": { + "sidebarTitle": "Create integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CreateIntegrationResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "integration_key": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateIntegrationRequest" + }, + "example": { + "plugin_type": "standard.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "team_id": 1467226103121, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ] + } + } + } + } + } + } + }, + "/integration/update": { + "post": { + "operationId": "integration-api-write-update", + "summary": "Update integration", + "description": "Update an integration's name, description, team, or settings.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields you send are changed; omitted fields keep their current value.\n- `settings` replaces the stored configuration. Sensitive entries left out, or sent back as the masked `******`, keep their stored value.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-update", + "metadata": { + "sidebarTitle": "Update integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/IntegrationDetail" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts (primary)", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775298600, + "last_time": 1775298600, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ], + "labels": { + "source": "prometheus" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateIntegrationRequest" + }, + "example": { + "integration_id": 6113996590131, + "name": "Prod metrics alerts (primary)", + "team_id": 1467226103121 + } + } + } + } + } + }, + "/integration/delete": { + "post": { + "operationId": "integration-api-write-delete", + "summary": "Delete integration", + "description": "Delete an integration that nothing else references.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Deleting an integration that other objects still reference returns HTTP 400 with `error.code` = `ReferenceExist` and `data.refs` listing them.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-delete", + "metadata": { + "sidebarTitle": "Delete integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/enable": { + "post": { + "operationId": "integration-api-write-enable", + "summary": "Enable integration", + "description": "Re-enable a disabled integration so it accepts events again.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enabling an integration resumes its scheduled pull task and heartbeat, and requires the integration type to be available on the current plan.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-enable", + "metadata": { + "sidebarTitle": "Enable integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/disable": { + "post": { + "operationId": "integration-api-write-disable", + "summary": "Disable integration", + "description": "Disable an integration without deleting its configuration.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Disabling stops event ingestion and pauses the scheduled pull task; settings are kept so the integration can be enabled again.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-disable", + "metadata": { + "sidebarTitle": "Disable integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/key/rotate": { + "post": { + "operationId": "integration-api-write-rotate-key", + "summary": "Rotate integration key", + "description": "Issue a new integration key and invalidate the previous one.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- The previous key stops working immediately, so update the pushing side before rotating.\n- The new key is returned once and cannot be read again later.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-rotate-key", + "metadata": { + "sidebarTitle": "Rotate integration key" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RotateIntegrationKeyResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_key": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, "/enrichment/mapping/data/truncate": { "post": { "operationId": "mapping-data-write-truncate", @@ -28532,6 +29271,14 @@ "type": "boolean", "description": "Show the Create War Room button on Feishu app cards." }, + "dingtalk_app_war_room_enabled": { + "type": "boolean", + "description": "Show the Create War Room button on DingTalk app cards." + }, + "slack_app_war_room_enabled": { + "type": "boolean", + "description": "Show the Create War Room button on Slack app cards." + }, "dingtalk_app": { "type": "string", "description": "DingTalk app message template source." @@ -28636,6 +29383,8 @@ "wecom_markdown_v2_enabled", "feishu_app_card_v2_preserve_blank_lines", "feishu_app_war_room_enabled", + "dingtalk_app_war_room_enabled", + "slack_app_war_room_enabled", "dingtalk_app", "wecom_app", "slack_app", @@ -28720,6 +29469,14 @@ "type": "boolean", "description": "Whether Feishu app cards show the Create War Room button. Hidden when the incident has no responders." }, + "dingtalk_app_war_room_enabled": { + "type": "boolean", + "description": "Whether DingTalk app cards show the Create War Room button. Hidden for closed incidents and when the incident has no responders." + }, + "slack_app_war_room_enabled": { + "type": "boolean", + "description": "Whether Slack app cards show the Create War Room button. Hidden for closed incidents and when the incident has no responders." + }, "dingtalk_app": { "type": "string", "description": "DingTalk app message template source." @@ -29003,6 +29760,20 @@ ], "description": "When set, show or hide the Create War Room button on Feishu app cards. Omit to keep the existing setting." }, + "dingtalk_app_war_room_enabled": { + "type": [ + "boolean", + "null" + ], + "description": "When set, show or hide the Create War Room button on DingTalk app cards. Omit to keep the existing setting." + }, + "slack_app_war_room_enabled": { + "type": [ + "boolean", + "null" + ], + "description": "When set, show or hide the Create War Room button on Slack app cards. Omit to keep the existing setting." + }, "dingtalk_app": { "type": [ "string", @@ -33627,6 +34398,594 @@ "format": "int64" } } + }, + "IntegrationTypeListRequest": { + "type": "object", + "description": "Filter parameters for listing integration types.", + "properties": { + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Page number, 1-based." + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20, + "description": "Page size. Defaults to 20, maximum 100." + }, + "orderby": { + "type": "string", + "description": "Sort field. When omitted, types are returned in console ranking order.", + "enum": [ + "id", + "created_at", + "updated_at", + "name", + "type" + ] + }, + "category": { + "type": "string", + "description": "Filter by category. Accepts a comma-separated list, for example `event.alert,event.change`." + }, + "asc": { + "type": [ + "boolean", + "null" + ], + "default": true, + "description": "Sort ascending when `true` (the default); descending when `false`." + } + } + }, + "IntegrationTypeItem": { + "type": "object", + "description": "An integration type the account can configure.", + "required": [ + "plugin_type", + "plugin_type_name", + "plugin_type_logo_url", + "category", + "status", + "supports_api_create" + ], + "properties": { + "plugin_type": { + "type": "string", + "description": "Type identifier to pass as `plugin_type` when creating an integration.", + "example": "standard.alert" + }, + "plugin_type_name": { + "type": "string", + "description": "Display name of the type.", + "example": "Standard Alert" + }, + "plugin_type_logo_url": { + "type": "string", + "description": "Logo URL of the type." + }, + "category": { + "type": "string", + "description": "Category the type belongs to.", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ] + }, + "status": { + "type": "string", + "description": "Platform status of the type." + }, + "supports_api_create": { + "type": "boolean", + "description": "Whether `POST /integration/create` accepts this type." + } + } + }, + "ListIntegrationTypesResponse": { + "type": "object", + "description": "A page of integration types.", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "Page number echoed back." + }, + "limit": { + "type": "integer", + "description": "Page size echoed back." + }, + "total": { + "type": "integer", + "format": "int64", + "description": "Total number of matching types." + }, + "items": { + "type": "array", + "description": "Integration types on the current page.", + "items": { + "$ref": "#/components/schemas/IntegrationTypeItem" + } + } + } + }, + "ListIntegrationsRequest": { + "type": "object", + "description": "Filter parameters for listing integrations.", + "properties": { + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Page number, 1-based." + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20, + "description": "Page size. Defaults to 20, maximum 100." + }, + "orderby": { + "type": "string", + "description": "Sort field. Defaults to `created_at`; `plugin_type` is sorted by the underlying plugin.", + "enum": [ + "created_at", + "updated_at", + "name", + "plugin_type", + "status" + ] + }, + "category": { + "type": "string", + "description": "Filter by category. Accepts a comma-separated list." + }, + "type": { + "type": "string", + "description": "Deprecated. Merged into `plugin_type` when both are set." + }, + "plugin_type": { + "type": "string", + "description": "Filter by integration type. Accepts a comma-separated list." + }, + "status": { + "type": "string", + "description": "Filter by status. Accepts a comma-separated list." + }, + "name": { + "type": "string", + "description": "Filter by integration name." + }, + "ref_ids": { + "type": "array", + "description": "Filter by source reference IDs. Each value must start with `c_` (channel), `a_` (account) or `w_`.", + "items": { + "type": "string" + } + }, + "asc": { + "type": "boolean", + "description": "Sort ascending when true, descending when false." + }, + "is_my_team": { + "type": "boolean", + "description": "Limit the result to integrations owned by your teams." + }, + "team_ids": { + "type": "array", + "description": "Filter by team IDs. With `is_my_team`, the values narrow that set further.", + "items": { + "type": "integer", + "format": "int64" + } + } + } + }, + "IntegrationItem": { + "type": "object", + "description": "A configured integration. Timestamps are Unix epoch seconds.", + "required": [ + "integration_id", + "team_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "ref_id", + "created_at", + "updated_at", + "last_time" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "Integration ID." + }, + "team_id": { + "type": "integer", + "format": "int64", + "description": "ID of the team that owns the integration. `0` when it is not assigned to a team." + }, + "plugin_type": { + "type": "string", + "description": "Integration type, for example `standard.alert` or `zabbix.alert`." + }, + "plugin_type_name": { + "type": "string", + "description": "Display name of the integration type, in the language of the request." + }, + "category": { + "type": "string", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ], + "description": "Category the integration belongs to." + }, + "name": { + "type": "string", + "description": "Integration name." + }, + "description": { + "type": "string", + "description": "Free-form description." + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Lifecycle status: `enabled` while the integration accepts events, `disabled` when it is paused." + }, + "ref_id": { + "type": "string", + "description": "Source reference ID: `a_`-prefixed for an account-scoped integration, `c_`-prefixed when it is shared into a channel." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the integration was created." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the integration was last updated." + }, + "last_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds of the most recent event received. `0` when no event has arrived yet." + } + } + }, + "ListIntegrationsResponse": { + "type": "object", + "description": "A page of integrations.", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "Page number echoed back." + }, + "limit": { + "type": "integer", + "description": "Page size echoed back." + }, + "total": { + "type": "integer", + "format": "int64", + "description": "Total number of matching integrations." + }, + "items": { + "type": "array", + "description": "Integrations on the current page.", + "items": { + "$ref": "#/components/schemas/IntegrationItem" + } + } + } + }, + "GetIntegrationRequest": { + "type": "object", + "description": "Identifies one integration.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "Integration ID.", + "example": 6113996590131 + } + } + }, + "IntegrationDetail": { + "type": "object", + "description": "A single integration with its full settings. Timestamps are Unix epoch seconds.", + "required": [ + "integration_id", + "team_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "ref_id", + "created_at", + "updated_at", + "last_time", + "settings" + ], + "properties": { + "integration_id": [ + { + "type": "integer", + "format": "int64", + "description": "Integration ID." + }, + true + ], + "team_id": [ + { + "type": "integer", + "format": "int64", + "description": "ID of the team that owns the integration. `0` when it is not assigned to a team." + }, + true + ], + "plugin_type": [ + { + "type": "string", + "description": "Integration type, for example `standard.alert` or `zabbix.alert`." + }, + true + ], + "plugin_type_name": [ + { + "type": "string", + "description": "Display name of the integration type, in the language of the request." + }, + true + ], + "category": [ + { + "type": "string", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ], + "description": "Category the integration belongs to." + }, + true + ], + "name": [ + { + "type": "string", + "description": "Integration name." + }, + true + ], + "description": [ + { + "type": "string", + "description": "Free-form description." + }, + true + ], + "status": [ + { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Lifecycle status: `enabled` while the integration accepts events, `disabled` when it is paused." + }, + true + ], + "ref_id": [ + { + "type": "string", + "description": "Source reference ID: `a_`-prefixed for an account-scoped integration, `c_`-prefixed when it is shared into a channel." + }, + true + ], + "created_at": [ + { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the integration was created." + }, + true + ], + "updated_at": [ + { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the integration was last updated." + }, + true + ], + "last_time": [ + { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds of the most recent event received. `0` when no event has arrived yet." + }, + true + ], + "settings": { + "type": "object", + "additionalProperties": true, + "description": "Type-specific configuration. Sensitive values (endpoint, headers, secrets, passwords) are returned masked as `******`." + } + } + }, + "CreateIntegrationRequest": { + "type": "object", + "description": "Payload for creating an integration.", + "required": [ + "plugin_type" + ], + "properties": { + "plugin_type": { + "type": "string", + "description": "Integration type. Must be one listed by `POST /integration/type/list` with `supports_api_create: true`.", + "example": "standard.alert" + }, + "name": { + "type": "string", + "minLength": 2, + "maxLength": 49, + "description": "Integration name. 2–49 characters.", + "example": "Prod metrics alerts" + }, + "description": { + "type": "string", + "maxLength": 499, + "description": "Free-form description, at most 499 characters." + }, + "team_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "Owning team ID.", + "example": 1467226103121 + }, + "settings": { + "type": "object", + "description": "Type-specific configuration; the accepted keys depend on `plugin_type`.", + "additionalProperties": true + } + } + }, + "CreateIntegrationResponse": { + "type": "object", + "description": "The created integration and its key.", + "required": [ + "integration_id", + "integration_key" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "ID of the new integration.", + "example": 6113996590131 + }, + "integration_key": { + "type": "string", + "description": "Key used to authenticate inbound pushes to this integration. Returned here only; fetch a new one with `POST /integration/key/rotate`.", + "example": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + }, + "UpdateIntegrationRequest": { + "type": "object", + "description": "Payload for updating an integration. Only the fields you send are changed.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "Integration ID.", + "example": 6113996590131 + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 2, + "maxLength": 49, + "description": "New name, 2–49 characters." + }, + "description": { + "type": [ + "string", + "null" + ], + "maxLength": 499, + "description": "New description, at most 499 characters." + }, + "team_id": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 0, + "description": "New owning team ID; `0` clears the team assignment." + }, + "settings": { + "type": [ + "object", + "null" + ], + "description": "Replacement configuration for the integration type. Sensitive entries left out, or sent back as the masked `******`, keep their stored value.", + "additionalProperties": true + } + } + }, + "IntegrationLifecycleRequest": { + "type": "object", + "description": "Identifies the integration to act on.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "Integration ID.", + "example": 6113996590131 + } + } + }, + "RotateIntegrationKeyResponse": { + "type": "object", + "description": "The newly issued integration key.", + "required": [ + "integration_key" + ], + "properties": { + "integration_key": { + "type": "string", + "description": "The new key. The previous key stops working immediately; this value cannot be read again later.", + "example": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } } } } diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index 3d49ef29..62b12269 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -142,6 +142,745 @@ } } }, + "/integration/type/list": { + "post": { + "operationId": "integration-api-read-type-list", + "summary": "查询集成类型列表", + "description": "查询当前账户可配置的集成类型列表。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。", + "href": "/zh/api-reference/on-call/integrations/integration-api-read-type-list", + "metadata": { + "sidebarTitle": "查询集成类型列表" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListIntegrationTypesResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 2, + "items": [ + { + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "plugin_type_logo_url": "https://cdn.flashcat.cloud/plugin/standard-alert.svg", + "category": "event.alert", + "status": "enabled", + "supports_api_create": true + }, + { + "plugin_type": "jira.change", + "plugin_type_name": "Jira", + "plugin_type_logo_url": "https://cdn.flashcat.cloud/plugin/jira.svg", + "category": "event.change", + "status": "enabled", + "supports_api_create": true + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationTypeListRequest" + }, + "example": { + "p": 1, + "limit": 20, + "category": "event.alert" + } + } + } + } + } + }, + "/integration/list": { + "post": { + "operationId": "integration-api-read-list", + "summary": "查询集成列表", + "description": "查询当前账户的告警源与变更源集成列表。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- `orderby` 默认 `created_at`；`plugin_type` 按底层插件排序。\n- `plugin_type`、`status`、`category` 支持逗号分隔多值；`ref_ids` 每个值必须以 `c_`、`a_` 或 `w_` 开头。\n- 传入 `is_my_team` 时仅返回你所在团队的集成，`team_ids` 会在该范围内进一步收窄。", + "href": "/zh/api-reference/on-call/integrations/integration-api-read-list", + "metadata": { + "sidebarTitle": "查询集成列表" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListIntegrationsResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 1, + "items": [ + { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775203200, + "last_time": 1775298600 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListIntegrationsRequest" + }, + "example": { + "p": 1, + "limit": 20, + "status": "enabled" + } + } + } + } + } + }, + "/integration/info": { + "post": { + "operationId": "integration-api-read-info", + "summary": "查询集成详情", + "description": "查询单个集成详情，敏感配置以打码形式返回。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 敏感配置（endpoint、headers、密钥、密码）均以 `******` 打码返回。", + "href": "/zh/api-reference/on-call/integrations/integration-api-read-info", + "metadata": { + "sidebarTitle": "查询集成详情" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/IntegrationDetail" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775203200, + "last_time": 1775298600, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ], + "labels": { + "source": "prometheus" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetIntegrationRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/create": { + "post": { + "operationId": "integration-api-write-create", + "summary": "创建集成", + "description": "为某个告警源或变更源创建集成。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `plugin_type` 必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型，否则返回 `InvalidParameter`。\n- `integration_key` 仅在创建时返回一次，请及时保存；`POST /integration/info` 不会返回该字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-create", + "metadata": { + "sidebarTitle": "创建集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CreateIntegrationResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "integration_key": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateIntegrationRequest" + }, + "example": { + "plugin_type": "standard.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "team_id": 1467226103121, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ] + } + } + } + } + } + } + }, + "/integration/update": { + "post": { + "operationId": "integration-api-write-update", + "summary": "更新集成", + "description": "更新集成的名称、描述、所属团队或配置。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 仅发送的字段会被修改，未发送的字段保持原值。\n- `settings` 会整体替换已存储的配置；敏感字段不传、或原样回传打码值 `******`，都会保留已存储的值。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-update", + "metadata": { + "sidebarTitle": "更新集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/IntegrationDetail" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts (primary)", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775298600, + "last_time": 1775298600, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ], + "labels": { + "source": "prometheus" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateIntegrationRequest" + }, + "example": { + "integration_id": 6113996590131, + "name": "Prod metrics alerts (primary)", + "team_id": 1467226103121 + } + } + } + } + } + }, + "/integration/delete": { + "post": { + "operationId": "integration-api-write-delete", + "summary": "删除集成", + "description": "删除指定的集成。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 若该集成仍被其他对象引用，删除会返回 HTTP 400，`error.code` 为 `ReferenceExist`，`data.refs` 列出引用方。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-delete", + "metadata": { + "sidebarTitle": "删除集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/enable": { + "post": { + "operationId": "integration-api-write-enable", + "summary": "启用集成", + "description": "重新启用已禁用的集成，恢复接收事件。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 启用会恢复该集成的拉取任务与心跳，并要求当前套餐包含该集成类型。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-enable", + "metadata": { + "sidebarTitle": "启用集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/disable": { + "post": { + "operationId": "integration-api-write-disable", + "summary": "禁用集成", + "description": "禁用集成，但保留其配置。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 禁用后停止接收事件并暂停定时拉取任务，配置保留，可再次启用。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-disable", + "metadata": { + "sidebarTitle": "禁用集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/key/rotate": { + "post": { + "operationId": "integration-api-write-rotate-key", + "summary": "轮换集成 Key", + "description": "生成新的集成 Key，并使旧 Key 立即失效。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 旧 Key 会立即失效，请先更新推送侧再轮换。\n- 新 Key 只返回一次，之后无法再次读取。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-rotate-key", + "metadata": { + "sidebarTitle": "轮换集成 Key" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RotateIntegrationKeyResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_key": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, "/enrichment/mapping/data/truncate": { "post": { "operationId": "mapping-data-write-truncate", @@ -28532,6 +29271,14 @@ "type": "boolean", "description": "飞书应用卡片展示「创建作战室」按钮。" }, + "dingtalk_app_war_room_enabled": { + "type": "boolean", + "description": "钉钉应用卡片展示「创建作战室」按钮。" + }, + "slack_app_war_room_enabled": { + "type": "boolean", + "description": "Slack 应用卡片展示「创建作战室」按钮。" + }, "dingtalk_app": { "type": "string", "description": "钉钉应用消息模板源。" @@ -28636,6 +29383,8 @@ "wecom_markdown_v2_enabled", "feishu_app_card_v2_preserve_blank_lines", "feishu_app_war_room_enabled", + "dingtalk_app_war_room_enabled", + "slack_app_war_room_enabled", "dingtalk_app", "wecom_app", "slack_app", @@ -28720,6 +29469,14 @@ "type": "boolean", "description": "飞书应用卡片是否展示「创建作战室」按钮；故障无响应人时不展示。" }, + "dingtalk_app_war_room_enabled": { + "type": "boolean", + "description": "钉钉应用卡片是否展示「创建作战室」按钮；故障已关闭或无响应人时不展示。" + }, + "slack_app_war_room_enabled": { + "type": "boolean", + "description": "Slack 应用卡片是否展示「创建作战室」按钮；故障已关闭或无响应人时不展示。" + }, "dingtalk_app": { "type": "string", "description": "钉钉应用消息模板源。" @@ -29003,6 +29760,20 @@ ], "description": "设置后决定飞书应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。" }, + "dingtalk_app_war_room_enabled": { + "type": [ + "boolean", + "null" + ], + "description": "设置后决定钉钉应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。" + }, + "slack_app_war_room_enabled": { + "type": [ + "boolean", + "null" + ], + "description": "设置后决定 Slack 应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。" + }, "dingtalk_app": { "type": [ "string", @@ -33627,6 +34398,594 @@ "format": "int64" } } + }, + "IntegrationTypeListRequest": { + "type": "object", + "description": "查询集成类型列表的过滤参数。", + "properties": { + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "页码，从 1 开始。" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20, + "description": "每页条数，默认 20，最大 100。" + }, + "orderby": { + "type": "string", + "description": "排序字段；不传时按控制台排序返回。", + "enum": [ + "id", + "created_at", + "updated_at", + "name", + "type" + ] + }, + "category": { + "type": "string", + "description": "按分类过滤，支持逗号分隔多个值，例如 `event.alert,event.change`。" + }, + "asc": { + "type": [ + "boolean", + "null" + ], + "default": true, + "description": "`true`（默认）升序，`false` 降序。" + } + } + }, + "IntegrationTypeItem": { + "type": "object", + "description": "账户可配置的一种集成类型。", + "required": [ + "plugin_type", + "plugin_type_name", + "plugin_type_logo_url", + "category", + "status", + "supports_api_create" + ], + "properties": { + "plugin_type": { + "type": "string", + "description": "创建集成时作为 `plugin_type` 传入的类型标识。", + "example": "standard.alert" + }, + "plugin_type_name": { + "type": "string", + "description": "类型显示名。", + "example": "Standard Alert" + }, + "plugin_type_logo_url": { + "type": "string", + "description": "类型 Logo 地址。" + }, + "category": { + "type": "string", + "description": "类型所属分类。", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ] + }, + "status": { + "type": "string", + "description": "该类型在平台侧的状态。" + }, + "supports_api_create": { + "type": "boolean", + "description": "该类型能否通过 `POST /integration/create` 创建。" + } + } + }, + "ListIntegrationTypesResponse": { + "type": "object", + "description": "集成类型列表的一页。", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "当前每页条数。" + }, + "total": { + "type": "integer", + "format": "int64", + "description": "匹配的类型总数。" + }, + "items": { + "type": "array", + "description": "当前页的集成类型。", + "items": { + "$ref": "#/components/schemas/IntegrationTypeItem" + } + } + } + }, + "ListIntegrationsRequest": { + "type": "object", + "description": "查询集成列表的过滤参数。", + "properties": { + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "页码，从 1 开始。" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20, + "description": "每页条数，默认 20，最大 100。" + }, + "orderby": { + "type": "string", + "description": "排序字段，默认 `created_at`；`plugin_type` 按底层插件排序。", + "enum": [ + "created_at", + "updated_at", + "name", + "plugin_type", + "status" + ] + }, + "category": { + "type": "string", + "description": "按分类过滤，支持逗号分隔多个值。" + }, + "type": { + "type": "string", + "description": "已废弃；与 `plugin_type` 同时传入时会合并生效。" + }, + "plugin_type": { + "type": "string", + "description": "按集成类型过滤，支持逗号分隔多个值。" + }, + "status": { + "type": "string", + "description": "按状态过滤，支持逗号分隔多个值。" + }, + "name": { + "type": "string", + "description": "按集成名称过滤。" + }, + "ref_ids": { + "type": "array", + "description": "按来源引用 ID 过滤；每个值必须以 `c_`（协作空间）、`a_`（账户）或 `w_` 开头。", + "items": { + "type": "string" + } + }, + "asc": { + "type": "boolean", + "description": "`true` 升序，`false` 降序。" + }, + "is_my_team": { + "type": "boolean", + "description": "仅返回你所在团队拥有的集成。" + }, + "team_ids": { + "type": "array", + "description": "按团队 ID 过滤；与 `is_my_team` 同时使用时在其结果内进一步收窄。", + "items": { + "type": "integer", + "format": "int64" + } + } + } + }, + "IntegrationItem": { + "type": "object", + "description": "已配置的集成；时间字段为 Unix 时间戳（秒）。", + "required": [ + "integration_id", + "team_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "ref_id", + "created_at", + "updated_at", + "last_time" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "集成 ID。" + }, + "team_id": { + "type": "integer", + "format": "int64", + "description": "所属团队 ID；未归属团队时为 `0`。" + }, + "plugin_type": { + "type": "string", + "description": "集成类型，例如 `standard.alert`、`zabbix.alert`。" + }, + "plugin_type_name": { + "type": "string", + "description": "集成类型显示名，随请求语言变化。" + }, + "category": { + "type": "string", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ], + "description": "集成所属分类。" + }, + "name": { + "type": "string", + "description": "集成名称。" + }, + "description": { + "type": "string", + "description": "集成描述。" + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "状态：`enabled` 正常接收事件，`disabled` 已暂停。" + }, + "ref_id": { + "type": "string", + "description": "来源引用 ID：`a_` 开头表示账户级集成，集成被共享到协作空间时为 `c_` 开头。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间的 Unix 时间戳（秒）。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最近更新时间的 Unix 时间戳（秒）。" + }, + "last_time": { + "type": "integer", + "format": "int64", + "description": "最近收到事件时间的 Unix 时间戳（秒），尚未收到事件时为 `0`。" + } + } + }, + "ListIntegrationsResponse": { + "type": "object", + "description": "集成列表的一页。", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "当前每页条数。" + }, + "total": { + "type": "integer", + "format": "int64", + "description": "匹配的集成总数。" + }, + "items": { + "type": "array", + "description": "当前页的集成。", + "items": { + "$ref": "#/components/schemas/IntegrationItem" + } + } + } + }, + "GetIntegrationRequest": { + "type": "object", + "description": "指定一个集成。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "集成 ID。", + "example": 6113996590131 + } + } + }, + "IntegrationDetail": { + "type": "object", + "description": "单个集成详情，含完整配置；时间字段为 Unix 时间戳（秒）。", + "required": [ + "integration_id", + "team_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "ref_id", + "created_at", + "updated_at", + "last_time", + "settings" + ], + "properties": { + "integration_id": [ + { + "type": "integer", + "format": "int64", + "description": "集成 ID。" + }, + true + ], + "team_id": [ + { + "type": "integer", + "format": "int64", + "description": "所属团队 ID；未归属团队时为 `0`。" + }, + true + ], + "plugin_type": [ + { + "type": "string", + "description": "集成类型，例如 `standard.alert`、`zabbix.alert`。" + }, + true + ], + "plugin_type_name": [ + { + "type": "string", + "description": "集成类型显示名，随请求语言变化。" + }, + true + ], + "category": [ + { + "type": "string", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ], + "description": "集成所属分类。" + }, + true + ], + "name": [ + { + "type": "string", + "description": "集成名称。" + }, + true + ], + "description": [ + { + "type": "string", + "description": "集成描述。" + }, + true + ], + "status": [ + { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "状态：`enabled` 正常接收事件，`disabled` 已暂停。" + }, + true + ], + "ref_id": [ + { + "type": "string", + "description": "来源引用 ID：`a_` 开头表示账户级集成，集成被共享到协作空间时为 `c_` 开头。" + }, + true + ], + "created_at": [ + { + "type": "integer", + "format": "int64", + "description": "创建时间的 Unix 时间戳（秒）。" + }, + true + ], + "updated_at": [ + { + "type": "integer", + "format": "int64", + "description": "最近更新时间的 Unix 时间戳（秒）。" + }, + true + ], + "last_time": [ + { + "type": "integer", + "format": "int64", + "description": "最近收到事件时间的 Unix 时间戳（秒），尚未收到事件时为 `0`。" + }, + true + ], + "settings": { + "type": "object", + "additionalProperties": true, + "description": "集成类型专属配置；敏感字段（endpoint、headers、密钥、密码）以 `******` 打码返回。" + } + } + }, + "CreateIntegrationRequest": { + "type": "object", + "description": "创建集成的请求体。", + "required": [ + "plugin_type" + ], + "properties": { + "plugin_type": { + "type": "string", + "description": "集成类型，必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型。", + "example": "standard.alert" + }, + "name": { + "type": "string", + "minLength": 2, + "maxLength": 49, + "description": "集成名称，2–49 个字符。", + "example": "Prod metrics alerts" + }, + "description": { + "type": "string", + "maxLength": 499, + "description": "集成描述，最长 499 个字符。" + }, + "team_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "所属团队 ID。", + "example": 1467226103121 + }, + "settings": { + "type": "object", + "description": "集成类型专属配置，可传字段取决于 `plugin_type`。", + "additionalProperties": true + } + } + }, + "CreateIntegrationResponse": { + "type": "object", + "description": "创建结果与集成 Key。", + "required": [ + "integration_id", + "integration_key" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "新建集成的 ID。", + "example": 6113996590131 + }, + "integration_key": { + "type": "string", + "description": "该集成的推送鉴权 Key，仅在此处返回；需要新 Key 请调用 `POST /integration/key/rotate`。", + "example": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + }, + "UpdateIntegrationRequest": { + "type": "object", + "description": "更新集成的请求体；仅发送的字段会被修改。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "集成 ID。", + "example": 6113996590131 + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 2, + "maxLength": 49, + "description": "新的集成名称，2–49 个字符。" + }, + "description": { + "type": [ + "string", + "null" + ], + "maxLength": 499, + "description": "新的集成描述，最长 499 个字符。" + }, + "team_id": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 0, + "description": "新的所属团队 ID；传 `0` 表示清除团队归属。" + }, + "settings": { + "type": [ + "object", + "null" + ], + "description": "替换该集成类型的配置；敏感字段不传、或原样回传 `******`，都会保留已存储的值。", + "additionalProperties": true + } + } + }, + "IntegrationLifecycleRequest": { + "type": "object", + "description": "指定要操作的集成。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "集成 ID。", + "example": 6113996590131 + } + } + }, + "RotateIntegrationKeyResponse": { + "type": "object", + "description": "新生成的集成 Key。", + "required": [ + "integration_key" + ], + "properties": { + "integration_key": { + "type": "string", + "description": "新的集成 Key。旧 Key 立即失效，且该值之后无法再次读取。", + "example": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } } } } diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 36e2edaf..f0894659 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -26197,6 +26197,10 @@ "description": "DingTalk app message template source.", "type": "string" }, + "dingtalk_app_war_room_enabled": { + "type": "boolean", + "description": "Show the Create War Room button on DingTalk app cards." + }, "email": { "description": "Email body template source (Go `html/template` syntax).", "type": "string" @@ -26248,6 +26252,10 @@ "description": "Slack app message template source.", "type": "string" }, + "slack_app_war_room_enabled": { + "type": "boolean", + "description": "Show the Create War Room button on Slack app cards." + }, "sms": { "description": "SMS template source (Go `text/template` syntax).", "type": "string" @@ -26370,6 +26378,10 @@ "description": "DingTalk app message template source.", "type": "string" }, + "dingtalk_app_war_room_enabled": { + "type": "boolean", + "description": "Whether DingTalk app cards show the Create War Room button. Hidden for closed incidents and when the incident has no responders." + }, "email": { "description": "Email body template source (Go `html/template` syntax).", "type": "string" @@ -26420,6 +26432,10 @@ "description": "Slack app message template source.", "type": "string" }, + "slack_app_war_room_enabled": { + "type": "boolean", + "description": "Whether Slack app cards show the Create War Room button. Hidden for closed incidents and when the incident has no responders." + }, "sms": { "description": "SMS template source (Go `text/template` syntax).", "type": "string" @@ -26504,6 +26520,8 @@ "wecom_markdown_v2_enabled", "feishu_app_card_v2_preserve_blank_lines", "feishu_app_war_room_enabled", + "dingtalk_app_war_room_enabled", + "slack_app_war_room_enabled", "dingtalk_app", "wecom_app", "slack_app", @@ -26634,6 +26652,13 @@ "null" ] }, + "dingtalk_app_war_room_enabled": { + "type": [ + "boolean", + "null" + ], + "description": "When set, show or hide the Create War Room button on DingTalk app cards. Omit to keep the existing setting." + }, "email": { "description": "Email body template source (Go `html/template` syntax). Omit to keep the current content; send an empty string to clear it.", "type": [ @@ -26708,6 +26733,13 @@ "null" ] }, + "slack_app_war_room_enabled": { + "type": [ + "boolean", + "null" + ], + "description": "When set, show or hide the Create War Room button on Slack app cards. Omit to keep the existing setting." + }, "sms": { "description": "SMS template source (Go `text/template` syntax). Omit to keep the current content; send an empty string to clear it.", "type": [ @@ -29395,6 +29427,594 @@ ] } } + }, + "IntegrationTypeListRequest": { + "type": "object", + "description": "Filter parameters for listing integration types.", + "properties": { + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Page number, 1-based." + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20, + "description": "Page size. Defaults to 20, maximum 100." + }, + "orderby": { + "type": "string", + "description": "Sort field. When omitted, types are returned in console ranking order.", + "enum": [ + "id", + "created_at", + "updated_at", + "name", + "type" + ] + }, + "category": { + "type": "string", + "description": "Filter by category. Accepts a comma-separated list, for example `event.alert,event.change`." + }, + "asc": { + "type": [ + "boolean", + "null" + ], + "default": true, + "description": "Sort ascending when `true` (the default); descending when `false`." + } + } + }, + "IntegrationTypeItem": { + "type": "object", + "description": "An integration type the account can configure.", + "required": [ + "plugin_type", + "plugin_type_name", + "plugin_type_logo_url", + "category", + "status", + "supports_api_create" + ], + "properties": { + "plugin_type": { + "type": "string", + "description": "Type identifier to pass as `plugin_type` when creating an integration.", + "example": "standard.alert" + }, + "plugin_type_name": { + "type": "string", + "description": "Display name of the type.", + "example": "Standard Alert" + }, + "plugin_type_logo_url": { + "type": "string", + "description": "Logo URL of the type." + }, + "category": { + "type": "string", + "description": "Category the type belongs to.", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ] + }, + "status": { + "type": "string", + "description": "Platform status of the type." + }, + "supports_api_create": { + "type": "boolean", + "description": "Whether `POST /integration/create` accepts this type." + } + } + }, + "ListIntegrationTypesResponse": { + "type": "object", + "description": "A page of integration types.", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "Page number echoed back." + }, + "limit": { + "type": "integer", + "description": "Page size echoed back." + }, + "total": { + "type": "integer", + "format": "int64", + "description": "Total number of matching types." + }, + "items": { + "type": "array", + "description": "Integration types on the current page.", + "items": { + "$ref": "#/components/schemas/IntegrationTypeItem" + } + } + } + }, + "ListIntegrationsRequest": { + "type": "object", + "description": "Filter parameters for listing integrations.", + "properties": { + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Page number, 1-based." + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20, + "description": "Page size. Defaults to 20, maximum 100." + }, + "orderby": { + "type": "string", + "description": "Sort field. Defaults to `created_at`; `plugin_type` is sorted by the underlying plugin.", + "enum": [ + "created_at", + "updated_at", + "name", + "plugin_type", + "status" + ] + }, + "category": { + "type": "string", + "description": "Filter by category. Accepts a comma-separated list." + }, + "type": { + "type": "string", + "description": "Deprecated. Merged into `plugin_type` when both are set." + }, + "plugin_type": { + "type": "string", + "description": "Filter by integration type. Accepts a comma-separated list." + }, + "status": { + "type": "string", + "description": "Filter by status. Accepts a comma-separated list." + }, + "name": { + "type": "string", + "description": "Filter by integration name." + }, + "ref_ids": { + "type": "array", + "description": "Filter by source reference IDs. Each value must start with `c_` (channel), `a_` (account) or `w_`.", + "items": { + "type": "string" + } + }, + "asc": { + "type": "boolean", + "description": "Sort ascending when true, descending when false." + }, + "is_my_team": { + "type": "boolean", + "description": "Limit the result to integrations owned by your teams." + }, + "team_ids": { + "type": "array", + "description": "Filter by team IDs. With `is_my_team`, the values narrow that set further.", + "items": { + "type": "integer", + "format": "int64" + } + } + } + }, + "IntegrationItem": { + "type": "object", + "description": "A configured integration. Timestamps are Unix epoch seconds.", + "required": [ + "integration_id", + "team_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "ref_id", + "created_at", + "updated_at", + "last_time" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "Integration ID." + }, + "team_id": { + "type": "integer", + "format": "int64", + "description": "ID of the team that owns the integration. `0` when it is not assigned to a team." + }, + "plugin_type": { + "type": "string", + "description": "Integration type, for example `standard.alert` or `zabbix.alert`." + }, + "plugin_type_name": { + "type": "string", + "description": "Display name of the integration type, in the language of the request." + }, + "category": { + "type": "string", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ], + "description": "Category the integration belongs to." + }, + "name": { + "type": "string", + "description": "Integration name." + }, + "description": { + "type": "string", + "description": "Free-form description." + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Lifecycle status: `enabled` while the integration accepts events, `disabled` when it is paused." + }, + "ref_id": { + "type": "string", + "description": "Source reference ID: `a_`-prefixed for an account-scoped integration, `c_`-prefixed when it is shared into a channel." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the integration was created." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the integration was last updated." + }, + "last_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds of the most recent event received. `0` when no event has arrived yet." + } + } + }, + "ListIntegrationsResponse": { + "type": "object", + "description": "A page of integrations.", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "Page number echoed back." + }, + "limit": { + "type": "integer", + "description": "Page size echoed back." + }, + "total": { + "type": "integer", + "format": "int64", + "description": "Total number of matching integrations." + }, + "items": { + "type": "array", + "description": "Integrations on the current page.", + "items": { + "$ref": "#/components/schemas/IntegrationItem" + } + } + } + }, + "GetIntegrationRequest": { + "type": "object", + "description": "Identifies one integration.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "Integration ID.", + "example": 6113996590131 + } + } + }, + "IntegrationDetail": { + "type": "object", + "description": "A single integration with its full settings. Timestamps are Unix epoch seconds.", + "required": [ + "integration_id", + "team_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "ref_id", + "created_at", + "updated_at", + "last_time", + "settings" + ], + "properties": { + "integration_id": [ + { + "type": "integer", + "format": "int64", + "description": "Integration ID." + }, + true + ], + "team_id": [ + { + "type": "integer", + "format": "int64", + "description": "ID of the team that owns the integration. `0` when it is not assigned to a team." + }, + true + ], + "plugin_type": [ + { + "type": "string", + "description": "Integration type, for example `standard.alert` or `zabbix.alert`." + }, + true + ], + "plugin_type_name": [ + { + "type": "string", + "description": "Display name of the integration type, in the language of the request." + }, + true + ], + "category": [ + { + "type": "string", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ], + "description": "Category the integration belongs to." + }, + true + ], + "name": [ + { + "type": "string", + "description": "Integration name." + }, + true + ], + "description": [ + { + "type": "string", + "description": "Free-form description." + }, + true + ], + "status": [ + { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Lifecycle status: `enabled` while the integration accepts events, `disabled` when it is paused." + }, + true + ], + "ref_id": [ + { + "type": "string", + "description": "Source reference ID: `a_`-prefixed for an account-scoped integration, `c_`-prefixed when it is shared into a channel." + }, + true + ], + "created_at": [ + { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the integration was created." + }, + true + ], + "updated_at": [ + { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the integration was last updated." + }, + true + ], + "last_time": [ + { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds of the most recent event received. `0` when no event has arrived yet." + }, + true + ], + "settings": { + "type": "object", + "additionalProperties": true, + "description": "Type-specific configuration. Sensitive values (endpoint, headers, secrets, passwords) are returned masked as `******`." + } + } + }, + "CreateIntegrationRequest": { + "type": "object", + "description": "Payload for creating an integration.", + "required": [ + "plugin_type" + ], + "properties": { + "plugin_type": { + "type": "string", + "description": "Integration type. Must be one listed by `POST /integration/type/list` with `supports_api_create: true`.", + "example": "standard.alert" + }, + "name": { + "type": "string", + "minLength": 2, + "maxLength": 49, + "description": "Integration name. 2–49 characters.", + "example": "Prod metrics alerts" + }, + "description": { + "type": "string", + "maxLength": 499, + "description": "Free-form description, at most 499 characters." + }, + "team_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "Owning team ID.", + "example": 1467226103121 + }, + "settings": { + "type": "object", + "description": "Type-specific configuration; the accepted keys depend on `plugin_type`.", + "additionalProperties": true + } + } + }, + "CreateIntegrationResponse": { + "type": "object", + "description": "The created integration and its key.", + "required": [ + "integration_id", + "integration_key" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "ID of the new integration.", + "example": 6113996590131 + }, + "integration_key": { + "type": "string", + "description": "Key used to authenticate inbound pushes to this integration. Returned here only; fetch a new one with `POST /integration/key/rotate`.", + "example": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + }, + "UpdateIntegrationRequest": { + "type": "object", + "description": "Payload for updating an integration. Only the fields you send are changed.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "Integration ID.", + "example": 6113996590131 + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 2, + "maxLength": 49, + "description": "New name, 2–49 characters." + }, + "description": { + "type": [ + "string", + "null" + ], + "maxLength": 499, + "description": "New description, at most 499 characters." + }, + "team_id": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 0, + "description": "New owning team ID; `0` clears the team assignment." + }, + "settings": { + "type": [ + "object", + "null" + ], + "description": "Replacement configuration for the integration type. Sensitive entries left out, or sent back as the masked `******`, keep their stored value.", + "additionalProperties": true + } + } + }, + "IntegrationLifecycleRequest": { + "type": "object", + "description": "Identifies the integration to act on.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "Integration ID.", + "example": 6113996590131 + } + } + }, + "RotateIntegrationKeyResponse": { + "type": "object", + "description": "The newly issued integration key.", + "required": [ + "integration_key" + ], + "properties": { + "integration_key": { + "type": "string", + "description": "The new key. The previous key stops working immediately; this value cannot be read again later.", + "example": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } } }, "securitySchemes": { @@ -60527,6 +61147,745 @@ } } } + }, + "/integration/type/list": { + "post": { + "operationId": "integration-api-read-type-list", + "summary": "List integration types", + "description": "List the integration types the account can configure.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- When `orderby` is omitted, types come back in console ranking order and `p`/`limit` still apply.\n- `supports_api_create` tells you which types `POST /integration/create` accepts.", + "href": "/en/api-reference/on-call/integrations/integration-api-read-type-list", + "metadata": { + "sidebarTitle": "List integration types" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListIntegrationTypesResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 2, + "items": [ + { + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "plugin_type_logo_url": "https://cdn.flashcat.cloud/plugin/standard-alert.svg", + "category": "event.alert", + "status": "enabled", + "supports_api_create": true + }, + { + "plugin_type": "jira.change", + "plugin_type_name": "Jira", + "plugin_type_logo_url": "https://cdn.flashcat.cloud/plugin/jira.svg", + "category": "event.change", + "status": "enabled", + "supports_api_create": true + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationTypeListRequest" + }, + "example": { + "p": 1, + "limit": 20, + "category": "event.alert" + } + } + } + } + } + }, + "/integration/list": { + "post": { + "operationId": "integration-api-read-list", + "summary": "List integrations", + "description": "List the account's alert-source and change-source integrations.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- `orderby` defaults to `created_at`; `plugin_type` is sorted by the underlying plugin.\n- `plugin_type`, `status` and `category` accept comma-separated values; `ref_ids` values must start with `c_`, `a_` or `w_`.\n- With `is_my_team` set, results are limited to your teams and `team_ids` narrows that set further.", + "href": "/en/api-reference/on-call/integrations/integration-api-read-list", + "metadata": { + "sidebarTitle": "List integrations" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListIntegrationsResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 1, + "items": [ + { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775203200, + "last_time": 1775298600 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListIntegrationsRequest" + }, + "example": { + "p": 1, + "limit": 20, + "status": "enabled" + } + } + } + } + } + }, + "/integration/info": { + "post": { + "operationId": "integration-api-read-info", + "summary": "Get integration detail", + "description": "Return one integration, including its settings with sensitive values masked.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- Sensitive settings (endpoint, headers, secrets, passwords) come back masked as `******`.", + "href": "/en/api-reference/on-call/integrations/integration-api-read-info", + "metadata": { + "sidebarTitle": "Get integration detail" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/IntegrationDetail" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775203200, + "last_time": 1775298600, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ], + "labels": { + "source": "prometheus" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetIntegrationRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/create": { + "post": { + "operationId": "integration-api-write-create", + "summary": "Create integration", + "description": "Create an integration for an alert source or change source.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `plugin_type` must be one of the types listed by `POST /integration/type/list` with `supports_api_create: true`; anything else returns `InvalidParameter`.\n- `integration_key` is returned once. Store it at creation time — it is not part of `POST /integration/info`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-create", + "metadata": { + "sidebarTitle": "Create integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CreateIntegrationResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "integration_key": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateIntegrationRequest" + }, + "example": { + "plugin_type": "standard.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "team_id": 1467226103121, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ] + } + } + } + } + } + } + }, + "/integration/update": { + "post": { + "operationId": "integration-api-write-update", + "summary": "Update integration", + "description": "Update an integration's name, description, team, or settings.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields you send are changed; omitted fields keep their current value.\n- `settings` replaces the stored configuration. Sensitive entries left out, or sent back as the masked `******`, keep their stored value.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-update", + "metadata": { + "sidebarTitle": "Update integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/IntegrationDetail" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts (primary)", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775298600, + "last_time": 1775298600, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ], + "labels": { + "source": "prometheus" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateIntegrationRequest" + }, + "example": { + "integration_id": 6113996590131, + "name": "Prod metrics alerts (primary)", + "team_id": 1467226103121 + } + } + } + } + } + }, + "/integration/delete": { + "post": { + "operationId": "integration-api-write-delete", + "summary": "Delete integration", + "description": "Delete an integration that nothing else references.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Deleting an integration that other objects still reference returns HTTP 400 with `error.code` = `ReferenceExist` and `data.refs` listing them.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-delete", + "metadata": { + "sidebarTitle": "Delete integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/enable": { + "post": { + "operationId": "integration-api-write-enable", + "summary": "Enable integration", + "description": "Re-enable a disabled integration so it accepts events again.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enabling an integration resumes its scheduled pull task and heartbeat, and requires the integration type to be available on the current plan.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-enable", + "metadata": { + "sidebarTitle": "Enable integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/disable": { + "post": { + "operationId": "integration-api-write-disable", + "summary": "Disable integration", + "description": "Disable an integration without deleting its configuration.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Disabling stops event ingestion and pauses the scheduled pull task; settings are kept so the integration can be enabled again.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-disable", + "metadata": { + "sidebarTitle": "Disable integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/key/rotate": { + "post": { + "operationId": "integration-api-write-rotate-key", + "summary": "Rotate integration key", + "description": "Issue a new integration key and invalidate the previous one.", + "tags": [ + "On-call/Integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- The previous key stops working immediately, so update the pushing side before rotating.\n- The new key is returned once and cannot be read again later.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", + "href": "/en/api-reference/on-call/integrations/integration-api-write-rotate-key", + "metadata": { + "sidebarTitle": "Rotate integration key" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RotateIntegrationKeyResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_key": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } } }, "security": [ diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 25cbdfae..2695fcbd 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -26197,6 +26197,10 @@ "description": "钉钉应用消息模板源。", "type": "string" }, + "dingtalk_app_war_room_enabled": { + "type": "boolean", + "description": "钉钉应用卡片展示「创建作战室」按钮。" + }, "email": { "description": "邮件正文模板源（Go `html/template` 语法）。", "type": "string" @@ -26248,6 +26252,10 @@ "description": "Slack 应用消息模板源。", "type": "string" }, + "slack_app_war_room_enabled": { + "type": "boolean", + "description": "Slack 应用卡片展示「创建作战室」按钮。" + }, "sms": { "description": "短信模板源（Go `text/template` 语法）。", "type": "string" @@ -26370,6 +26378,10 @@ "description": "钉钉应用消息模板源。", "type": "string" }, + "dingtalk_app_war_room_enabled": { + "type": "boolean", + "description": "钉钉应用卡片是否展示「创建作战室」按钮；故障已关闭或无响应人时不展示。" + }, "email": { "description": "邮件正文模板源（Go `html/template` 语法）。", "type": "string" @@ -26420,6 +26432,10 @@ "description": "Slack 应用消息模板源。", "type": "string" }, + "slack_app_war_room_enabled": { + "type": "boolean", + "description": "Slack 应用卡片是否展示「创建作战室」按钮；故障已关闭或无响应人时不展示。" + }, "sms": { "description": "短信模板源（Go `text/template` 语法）。", "type": "string" @@ -26504,6 +26520,8 @@ "wecom_markdown_v2_enabled", "feishu_app_card_v2_preserve_blank_lines", "feishu_app_war_room_enabled", + "dingtalk_app_war_room_enabled", + "slack_app_war_room_enabled", "dingtalk_app", "wecom_app", "slack_app", @@ -26634,6 +26652,13 @@ "null" ] }, + "dingtalk_app_war_room_enabled": { + "type": [ + "boolean", + "null" + ], + "description": "设置后决定钉钉应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。" + }, "email": { "description": "邮件正文模板源（Go `html/template` 语法）。省略时保持当前内容；传空字符串表示清空。", "type": [ @@ -26708,6 +26733,13 @@ "null" ] }, + "slack_app_war_room_enabled": { + "type": [ + "boolean", + "null" + ], + "description": "设置后决定 Slack 应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。" + }, "sms": { "description": "短信模板源（Go `text/template` 语法）。省略时保持当前内容；传空字符串表示清空。", "type": [ @@ -29395,6 +29427,594 @@ ] } } + }, + "IntegrationTypeListRequest": { + "type": "object", + "description": "查询集成类型列表的过滤参数。", + "properties": { + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "页码，从 1 开始。" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20, + "description": "每页条数，默认 20，最大 100。" + }, + "orderby": { + "type": "string", + "description": "排序字段；不传时按控制台排序返回。", + "enum": [ + "id", + "created_at", + "updated_at", + "name", + "type" + ] + }, + "category": { + "type": "string", + "description": "按分类过滤，支持逗号分隔多个值，例如 `event.alert,event.change`。" + }, + "asc": { + "type": [ + "boolean", + "null" + ], + "default": true, + "description": "`true`（默认）升序，`false` 降序。" + } + } + }, + "IntegrationTypeItem": { + "type": "object", + "description": "账户可配置的一种集成类型。", + "required": [ + "plugin_type", + "plugin_type_name", + "plugin_type_logo_url", + "category", + "status", + "supports_api_create" + ], + "properties": { + "plugin_type": { + "type": "string", + "description": "创建集成时作为 `plugin_type` 传入的类型标识。", + "example": "standard.alert" + }, + "plugin_type_name": { + "type": "string", + "description": "类型显示名。", + "example": "Standard Alert" + }, + "plugin_type_logo_url": { + "type": "string", + "description": "类型 Logo 地址。" + }, + "category": { + "type": "string", + "description": "类型所属分类。", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ] + }, + "status": { + "type": "string", + "description": "该类型在平台侧的状态。" + }, + "supports_api_create": { + "type": "boolean", + "description": "该类型能否通过 `POST /integration/create` 创建。" + } + } + }, + "ListIntegrationTypesResponse": { + "type": "object", + "description": "集成类型列表的一页。", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "当前每页条数。" + }, + "total": { + "type": "integer", + "format": "int64", + "description": "匹配的类型总数。" + }, + "items": { + "type": "array", + "description": "当前页的集成类型。", + "items": { + "$ref": "#/components/schemas/IntegrationTypeItem" + } + } + } + }, + "ListIntegrationsRequest": { + "type": "object", + "description": "查询集成列表的过滤参数。", + "properties": { + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "页码，从 1 开始。" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 20, + "description": "每页条数，默认 20，最大 100。" + }, + "orderby": { + "type": "string", + "description": "排序字段，默认 `created_at`；`plugin_type` 按底层插件排序。", + "enum": [ + "created_at", + "updated_at", + "name", + "plugin_type", + "status" + ] + }, + "category": { + "type": "string", + "description": "按分类过滤，支持逗号分隔多个值。" + }, + "type": { + "type": "string", + "description": "已废弃；与 `plugin_type` 同时传入时会合并生效。" + }, + "plugin_type": { + "type": "string", + "description": "按集成类型过滤，支持逗号分隔多个值。" + }, + "status": { + "type": "string", + "description": "按状态过滤，支持逗号分隔多个值。" + }, + "name": { + "type": "string", + "description": "按集成名称过滤。" + }, + "ref_ids": { + "type": "array", + "description": "按来源引用 ID 过滤；每个值必须以 `c_`（协作空间）、`a_`（账户）或 `w_` 开头。", + "items": { + "type": "string" + } + }, + "asc": { + "type": "boolean", + "description": "`true` 升序，`false` 降序。" + }, + "is_my_team": { + "type": "boolean", + "description": "仅返回你所在团队拥有的集成。" + }, + "team_ids": { + "type": "array", + "description": "按团队 ID 过滤；与 `is_my_team` 同时使用时在其结果内进一步收窄。", + "items": { + "type": "integer", + "format": "int64" + } + } + } + }, + "IntegrationItem": { + "type": "object", + "description": "已配置的集成；时间字段为 Unix 时间戳（秒）。", + "required": [ + "integration_id", + "team_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "ref_id", + "created_at", + "updated_at", + "last_time" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "集成 ID。" + }, + "team_id": { + "type": "integer", + "format": "int64", + "description": "所属团队 ID；未归属团队时为 `0`。" + }, + "plugin_type": { + "type": "string", + "description": "集成类型，例如 `standard.alert`、`zabbix.alert`。" + }, + "plugin_type_name": { + "type": "string", + "description": "集成类型显示名，随请求语言变化。" + }, + "category": { + "type": "string", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ], + "description": "集成所属分类。" + }, + "name": { + "type": "string", + "description": "集成名称。" + }, + "description": { + "type": "string", + "description": "集成描述。" + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "状态：`enabled` 正常接收事件，`disabled` 已暂停。" + }, + "ref_id": { + "type": "string", + "description": "来源引用 ID：`a_` 开头表示账户级集成，集成被共享到协作空间时为 `c_` 开头。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间的 Unix 时间戳（秒）。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最近更新时间的 Unix 时间戳（秒）。" + }, + "last_time": { + "type": "integer", + "format": "int64", + "description": "最近收到事件时间的 Unix 时间戳（秒），尚未收到事件时为 `0`。" + } + } + }, + "ListIntegrationsResponse": { + "type": "object", + "description": "集成列表的一页。", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "当前每页条数。" + }, + "total": { + "type": "integer", + "format": "int64", + "description": "匹配的集成总数。" + }, + "items": { + "type": "array", + "description": "当前页的集成。", + "items": { + "$ref": "#/components/schemas/IntegrationItem" + } + } + } + }, + "GetIntegrationRequest": { + "type": "object", + "description": "指定一个集成。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "集成 ID。", + "example": 6113996590131 + } + } + }, + "IntegrationDetail": { + "type": "object", + "description": "单个集成详情，含完整配置；时间字段为 Unix 时间戳（秒）。", + "required": [ + "integration_id", + "team_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "ref_id", + "created_at", + "updated_at", + "last_time", + "settings" + ], + "properties": { + "integration_id": [ + { + "type": "integer", + "format": "int64", + "description": "集成 ID。" + }, + true + ], + "team_id": [ + { + "type": "integer", + "format": "int64", + "description": "所属团队 ID；未归属团队时为 `0`。" + }, + true + ], + "plugin_type": [ + { + "type": "string", + "description": "集成类型，例如 `standard.alert`、`zabbix.alert`。" + }, + true + ], + "plugin_type_name": [ + { + "type": "string", + "description": "集成类型显示名，随请求语言变化。" + }, + true + ], + "category": [ + { + "type": "string", + "enum": [ + "event.alert", + "event.change", + "im", + "webhook" + ], + "description": "集成所属分类。" + }, + true + ], + "name": [ + { + "type": "string", + "description": "集成名称。" + }, + true + ], + "description": [ + { + "type": "string", + "description": "集成描述。" + }, + true + ], + "status": [ + { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "状态：`enabled` 正常接收事件，`disabled` 已暂停。" + }, + true + ], + "ref_id": [ + { + "type": "string", + "description": "来源引用 ID：`a_` 开头表示账户级集成，集成被共享到协作空间时为 `c_` 开头。" + }, + true + ], + "created_at": [ + { + "type": "integer", + "format": "int64", + "description": "创建时间的 Unix 时间戳（秒）。" + }, + true + ], + "updated_at": [ + { + "type": "integer", + "format": "int64", + "description": "最近更新时间的 Unix 时间戳（秒）。" + }, + true + ], + "last_time": [ + { + "type": "integer", + "format": "int64", + "description": "最近收到事件时间的 Unix 时间戳（秒），尚未收到事件时为 `0`。" + }, + true + ], + "settings": { + "type": "object", + "additionalProperties": true, + "description": "集成类型专属配置；敏感字段（endpoint、headers、密钥、密码）以 `******` 打码返回。" + } + } + }, + "CreateIntegrationRequest": { + "type": "object", + "description": "创建集成的请求体。", + "required": [ + "plugin_type" + ], + "properties": { + "plugin_type": { + "type": "string", + "description": "集成类型，必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型。", + "example": "standard.alert" + }, + "name": { + "type": "string", + "minLength": 2, + "maxLength": 49, + "description": "集成名称，2–49 个字符。", + "example": "Prod metrics alerts" + }, + "description": { + "type": "string", + "maxLength": 499, + "description": "集成描述，最长 499 个字符。" + }, + "team_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "所属团队 ID。", + "example": 1467226103121 + }, + "settings": { + "type": "object", + "description": "集成类型专属配置，可传字段取决于 `plugin_type`。", + "additionalProperties": true + } + } + }, + "CreateIntegrationResponse": { + "type": "object", + "description": "创建结果与集成 Key。", + "required": [ + "integration_id", + "integration_key" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "新建集成的 ID。", + "example": 6113996590131 + }, + "integration_key": { + "type": "string", + "description": "该集成的推送鉴权 Key，仅在此处返回；需要新 Key 请调用 `POST /integration/key/rotate`。", + "example": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + }, + "UpdateIntegrationRequest": { + "type": "object", + "description": "更新集成的请求体；仅发送的字段会被修改。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "集成 ID。", + "example": 6113996590131 + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 2, + "maxLength": 49, + "description": "新的集成名称，2–49 个字符。" + }, + "description": { + "type": [ + "string", + "null" + ], + "maxLength": 499, + "description": "新的集成描述，最长 499 个字符。" + }, + "team_id": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 0, + "description": "新的所属团队 ID；传 `0` 表示清除团队归属。" + }, + "settings": { + "type": [ + "object", + "null" + ], + "description": "替换该集成类型的配置；敏感字段不传、或原样回传 `******`，都会保留已存储的值。", + "additionalProperties": true + } + } + }, + "IntegrationLifecycleRequest": { + "type": "object", + "description": "指定要操作的集成。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "description": "集成 ID。", + "example": 6113996590131 + } + } + }, + "RotateIntegrationKeyResponse": { + "type": "object", + "description": "新生成的集成 Key。", + "required": [ + "integration_key" + ], + "properties": { + "integration_key": { + "type": "string", + "description": "新的集成 Key。旧 Key 立即失效，且该值之后无法再次读取。", + "example": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } } }, "securitySchemes": { @@ -60527,6 +61147,745 @@ } } } + }, + "/integration/type/list": { + "post": { + "operationId": "integration-api-read-type-list", + "summary": "查询集成类型列表", + "description": "查询当前账户可配置的集成类型列表。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。", + "href": "/zh/api-reference/on-call/integrations/integration-api-read-type-list", + "metadata": { + "sidebarTitle": "查询集成类型列表" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListIntegrationTypesResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 2, + "items": [ + { + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "plugin_type_logo_url": "https://cdn.flashcat.cloud/plugin/standard-alert.svg", + "category": "event.alert", + "status": "enabled", + "supports_api_create": true + }, + { + "plugin_type": "jira.change", + "plugin_type_name": "Jira", + "plugin_type_logo_url": "https://cdn.flashcat.cloud/plugin/jira.svg", + "category": "event.change", + "status": "enabled", + "supports_api_create": true + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationTypeListRequest" + }, + "example": { + "p": 1, + "limit": 20, + "category": "event.alert" + } + } + } + } + } + }, + "/integration/list": { + "post": { + "operationId": "integration-api-read-list", + "summary": "查询集成列表", + "description": "查询当前账户的告警源与变更源集成列表。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- `orderby` 默认 `created_at`；`plugin_type` 按底层插件排序。\n- `plugin_type`、`status`、`category` 支持逗号分隔多值；`ref_ids` 每个值必须以 `c_`、`a_` 或 `w_` 开头。\n- 传入 `is_my_team` 时仅返回你所在团队的集成，`team_ids` 会在该范围内进一步收窄。", + "href": "/zh/api-reference/on-call/integrations/integration-api-read-list", + "metadata": { + "sidebarTitle": "查询集成列表" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListIntegrationsResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 1, + "items": [ + { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775203200, + "last_time": 1775298600 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListIntegrationsRequest" + }, + "example": { + "p": 1, + "limit": 20, + "status": "enabled" + } + } + } + } + } + }, + "/integration/info": { + "post": { + "operationId": "integration-api-read-info", + "summary": "查询集成详情", + "description": "查询单个集成详情，敏感配置以打码形式返回。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 敏感配置（endpoint、headers、密钥、密码）均以 `******` 打码返回。", + "href": "/zh/api-reference/on-call/integrations/integration-api-read-info", + "metadata": { + "sidebarTitle": "查询集成详情" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/IntegrationDetail" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775203200, + "last_time": 1775298600, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ], + "labels": { + "source": "prometheus" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetIntegrationRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/create": { + "post": { + "operationId": "integration-api-write-create", + "summary": "创建集成", + "description": "为某个告警源或变更源创建集成。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `plugin_type` 必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型，否则返回 `InvalidParameter`。\n- `integration_key` 仅在创建时返回一次，请及时保存；`POST /integration/info` 不会返回该字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-create", + "metadata": { + "sidebarTitle": "创建集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CreateIntegrationResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "integration_key": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateIntegrationRequest" + }, + "example": { + "plugin_type": "standard.alert", + "name": "Prod metrics alerts", + "description": "Alerts pushed by the production Prometheus stack", + "team_id": 1467226103121, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ] + } + } + } + } + } + } + }, + "/integration/update": { + "post": { + "operationId": "integration-api-write-update", + "summary": "更新集成", + "description": "更新集成的名称、描述、所属团队或配置。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 仅发送的字段会被修改，未发送的字段保持原值。\n- `settings` 会整体替换已存储的配置；敏感字段不传、或原样回传打码值 `******`，都会保留已存储的值。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-update", + "metadata": { + "sidebarTitle": "更新集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/IntegrationDetail" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 6113996590131, + "team_id": 1467226103121, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard Alert", + "category": "event.alert", + "name": "Prod metrics alerts (primary)", + "description": "Alerts pushed by the production Prometheus stack", + "status": "enabled", + "ref_id": "a_6612f0c9e1b7a4d3508f2c6b", + "created_at": 1775116800, + "updated_at": 1775298600, + "last_time": 1775298600, + "settings": { + "severity_mapping": [ + { + "P1": "Critical" + } + ], + "labels": { + "source": "prometheus" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateIntegrationRequest" + }, + "example": { + "integration_id": 6113996590131, + "name": "Prod metrics alerts (primary)", + "team_id": 1467226103121 + } + } + } + } + } + }, + "/integration/delete": { + "post": { + "operationId": "integration-api-write-delete", + "summary": "删除集成", + "description": "删除指定的集成。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 若该集成仍被其他对象引用，删除会返回 HTTP 400，`error.code` 为 `ReferenceExist`，`data.refs` 列出引用方。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-delete", + "metadata": { + "sidebarTitle": "删除集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/enable": { + "post": { + "operationId": "integration-api-write-enable", + "summary": "启用集成", + "description": "重新启用已禁用的集成，恢复接收事件。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 启用会恢复该集成的拉取任务与心跳，并要求当前套餐包含该集成类型。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-enable", + "metadata": { + "sidebarTitle": "启用集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/disable": { + "post": { + "operationId": "integration-api-write-disable", + "summary": "禁用集成", + "description": "禁用集成，但保留其配置。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 禁用后停止接收事件并暂停定时拉取任务，配置保留，可再次启用。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-disable", + "metadata": { + "sidebarTitle": "禁用集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EmptyObject" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/integration/key/rotate": { + "post": { + "operationId": "integration-api-write-rotate-key", + "summary": "轮换集成 Key", + "description": "生成新的集成 Key，并使旧 Key 立即失效。", + "tags": [ + "On-call/集成中心" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 旧 Key 会立即失效，请先更新推送侧再轮换。\n- 新 Key 只返回一次，之后无法再次读取。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", + "href": "/zh/api-reference/on-call/integrations/integration-api-write-rotate-key", + "metadata": { + "sidebarTitle": "轮换集成 Key" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RotateIntegrationKeyResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_key": "9f2c7d1b45a86e30f7b1c9d4a2e65738123" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } } }, "security": [ diff --git a/docs.json b/docs.json index f1aaa570..02c39983 100644 --- a/docs.json +++ b/docs.json @@ -2281,7 +2281,16 @@ "pages": [ "POST /webhook/history/list", "POST /webhook/history/detail", - "POST /datasource/im/person/try-link" + "POST /datasource/im/person/try-link", + "POST /integration/type/list", + "POST /integration/list", + "POST /integration/info", + "POST /integration/create", + "POST /integration/update", + "POST /integration/delete", + "POST /integration/enable", + "POST /integration/disable", + "POST /integration/key/rotate" ] }, { @@ -3668,7 +3677,16 @@ "pages": [ "POST /webhook/history/list", "POST /webhook/history/detail", - "POST /datasource/im/person/try-link" + "POST /datasource/im/person/try-link", + "POST /integration/type/list", + "POST /integration/list", + "POST /integration/info", + "POST /integration/create", + "POST /integration/update", + "POST /integration/delete", + "POST /integration/enable", + "POST /integration/disable", + "POST /integration/key/rotate" ] }, { diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index 54265f2f..f09a701f 100644 --- a/en/openapi/api-catalog.mdx +++ b/en/openapi/api-catalog.mdx @@ -3,13 +3,13 @@ title: "API Catalog" description: "Complete list of Flashduty Open API endpoints, organized by product module with links to detailed documentation" --- -Flashduty Open API provides **338** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details. +Flashduty Open API provides **347** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details. All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated via APP Key through query string. - + ### Incidents @@ -134,6 +134,15 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi | POST | [`/webhook/history/list`](/en/api-reference/on-call/integrations/webhook-history-list) | List webhook delivery history | | POST | [`/webhook/history/detail`](/en/api-reference/on-call/integrations/webhook-history-detail) | Get webhook delivery detail | | POST | [`/datasource/im/person/try-link`](/en/api-reference/on-call/integrations/datasource-im-person-try-link) | Attempt IM person linking | +| POST | [`/integration/type/list`](/en/api-reference/on-call/integrations/integration-api-read-type-list) | List integration types | +| POST | [`/integration/list`](/en/api-reference/on-call/integrations/integration-api-read-list) | List integrations | +| POST | [`/integration/info`](/en/api-reference/on-call/integrations/integration-api-read-info) | Get integration detail | +| POST | [`/integration/create`](/en/api-reference/on-call/integrations/integration-api-write-create) | Create integration | +| POST | [`/integration/update`](/en/api-reference/on-call/integrations/integration-api-write-update) | Update integration | +| POST | [`/integration/delete`](/en/api-reference/on-call/integrations/integration-api-write-delete) | Delete integration | +| POST | [`/integration/enable`](/en/api-reference/on-call/integrations/integration-api-write-enable) | Enable integration | +| POST | [`/integration/disable`](/en/api-reference/on-call/integrations/integration-api-write-disable) | Disable integration | +| POST | [`/integration/key/rotate`](/en/api-reference/on-call/integrations/integration-api-write-rotate-key) | Rotate integration key | ### Schedules diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 2b8550a7..a0e82872 100644 --- a/zh/openapi/api-catalog.mdx +++ b/zh/openapi/api-catalog.mdx @@ -3,13 +3,13 @@ title: "API 目录" description: "Flashduty Open API 接口完整列表，按产品模块组织并链接到详细文档" --- -Flashduty Open API 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 +Flashduty Open API 提供 **347** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 所有接口 URL 均以 `https://api.flashcat.cloud` 为 base，通过 query string 中的 APP Key 认证。 - + ### 故障管理 @@ -134,6 +134,15 @@ Flashduty Open API 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、 | POST | [`/webhook/history/list`](/zh/api-reference/on-call/integrations/webhook-history-list) | 查询 Webhook 推送历史 | | POST | [`/webhook/history/detail`](/zh/api-reference/on-call/integrations/webhook-history-detail) | 获取 Webhook 推送详情 | | POST | [`/datasource/im/person/try-link`](/zh/api-reference/on-call/integrations/datasource-im-person-try-link) | 尝试关联 IM 人员 | +| POST | [`/integration/type/list`](/zh/api-reference/on-call/integrations/integration-api-read-type-list) | 查询集成类型列表 | +| POST | [`/integration/list`](/zh/api-reference/on-call/integrations/integration-api-read-list) | 查询集成列表 | +| POST | [`/integration/info`](/zh/api-reference/on-call/integrations/integration-api-read-info) | 查询集成详情 | +| POST | [`/integration/create`](/zh/api-reference/on-call/integrations/integration-api-write-create) | 创建集成 | +| POST | [`/integration/update`](/zh/api-reference/on-call/integrations/integration-api-write-update) | 更新集成 | +| POST | [`/integration/delete`](/zh/api-reference/on-call/integrations/integration-api-write-delete) | 删除集成 | +| POST | [`/integration/enable`](/zh/api-reference/on-call/integrations/integration-api-write-enable) | 启用集成 | +| POST | [`/integration/disable`](/zh/api-reference/on-call/integrations/integration-api-write-disable) | 禁用集成 | +| POST | [`/integration/key/rotate`](/zh/api-reference/on-call/integrations/integration-api-write-rotate-key) | 轮换集成 Key | ### 值班排班