From a80c48590c938dbec3c221dcb5ab36a922270ac7 Mon Sep 17 00:00:00 2001 From: alick-liming Date: Wed, 28 Oct 2026 13:16:57 +0800 Subject: [PATCH] docs: document dedicated integration APIs --- api-reference/on-call.openapi.en.json | 1153 +++++++++++++++++++++++- api-reference/on-call.openapi.zh.json | 1153 +++++++++++++++++++++++- api-reference/openapi.en.json | 1157 ++++++++++++++++++++++++- api-reference/openapi.zh.json | 1151 +++++++++++++++++++++++- docs.json | 108 ++- en/openapi/api-catalog.mdx | 48 +- zh/openapi/api-catalog.mdx | 48 +- 7 files changed, 4755 insertions(+), 63 deletions(-) diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index c6fdcc70a..abad227ab 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -68,6 +68,10 @@ { "name": "On-call/Changes", "description": "" + }, + { + "name": "On-call/Dedicated integrations", + "description": "Manage alert integrations owned by individual channels." } ], "paths": { @@ -17421,7 +17425,7 @@ "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.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- Public and dedicated integrations share this type catalog; it returns no configured integration instances, settings, or keys.\n- The App Key's `api_scopes` must allow `integration.api:read:typeList`; `channel.integration` scopes do not include this endpoint.\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.\n- `category` values are not validated; an unknown value returns an empty list.", "href": "/en/api-reference/on-call/integrations/integration-api-read-type-list", "metadata": { "sidebarTitle": "List integration types" @@ -17482,6 +17486,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -18165,10 +18172,837 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IntegrationLifecycleRequest" + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/channel/integration/list": { + "post": { + "operationId": "channel-integration-read-list", + "summary": "List dedicated integrations", + "description": "List the dedicated integrations owned by one channel.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- Private channels also require the account owner, an Admin, the channel creator, or membership in its owning or managing teams; public channels still require the API permission above.\n- `channel_id` is required; `p` defaults to `1` and `limit` defaults to `100`, with a maximum of `100`.\n- `plugin_type` and `status` each accept one value.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-read-list", + "metadata": { + "sidebarTitle": "List dedicated integrations" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationListResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 1, + "items": [ + { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationListRequest" + }, + "example": { + "channel_id": 20001, + "p": 1, + "limit": 20 + } + } + } + } + } + }, + "/channel/integration/info": { + "post": { + "operationId": "channel-integration-read-info", + "summary": "Get dedicated integration detail", + "description": "Get one channel-owned integration, including its integration key and masked settings.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- Private channels also require the account owner, an Admin, the channel creator, or membership in its owning or managing teams; public channels still require the API permission above.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-read-info", + "metadata": { + "sidebarTitle": "Get dedicated integration detail" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/create": { + "post": { + "operationId": "channel-integration-write-create", + "summary": "Create dedicated integration", + "description": "Create a dedicated alert integration for an enabled channel.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- The channel must be enabled; the integration type must be enabled, belong to `event.alert`, and be supported by your subscription.\n- If you know the `plugin_type`, create the integration directly without querying types first. You can optionally query `POST /integration/type/list` for alert types with Channels Read, Channels Manage, or Integrations Read; the App Key's `api_scopes` must also allow `integration.api:read:typeList`.\n- An omitted `name` uses the integration type default; an omitted `integration_key` is generated. A supplied key must have 35 characters, match the account suffix, and not be used by another integration.\n- Success returns `integration_id` and `integration_key`; use that `integration_id` for subsequent operations.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-create", + "metadata": { + "sidebarTitle": "Create dedicated integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationCreateResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "integration_key": "0123456789abcdef0123456789abcdef100" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationCreateRequest" + }, + "example": { + "channel_id": 20001, + "plugin_type": "standard.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "settings": {} + } + } + } + } + } + }, + "/channel/integration/update": { + "post": { + "operationId": "channel-integration-write-update", + "summary": "Update dedicated integration", + "description": "Update the name, description, or settings of a dedicated integration.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.\n- Only supplied fields change; omitted or `null` fields retain their value. Send `description: \"\"` to clear the description.\n- Supplied `settings` follow the integration type configuration rules; masked or omitted secret fields retain their stored value. Retaining a secret does not allow changing its corresponding destination.\n- This endpoint does not change the channel, integration type, or integration key.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-update", + "metadata": { + "sidebarTitle": "Update dedicated integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments production alerts", + "description": "", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationUpdateRequest" + }, + "example": { + "integration_id": 10001, + "name": "Payments production alerts", + "description": "" + } + } + } + } + } + }, + "/channel/integration/delete": { + "post": { + "operationId": "channel-integration-write-delete", + "summary": "Delete dedicated integration", + "description": "Delete a dedicated integration after its references have been removed.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- Existing references return HTTP 400 with `ReferenceExist` and `data.refs` listing them; remove those references before deleting.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-delete", + "metadata": { + "sidebarTitle": "Delete dedicated 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": { + "description": "Invalid parameters or an existing reference; ReferenceExist includes data.refs.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorResponse" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "description": "Resources that prevent deletion.", + "properties": { + "refs": { + "type": "array", + "description": "Referencing resources; remove their references before retrying.", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "description": "Referencing resource kind." + }, + "name": { + "type": "string", + "description": "Referencing resource name." + }, + "href": { + "type": "string", + "description": "Console link to the referencing resource." + } + } + } + } + } + } + } + } + ] + }, + "examples": { + "missingParameter": { + "value": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "InvalidParameter", + "message": "The specified parameter is not valid." + } + } + } + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "ReferenceExist", + "message": "There still are associated resources, deletion is blocked." + }, + "data": { + "refs": [ + { + "kind": "channel", + "name": "Payments", + "href": "https://console.flashcat.cloud/channel/20001" + } + ] + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/enable": { + "post": { + "operationId": "channel-integration-write-enable", + "summary": "Enable dedicated integration", + "description": "Enable a dedicated integration so it can receive alerts.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- After permission and subscription checks pass, repeating an operation when the target state is already set succeeds.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-enable", + "metadata": { + "sidebarTitle": "Enable dedicated 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" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/disable": { + "post": { + "operationId": "channel-integration-write-disable", + "summary": "Disable dedicated integration", + "description": "Disable a dedicated integration to pause alert ingestion.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- After permission checks pass, repeating this operation when the integration is already disabled succeeds.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-disable", + "metadata": { + "sidebarTitle": "Disable dedicated 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" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/key/rotate": { + "post": { + "operationId": "channel-integration-write-rotate-key", + "summary": "Rotate dedicated integration key", + "description": "Issue a new dedicated integration key and invalidate the previous key.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- After the previous key is invalidated, senders using it can no longer ingest alerts; configure the returned key in the corresponding monitoring system.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-rotate-key", + "metadata": { + "sidebarTitle": "Rotate dedicated 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": "0123456789abcdef0123456789abcdef100" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" }, "example": { - "integration_id": 6113996590131 + "integration_id": 10001 } } } @@ -35078,10 +35912,321 @@ "properties": { "integration_key": { "type": "string", - "description": "New integration key; the previous key stops working immediately. Also readable from `/integration/list` and `/integration/info`.", + "description": "New integration key; the previous key stops working immediately.", "example": "0123456789abcdef0123456789abcdef100" } } + }, + "ChannelIntegrationItem": { + "type": "object", + "description": "A channel-owned dedicated integration, with its complete key and masked settings.", + "required": [ + "integration_id", + "channel_id", + "integration_key", + "exclusive_data_source_id", + "plugin_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "created_at", + "updated_at", + "last_time", + "last_source_time", + "settings" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "Dedicated integration ID; use this ID for subsequent API calls." + }, + "channel_id": { + "type": "integer", + "format": "int64", + "description": "ID of the channel that owns the dedicated integration." + }, + "integration_key": { + "type": "string", + "description": "Complete integration key for alert ingestion; separate from the management App Key." + }, + "exclusive_data_source_id": { + "type": "integer", + "format": "int64", + "description": "Compatibility identifier for earlier integrations; `0` when absent. Use `integration_id` for this API group." + }, + "plugin_id": { + "type": "integer", + "format": "int64", + "description": "Numeric integration type ID. Create uses the string `plugin_type` instead." + }, + "plugin_type": { + "type": "string", + "description": "Integration type identifier, such as `standard.alert`." + }, + "plugin_type_name": { + "type": "string", + "description": "Integration type display name, localized to the request language." + }, + "category": { + "type": "string", + "description": "Integration category; dedicated integration creation accepts `event.alert` alert integrations." + }, + "name": { + "type": "string", + "description": "Integration name." + }, + "description": { + "type": "string", + "description": "Integration description; empty when unset." + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Lifecycle status: `enabled` accepts alerts; `disabled` pauses ingestion." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation time as a Unix timestamp in seconds." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update time as a Unix timestamp in seconds." + }, + "last_time": { + "type": "integer", + "format": "int64", + "description": "Most recent received-event time as a Unix timestamp in seconds; `0` when no event has arrived." + }, + "last_source_time": { + "type": "integer", + "format": "int64", + "description": "Source time of the most recent event as a Unix timestamp in seconds; `0` when unavailable." + }, + "settings": { + "type": "object", + "additionalProperties": true, + "description": "Integration-type-specific configuration; saved secret values in responses are masked as `******`." + } + } + }, + "ChannelIntegrationIDRequest": { + "type": "object", + "description": "Identifies one dedicated integration.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 10001, + "description": "Dedicated integration ID returned by create, list, or info. Public integration IDs are not accepted." + } + } + }, + "ChannelIntegrationUpdateRequest": { + "type": "object", + "description": "Partial update of a dedicated integration; omitted or null fields keep their value.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 10001, + "description": "Dedicated integration ID returned by create, list, or info. Public integration IDs are not accepted." + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 2, + "maxLength": 49, + "description": "New name, 2–49 characters; omitted or null keeps the stored name." + }, + "description": { + "type": [ + "string", + "null" + ], + "maxLength": 499, + "description": "New description, at most 499 characters; empty clears it, omitted or null keeps it." + }, + "settings": { + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "Replacement type-specific configuration. Omitted or null keeps it; masked or omitted secret fields retain their stored value." + } + } + }, + "ChannelIntegrationListResponse": { + "type": "object", + "description": "One page of dedicated integrations.", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "Returned page number." + }, + "limit": { + "type": "integer", + "description": "Returned page size." + }, + "total": { + "type": "integer", + "description": "Total number of matching dedicated integrations." + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + }, + "description": "Dedicated integrations on this page." + } + } + }, + "ChannelIntegrationCreateRequest": { + "type": "object", + "description": "Creates a dedicated integration in an enabled channel.", + "required": [ + "channel_id", + "plugin_type" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 20001, + "description": "Target channel ID; the channel must be enabled." + }, + "plugin_type": { + "type": "string", + "description": "Enabled alert integration type identifier, such as `standard.alert`." + }, + "name": { + "type": "string", + "maxLength": 49, + "description": "Integration name, 2–49 characters when supplied; omitted or empty uses the integration type default.", + "anyOf": [ + { + "maxLength": 0 + }, + { + "minLength": 2 + } + ] + }, + "description": { + "type": "string", + "maxLength": 499, + "description": "Description, at most 499 characters." + }, + "integration_key": { + "type": "string", + "maxLength": 35, + "description": "Optional supplied integration key. A non-empty value must have 35 characters, match the account suffix, and be unique.", + "anyOf": [ + { + "maxLength": 0 + }, + { + "minLength": 35 + } + ] + }, + "settings": { + "type": "object", + "additionalProperties": true, + "description": "Integration-type-specific configuration; saved secret values in responses are masked as `******`." + } + } + }, + "ChannelIntegrationListRequest": { + "type": "object", + "description": "Filters and pagination for one channel's dedicated integrations.", + "required": [ + "channel_id" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 20001, + "description": "Channel ID to list dedicated integrations for." + }, + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Page number, starting at 1." + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 100, + "description": "Number of items per page, at most 100." + }, + "name": { + "type": "string", + "maxLength": 49, + "description": "Filter by integration name." + }, + "plugin_type": { + "type": "string", + "description": "Filter by one integration type." + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Filter by `enabled` integrations that accept alerts or `disabled` integrations that pause ingestion." + } + } + }, + "ChannelIntegrationCreateResponse": { + "type": "object", + "description": "The created dedicated integration and its ingestion key.", + "required": [ + "integration_id", + "integration_key" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "Created dedicated integration ID." + }, + "integration_key": { + "type": "string", + "description": "Integration key for alert ingestion." + } + } } } } diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index 3cc970abc..7d78d14d6 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -68,6 +68,10 @@ { "name": "On-call/变更管理", "description": "" + }, + { + "name": "On-call/专属集成", + "description": "管理各协作空间的专属告警集成。" } ], "paths": { @@ -17421,7 +17425,7 @@ "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` 创建。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 公共集成和专属集成共用此类型目录，不返回已配置的集成实例、配置或 Key。\n- App Key 的 `api_scopes` 须允许 `integration.api:read:typeList`；`channel.integration` 范围不包含此接口。\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。\n- `category` 取值不做校验，未知值会返回空列表。", "href": "/zh/api-reference/on-call/integrations/integration-api-read-type-list", "metadata": { "sidebarTitle": "查询集成类型列表" @@ -17482,6 +17486,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -18165,10 +18172,837 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IntegrationLifecycleRequest" + "$ref": "#/components/schemas/IntegrationLifecycleRequest" + }, + "example": { + "integration_id": 6113996590131 + } + } + } + } + } + }, + "/channel/integration/list": { + "post": { + "operationId": "channel-integration-read-list", + "summary": "查询专属集成列表", + "description": "查询指定协作空间的专属集成。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 查看私有空间还要求您是账户所有者、Admin、空间创建者，或所属团队、管理团队的成员；公开空间仍需上述接口权限。\n- `channel_id` 必填；`p` 默认 `1`，`limit` 默认 `100`，最多 `100`。\n- `plugin_type` 和 `status` 各接受单个值。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-list", + "metadata": { + "sidebarTitle": "查询专属集成列表" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationListResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 1, + "items": [ + { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationListRequest" + }, + "example": { + "channel_id": 20001, + "p": 1, + "limit": 20 + } + } + } + } + } + }, + "/channel/integration/info": { + "post": { + "operationId": "channel-integration-read-info", + "summary": "查看专属集成详情", + "description": "查看专属集成详情、集成 Key 和脱敏配置。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 查看私有空间还要求您是账户所有者、Admin、空间创建者，或所属团队、管理团队的成员；公开空间仍需上述接口权限。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-info", + "metadata": { + "sidebarTitle": "查看专属集成详情" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/create": { + "post": { + "operationId": "channel-integration-write-create", + "summary": "创建专属集成", + "description": "为已启用的协作空间创建专属告警集成。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 目标空间必须已启用；集成类型须已启用、属于 `event.alert`，且您的订阅支持该类型。\n- 已知 `plugin_type` 时可直接创建，无需先查询类型。也可选用 `POST /integration/type/list` 查询告警类型；该接口支持协作空间查看、管理或集成中心查看权限，App Key 的 `api_scopes` 还须允许 `integration.api:read:typeList`。\n- 省略 `name` 时使用集成类型的默认名称；省略 `integration_key` 时自动生成。自带 Key 须为 35 个字符、匹配账户后缀，且未被其他集成使用。\n- 成功后返回 `integration_id` 和 `integration_key`；后续操作使用返回的 `integration_id`。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-create", + "metadata": { + "sidebarTitle": "创建专属集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationCreateResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "integration_key": "0123456789abcdef0123456789abcdef100" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationCreateRequest" + }, + "example": { + "channel_id": 20001, + "plugin_type": "standard.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "settings": {} + } + } + } + } + } + }, + "/channel/integration/update": { + "post": { + "operationId": "channel-integration-write-update", + "summary": "更新专属集成", + "description": "更新专属集成的名称、描述或配置。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。\n- 仅更新传入的字段；省略或设为 `null` 时保留原值。`description: \"\"` 清空描述。\n- 传入 `settings` 时按该类型的配置规则保存；已脱敏或省略的密钥类字段保留原值。保留原密钥时，不能同时更改对应的目标地址。\n- 此接口不更改所属空间、集成类型或集成 Key。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-update", + "metadata": { + "sidebarTitle": "更新专属集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments production alerts", + "description": "", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationUpdateRequest" + }, + "example": { + "integration_id": 10001, + "name": "Payments production alerts", + "description": "" + } + } + } + } + } + }, + "/channel/integration/delete": { + "post": { + "operationId": "channel-integration-write-delete", + "summary": "删除专属集成", + "description": "删除已解除资源引用的专属集成。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 存在其他资源引用时，返回 HTTP 400、`ReferenceExist`，并在 `data.refs` 中列出引用；解除引用后再删除。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-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": { + "description": "参数无效或存在资源引用；ReferenceExist 错误包含 data.refs。", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorResponse" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "description": "阻止删除的引用资源。", + "properties": { + "refs": { + "type": "array", + "description": "引用当前集成的资源；解除引用后再重试。", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "description": "引用资源的类型。" + }, + "name": { + "type": "string", + "description": "引用资源的名称。" + }, + "href": { + "type": "string", + "description": "引用资源的控制台链接。" + } + } + } + } + } + } + } + } + ] + }, + "examples": { + "missingParameter": { + "value": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "InvalidParameter", + "message": "The specified parameter is not valid." + } + } + } + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "ReferenceExist", + "message": "There still are associated resources, deletion is blocked." + }, + "data": { + "refs": [ + { + "kind": "channel", + "name": "Payments", + "href": "https://console.flashcat.cloud/channel/20001" + } + ] + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/enable": { + "post": { + "operationId": "channel-integration-write-enable", + "summary": "启用专属集成", + "description": "启用专属集成，使其接收告警。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 权限及订阅校验通过后，已处于目标状态时重复调用成功返回。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-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" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/disable": { + "post": { + "operationId": "channel-integration-write-disable", + "summary": "禁用专属集成", + "description": "禁用专属集成，暂停接收告警。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 权限校验通过后，已处于禁用状态时重复调用成功返回。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-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" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/key/rotate": { + "post": { + "operationId": "channel-integration-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- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 原 Key 失效后，仍使用原 Key 的推送端将无法接入；请将返回的新 Key 配置到对应监控系统。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-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": "0123456789abcdef0123456789abcdef100" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" }, "example": { - "integration_id": 6113996590131 + "integration_id": 10001 } } } @@ -35078,10 +35912,321 @@ "properties": { "integration_key": { "type": "string", - "description": "新的集成 Key，旧 Key 立即失效；新 Key 也可通过 `/integration/list` 和 `/integration/info` 查询。", + "description": "新的集成 Key；原 Key 立即失效。", "example": "0123456789abcdef0123456789abcdef100" } } + }, + "ChannelIntegrationItem": { + "type": "object", + "description": "协作空间专属集成，包含完整集成 Key 和脱敏配置。", + "required": [ + "integration_id", + "channel_id", + "integration_key", + "exclusive_data_source_id", + "plugin_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "created_at", + "updated_at", + "last_time", + "last_source_time", + "settings" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "专属集成 ID，后续接口调用使用此 ID。" + }, + "channel_id": { + "type": "integer", + "format": "int64", + "description": "专属集成所属的协作空间 ID。" + }, + "integration_key": { + "type": "string", + "description": "用于告警接入的完整集成 Key，与管理接口的 App Key 不同。" + }, + "exclusive_data_source_id": { + "type": "integer", + "format": "int64", + "description": "早期集成的兼容标识，无关联值时为 `0`；本组接口统一使用 `integration_id`。" + }, + "plugin_id": { + "type": "integer", + "format": "int64", + "description": "集成类型的数字 ID；创建时使用字符串 `plugin_type`。" + }, + "plugin_type": { + "type": "string", + "description": "集成类型标识，例如 `standard.alert`。" + }, + "plugin_type_name": { + "type": "string", + "description": "按请求语言返回的集成类型显示名称。" + }, + "category": { + "type": "string", + "description": "集成分类；专属集成创建接口接受 `event.alert` 告警集成。" + }, + "name": { + "type": "string", + "description": "集成名称。" + }, + "description": { + "type": "string", + "description": "集成描述；未设置时为空字符串。" + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "集成状态：`enabled` 表示接收告警，`disabled` 表示暂停接入。" + }, + "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`。" + }, + "last_source_time": { + "type": "integer", + "format": "int64", + "description": "最近事件的来源时间，Unix 时间戳，单位为秒；无可用值时为 `0`。" + }, + "settings": { + "type": "object", + "additionalProperties": true, + "description": "集成类型对应的配置；响应中已保存的密钥类值以 `******` 返回。" + } + } + }, + "ChannelIntegrationIDRequest": { + "type": "object", + "description": "标识一条专属集成。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 10001, + "description": "创建、列表或详情接口返回的专属集成 ID；不接受公共集成 ID。" + } + } + }, + "ChannelIntegrationUpdateRequest": { + "type": "object", + "description": "专属集成的部分更新；省略或为 null 的字段保留原值。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 10001, + "description": "创建、列表或详情接口返回的专属集成 ID；不接受公共集成 ID。" + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 2, + "maxLength": 49, + "description": "新名称，2–49 个字符；省略或为 null 时保留原名称。" + }, + "description": { + "type": [ + "string", + "null" + ], + "maxLength": 499, + "description": "新描述，最多 499 个字符；空字符串清空，省略或为 null 时保留。" + }, + "settings": { + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "按集成类型替换配置；省略或为 null 时保留，已脱敏或省略的密钥类字段保留原值。" + } + } + }, + "ChannelIntegrationListResponse": { + "type": "object", + "description": "一页专属集成结果。", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "当前每页条数。" + }, + "total": { + "type": "integer", + "description": "符合条件的专属集成总数。" + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + }, + "description": "当前页的专属集成。" + } + } + }, + "ChannelIntegrationCreateRequest": { + "type": "object", + "description": "在已启用的协作空间创建专属集成。", + "required": [ + "channel_id", + "plugin_type" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 20001, + "description": "目标协作空间 ID，空间须已启用。" + }, + "plugin_type": { + "type": "string", + "description": "已启用的告警集成类型标识，例如 `standard.alert`。" + }, + "name": { + "type": "string", + "maxLength": 49, + "description": "集成名称，提供时为 2–49 个字符；省略或为空时使用集成类型的默认名称。", + "anyOf": [ + { + "maxLength": 0 + }, + { + "minLength": 2 + } + ] + }, + "description": { + "type": "string", + "maxLength": 499, + "description": "集成描述，最多 499 个字符。" + }, + "integration_key": { + "type": "string", + "maxLength": 35, + "description": "可选的自带集成 Key；非空时须为 35 个字符、匹配账户后缀，且未被其他集成使用。", + "anyOf": [ + { + "maxLength": 0 + }, + { + "minLength": 35 + } + ] + }, + "settings": { + "type": "object", + "additionalProperties": true, + "description": "集成类型对应的配置；响应中已保存的密钥类值以 `******` 返回。" + } + } + }, + "ChannelIntegrationListRequest": { + "type": "object", + "description": "指定协作空间的专属集成查询条件。", + "required": [ + "channel_id" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 20001, + "description": "要查询专属集成的协作空间 ID。" + }, + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "页码，从 1 开始。" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 100, + "description": "每页条数，最多 100 条。" + }, + "name": { + "type": "string", + "maxLength": 49, + "description": "按集成名称过滤。" + }, + "plugin_type": { + "type": "string", + "description": "按单个集成类型过滤。" + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "按状态过滤：`enabled` 表示接收告警，`disabled` 表示暂停接入。" + } + } + }, + "ChannelIntegrationCreateResponse": { + "type": "object", + "description": "创建完成的专属集成及其接入 Key。", + "required": [ + "integration_id", + "integration_key" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "创建完成的专属集成 ID。" + }, + "integration_key": { + "type": "string", + "description": "用于告警接入的集成 Key。" + } + } } } } diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 1fcc8cc08..57b74dfcd 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -30083,10 +30083,321 @@ "properties": { "integration_key": { "type": "string", - "description": "New integration key; the previous key stops working immediately. Also readable from `/integration/list` and `/integration/info`.", + "description": "New integration key; the previous key stops working immediately.", "example": "0123456789abcdef0123456789abcdef100" } } + }, + "ChannelIntegrationItem": { + "type": "object", + "description": "A channel-owned dedicated integration, with its complete key and masked settings.", + "required": [ + "integration_id", + "channel_id", + "integration_key", + "exclusive_data_source_id", + "plugin_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "created_at", + "updated_at", + "last_time", + "last_source_time", + "settings" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "Dedicated integration ID; use this ID for subsequent API calls." + }, + "channel_id": { + "type": "integer", + "format": "int64", + "description": "ID of the channel that owns the dedicated integration." + }, + "integration_key": { + "type": "string", + "description": "Complete integration key for alert ingestion; separate from the management App Key." + }, + "exclusive_data_source_id": { + "type": "integer", + "format": "int64", + "description": "Compatibility identifier for earlier integrations; `0` when absent. Use `integration_id` for this API group." + }, + "plugin_id": { + "type": "integer", + "format": "int64", + "description": "Numeric integration type ID. Create uses the string `plugin_type` instead." + }, + "plugin_type": { + "type": "string", + "description": "Integration type identifier, such as `standard.alert`." + }, + "plugin_type_name": { + "type": "string", + "description": "Integration type display name, localized to the request language." + }, + "category": { + "type": "string", + "description": "Integration category; dedicated integration creation accepts `event.alert` alert integrations." + }, + "name": { + "type": "string", + "description": "Integration name." + }, + "description": { + "type": "string", + "description": "Integration description; empty when unset." + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Lifecycle status: `enabled` accepts alerts; `disabled` pauses ingestion." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation time as a Unix timestamp in seconds." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update time as a Unix timestamp in seconds." + }, + "last_time": { + "type": "integer", + "format": "int64", + "description": "Most recent received-event time as a Unix timestamp in seconds; `0` when no event has arrived." + }, + "last_source_time": { + "type": "integer", + "format": "int64", + "description": "Source time of the most recent event as a Unix timestamp in seconds; `0` when unavailable." + }, + "settings": { + "type": "object", + "additionalProperties": true, + "description": "Integration-type-specific configuration; saved secret values in responses are masked as `******`." + } + } + }, + "ChannelIntegrationIDRequest": { + "type": "object", + "description": "Identifies one dedicated integration.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 10001, + "description": "Dedicated integration ID returned by create, list, or info. Public integration IDs are not accepted." + } + } + }, + "ChannelIntegrationUpdateRequest": { + "type": "object", + "description": "Partial update of a dedicated integration; omitted or null fields keep their value.", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 10001, + "description": "Dedicated integration ID returned by create, list, or info. Public integration IDs are not accepted." + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 2, + "maxLength": 49, + "description": "New name, 2–49 characters; omitted or null keeps the stored name." + }, + "description": { + "type": [ + "string", + "null" + ], + "maxLength": 499, + "description": "New description, at most 499 characters; empty clears it, omitted or null keeps it." + }, + "settings": { + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "Replacement type-specific configuration. Omitted or null keeps it; masked or omitted secret fields retain their stored value." + } + } + }, + "ChannelIntegrationListResponse": { + "type": "object", + "description": "One page of dedicated integrations.", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "Returned page number." + }, + "limit": { + "type": "integer", + "description": "Returned page size." + }, + "total": { + "type": "integer", + "description": "Total number of matching dedicated integrations." + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + }, + "description": "Dedicated integrations on this page." + } + } + }, + "ChannelIntegrationCreateRequest": { + "type": "object", + "description": "Creates a dedicated integration in an enabled channel.", + "required": [ + "channel_id", + "plugin_type" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 20001, + "description": "Target channel ID; the channel must be enabled." + }, + "plugin_type": { + "type": "string", + "description": "Enabled alert integration type identifier, such as `standard.alert`." + }, + "name": { + "type": "string", + "maxLength": 49, + "description": "Integration name, 2–49 characters when supplied; omitted or empty uses the integration type default.", + "anyOf": [ + { + "maxLength": 0 + }, + { + "minLength": 2 + } + ] + }, + "description": { + "type": "string", + "maxLength": 499, + "description": "Description, at most 499 characters." + }, + "integration_key": { + "type": "string", + "maxLength": 35, + "description": "Optional supplied integration key. A non-empty value must have 35 characters, match the account suffix, and be unique.", + "anyOf": [ + { + "maxLength": 0 + }, + { + "minLength": 35 + } + ] + }, + "settings": { + "type": "object", + "additionalProperties": true, + "description": "Integration-type-specific configuration; saved secret values in responses are masked as `******`." + } + } + }, + "ChannelIntegrationListRequest": { + "type": "object", + "description": "Filters and pagination for one channel's dedicated integrations.", + "required": [ + "channel_id" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 20001, + "description": "Channel ID to list dedicated integrations for." + }, + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Page number, starting at 1." + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 100, + "description": "Number of items per page, at most 100." + }, + "name": { + "type": "string", + "maxLength": 49, + "description": "Filter by integration name." + }, + "plugin_type": { + "type": "string", + "description": "Filter by one integration type." + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Filter by `enabled` integrations that accept alerts or `disabled` integrations that pause ingestion." + } + } + }, + "ChannelIntegrationCreateResponse": { + "type": "object", + "description": "The created dedicated integration and its ingestion key.", + "required": [ + "integration_id", + "integration_key" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "Created dedicated integration ID." + }, + "integration_key": { + "type": "string", + "description": "Integration key for alert ingestion." + } + } } }, "securitySchemes": { @@ -61229,7 +61540,7 @@ "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.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- Public and dedicated integrations share this type catalog; it returns no configured integration instances, settings, or keys.\n- The App Key's `api_scopes` must allow `integration.api:read:typeList`; `channel.integration` scopes do not include this endpoint.\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.\n- `category` values are not validated; an unknown value returns an empty list.", "href": "/en/api-reference/on-call/integrations/integration-api-read-type-list", "metadata": { "sidebarTitle": "List integration types" @@ -61290,6 +61601,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -61982,10 +62296,837 @@ } } } - } - }, - "security": [ - { + }, + "/channel/integration/list": { + "post": { + "operationId": "channel-integration-read-list", + "summary": "List dedicated integrations", + "description": "List the dedicated integrations owned by one channel.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- Private channels also require the account owner, an Admin, the channel creator, or membership in its owning or managing teams; public channels still require the API permission above.\n- `channel_id` is required; `p` defaults to `1` and `limit` defaults to `100`, with a maximum of `100`.\n- `plugin_type` and `status` each accept one value.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-read-list", + "metadata": { + "sidebarTitle": "List dedicated integrations" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationListResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 1, + "items": [ + { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationListRequest" + }, + "example": { + "channel_id": 20001, + "p": 1, + "limit": 20 + } + } + } + } + } + }, + "/channel/integration/info": { + "post": { + "operationId": "channel-integration-read-info", + "summary": "Get dedicated integration detail", + "description": "Get one channel-owned integration, including its integration key and masked settings.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- Private channels also require the account owner, an Admin, the channel creator, or membership in its owning or managing teams; public channels still require the API permission above.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-read-info", + "metadata": { + "sidebarTitle": "Get dedicated integration detail" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/create": { + "post": { + "operationId": "channel-integration-write-create", + "summary": "Create dedicated integration", + "description": "Create a dedicated alert integration for an enabled channel.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- The channel must be enabled; the integration type must be enabled, belong to `event.alert`, and be supported by your subscription.\n- If you know the `plugin_type`, create the integration directly without querying types first. You can optionally query `POST /integration/type/list` for alert types with Channels Read, Channels Manage, or Integrations Read; the App Key's `api_scopes` must also allow `integration.api:read:typeList`.\n- An omitted `name` uses the integration type default; an omitted `integration_key` is generated. A supplied key must have 35 characters, match the account suffix, and not be used by another integration.\n- Success returns `integration_id` and `integration_key`; use that `integration_id` for subsequent operations.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-create", + "metadata": { + "sidebarTitle": "Create dedicated integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationCreateResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "integration_key": "0123456789abcdef0123456789abcdef100" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationCreateRequest" + }, + "example": { + "channel_id": 20001, + "plugin_type": "standard.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "settings": {} + } + } + } + } + } + }, + "/channel/integration/update": { + "post": { + "operationId": "channel-integration-write-update", + "summary": "Update dedicated integration", + "description": "Update the name, description, or settings of a dedicated integration.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.\n- Only supplied fields change; omitted or `null` fields retain their value. Send `description: \"\"` to clear the description.\n- Supplied `settings` follow the integration type configuration rules; masked or omitted secret fields retain their stored value. Retaining a secret does not allow changing its corresponding destination.\n- This endpoint does not change the channel, integration type, or integration key.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-update", + "metadata": { + "sidebarTitle": "Update dedicated integration" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments production alerts", + "description": "", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationUpdateRequest" + }, + "example": { + "integration_id": 10001, + "name": "Payments production alerts", + "description": "" + } + } + } + } + } + }, + "/channel/integration/delete": { + "post": { + "operationId": "channel-integration-write-delete", + "summary": "Delete dedicated integration", + "description": "Delete a dedicated integration after its references have been removed.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- Existing references return HTTP 400 with `ReferenceExist` and `data.refs` listing them; remove those references before deleting.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-delete", + "metadata": { + "sidebarTitle": "Delete dedicated 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": { + "description": "Invalid parameters or an existing reference; ReferenceExist includes data.refs.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorResponse" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "description": "Resources that prevent deletion.", + "properties": { + "refs": { + "type": "array", + "description": "Referencing resources; remove their references before retrying.", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "description": "Referencing resource kind." + }, + "name": { + "type": "string", + "description": "Referencing resource name." + }, + "href": { + "type": "string", + "description": "Console link to the referencing resource." + } + } + } + } + } + } + } + } + ] + }, + "examples": { + "missingParameter": { + "value": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "InvalidParameter", + "message": "The specified parameter is not valid." + } + } + } + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "ReferenceExist", + "message": "There still are associated resources, deletion is blocked." + }, + "data": { + "refs": [ + { + "kind": "channel", + "name": "Payments", + "href": "https://console.flashcat.cloud/channel/20001" + } + ] + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/enable": { + "post": { + "operationId": "channel-integration-write-enable", + "summary": "Enable dedicated integration", + "description": "Enable a dedicated integration so it can receive alerts.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- After permission and subscription checks pass, repeating an operation when the target state is already set succeeds.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-enable", + "metadata": { + "sidebarTitle": "Enable dedicated 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" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/disable": { + "post": { + "operationId": "channel-integration-write-disable", + "summary": "Disable dedicated integration", + "description": "Disable a dedicated integration to pause alert ingestion.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- After permission checks pass, repeating this operation when the integration is already disabled succeeds.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-disable", + "metadata": { + "sidebarTitle": "Disable dedicated 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" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/key/rotate": { + "post": { + "operationId": "channel-integration-write-rotate-key", + "summary": "Rotate dedicated integration key", + "description": "Issue a new dedicated integration key and invalidate the previous key.", + "tags": [ + "On-call/Dedicated integrations" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- After the previous key is invalidated, senders using it can no longer ingest alerts; configure the returned key in the corresponding monitoring system.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-rotate-key", + "metadata": { + "sidebarTitle": "Rotate dedicated 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": "0123456789abcdef0123456789abcdef100" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "Another request is changing this channel's integrations. Retry after it completes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + } + }, + "security": [ + { "AppKeyAuth": [] } ], @@ -62145,6 +63286,10 @@ { "description": "AI SRE artifact gallery — publish, browse, and publicly share agent-produced files.", "name": "AI SRE/Artifacts" + }, + { + "name": "On-call/Dedicated integrations", + "description": "Manage alert integrations owned by individual channels." } ] } diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index dbbb1a1dc..45ee86f1e 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -30083,10 +30083,321 @@ "properties": { "integration_key": { "type": "string", - "description": "新的集成 Key，旧 Key 立即失效；新 Key 也可通过 `/integration/list` 和 `/integration/info` 查询。", + "description": "新的集成 Key；原 Key 立即失效。", "example": "0123456789abcdef0123456789abcdef100" } } + }, + "ChannelIntegrationItem": { + "type": "object", + "description": "协作空间专属集成，包含完整集成 Key 和脱敏配置。", + "required": [ + "integration_id", + "channel_id", + "integration_key", + "exclusive_data_source_id", + "plugin_id", + "plugin_type", + "plugin_type_name", + "category", + "name", + "description", + "status", + "created_at", + "updated_at", + "last_time", + "last_source_time", + "settings" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "专属集成 ID，后续接口调用使用此 ID。" + }, + "channel_id": { + "type": "integer", + "format": "int64", + "description": "专属集成所属的协作空间 ID。" + }, + "integration_key": { + "type": "string", + "description": "用于告警接入的完整集成 Key，与管理接口的 App Key 不同。" + }, + "exclusive_data_source_id": { + "type": "integer", + "format": "int64", + "description": "早期集成的兼容标识，无关联值时为 `0`；本组接口统一使用 `integration_id`。" + }, + "plugin_id": { + "type": "integer", + "format": "int64", + "description": "集成类型的数字 ID；创建时使用字符串 `plugin_type`。" + }, + "plugin_type": { + "type": "string", + "description": "集成类型标识，例如 `standard.alert`。" + }, + "plugin_type_name": { + "type": "string", + "description": "按请求语言返回的集成类型显示名称。" + }, + "category": { + "type": "string", + "description": "集成分类；专属集成创建接口接受 `event.alert` 告警集成。" + }, + "name": { + "type": "string", + "description": "集成名称。" + }, + "description": { + "type": "string", + "description": "集成描述；未设置时为空字符串。" + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "集成状态：`enabled` 表示接收告警，`disabled` 表示暂停接入。" + }, + "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`。" + }, + "last_source_time": { + "type": "integer", + "format": "int64", + "description": "最近事件的来源时间，Unix 时间戳，单位为秒；无可用值时为 `0`。" + }, + "settings": { + "type": "object", + "additionalProperties": true, + "description": "集成类型对应的配置；响应中已保存的密钥类值以 `******` 返回。" + } + } + }, + "ChannelIntegrationIDRequest": { + "type": "object", + "description": "标识一条专属集成。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 10001, + "description": "创建、列表或详情接口返回的专属集成 ID；不接受公共集成 ID。" + } + } + }, + "ChannelIntegrationUpdateRequest": { + "type": "object", + "description": "专属集成的部分更新；省略或为 null 的字段保留原值。", + "required": [ + "integration_id" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 10001, + "description": "创建、列表或详情接口返回的专属集成 ID；不接受公共集成 ID。" + }, + "name": { + "type": [ + "string", + "null" + ], + "minLength": 2, + "maxLength": 49, + "description": "新名称，2–49 个字符；省略或为 null 时保留原名称。" + }, + "description": { + "type": [ + "string", + "null" + ], + "maxLength": 499, + "description": "新描述，最多 499 个字符；空字符串清空，省略或为 null 时保留。" + }, + "settings": { + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "按集成类型替换配置；省略或为 null 时保留，已脱敏或省略的密钥类字段保留原值。" + } + } + }, + "ChannelIntegrationListResponse": { + "type": "object", + "description": "一页专属集成结果。", + "required": [ + "p", + "limit", + "total", + "items" + ], + "properties": { + "p": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "当前每页条数。" + }, + "total": { + "type": "integer", + "description": "符合条件的专属集成总数。" + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + }, + "description": "当前页的专属集成。" + } + } + }, + "ChannelIntegrationCreateRequest": { + "type": "object", + "description": "在已启用的协作空间创建专属集成。", + "required": [ + "channel_id", + "plugin_type" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 20001, + "description": "目标协作空间 ID，空间须已启用。" + }, + "plugin_type": { + "type": "string", + "description": "已启用的告警集成类型标识，例如 `standard.alert`。" + }, + "name": { + "type": "string", + "maxLength": 49, + "description": "集成名称，提供时为 2–49 个字符；省略或为空时使用集成类型的默认名称。", + "anyOf": [ + { + "maxLength": 0 + }, + { + "minLength": 2 + } + ] + }, + "description": { + "type": "string", + "maxLength": 499, + "description": "集成描述，最多 499 个字符。" + }, + "integration_key": { + "type": "string", + "maxLength": 35, + "description": "可选的自带集成 Key；非空时须为 35 个字符、匹配账户后缀，且未被其他集成使用。", + "anyOf": [ + { + "maxLength": 0 + }, + { + "minLength": 35 + } + ] + }, + "settings": { + "type": "object", + "additionalProperties": true, + "description": "集成类型对应的配置；响应中已保存的密钥类值以 `******` 返回。" + } + } + }, + "ChannelIntegrationListRequest": { + "type": "object", + "description": "指定协作空间的专属集成查询条件。", + "required": [ + "channel_id" + ], + "properties": { + "channel_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "example": 20001, + "description": "要查询专属集成的协作空间 ID。" + }, + "p": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "页码，从 1 开始。" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 100, + "description": "每页条数，最多 100 条。" + }, + "name": { + "type": "string", + "maxLength": 49, + "description": "按集成名称过滤。" + }, + "plugin_type": { + "type": "string", + "description": "按单个集成类型过滤。" + }, + "status": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "按状态过滤：`enabled` 表示接收告警，`disabled` 表示暂停接入。" + } + } + }, + "ChannelIntegrationCreateResponse": { + "type": "object", + "description": "创建完成的专属集成及其接入 Key。", + "required": [ + "integration_id", + "integration_key" + ], + "properties": { + "integration_id": { + "type": "integer", + "format": "int64", + "description": "创建完成的专属集成 ID。" + }, + "integration_key": { + "type": "string", + "description": "用于告警接入的集成 Key。" + } + } } }, "securitySchemes": { @@ -61229,7 +61540,7 @@ "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` 创建。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 公共集成和专属集成共用此类型目录，不返回已配置的集成实例、配置或 Key。\n- App Key 的 `api_scopes` 须允许 `integration.api:read:typeList`；`channel.integration` 范围不包含此接口。\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。\n- `category` 取值不做校验，未知值会返回空列表。", "href": "/zh/api-reference/on-call/integrations/integration-api-read-type-list", "metadata": { "sidebarTitle": "查询集成类型列表" @@ -61290,6 +61601,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -61982,7 +62296,834 @@ } } } - } + }, + "/channel/integration/list": { + "post": { + "operationId": "channel-integration-read-list", + "summary": "查询专属集成列表", + "description": "查询指定协作空间的专属集成。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 查看私有空间还要求您是账户所有者、Admin、空间创建者，或所属团队、管理团队的成员；公开空间仍需上述接口权限。\n- `channel_id` 必填；`p` 默认 `1`，`limit` 默认 `100`，最多 `100`。\n- `plugin_type` 和 `status` 各接受单个值。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-list", + "metadata": { + "sidebarTitle": "查询专属集成列表" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationListResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "p": 1, + "limit": 20, + "total": 1, + "items": [ + { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationListRequest" + }, + "example": { + "channel_id": 20001, + "p": 1, + "limit": 20 + } + } + } + } + } + }, + "/channel/integration/info": { + "post": { + "operationId": "channel-integration-read-info", + "summary": "查看专属集成详情", + "description": "查看专属集成详情、集成 Key 和脱敏配置。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 查看私有空间还要求您是账户所有者、Admin、空间创建者，或所属团队、管理团队的成员；公开空间仍需上述接口权限。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-info", + "metadata": { + "sidebarTitle": "查看专属集成详情" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/create": { + "post": { + "operationId": "channel-integration-write-create", + "summary": "创建专属集成", + "description": "为已启用的协作空间创建专属告警集成。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 目标空间必须已启用；集成类型须已启用、属于 `event.alert`，且您的订阅支持该类型。\n- 已知 `plugin_type` 时可直接创建，无需先查询类型。也可选用 `POST /integration/type/list` 查询告警类型；该接口支持协作空间查看、管理或集成中心查看权限，App Key 的 `api_scopes` 还须允许 `integration.api:read:typeList`。\n- 省略 `name` 时使用集成类型的默认名称；省略 `integration_key` 时自动生成。自带 Key 须为 35 个字符、匹配账户后缀，且未被其他集成使用。\n- 成功后返回 `integration_id` 和 `integration_key`；后续操作使用返回的 `integration_id`。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-create", + "metadata": { + "sidebarTitle": "创建专属集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationCreateResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "integration_key": "0123456789abcdef0123456789abcdef100" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationCreateRequest" + }, + "example": { + "channel_id": 20001, + "plugin_type": "standard.alert", + "name": "Payments alerts", + "description": "Alerts for the payments channel", + "settings": {} + } + } + } + } + } + }, + "/channel/integration/update": { + "post": { + "operationId": "channel-integration-write-update", + "summary": "更新专属集成", + "description": "更新专属集成的名称、描述或配置。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。\n- 仅更新传入的字段；省略或设为 `null` 时保留原值。`description: \"\"` 清空描述。\n- 传入 `settings` 时按该类型的配置规则保存；已脱敏或省略的密钥类字段保留原值。保留原密钥时，不能同时更改对应的目标地址。\n- 此接口不更改所属空间、集成类型或集成 Key。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-update", + "metadata": { + "sidebarTitle": "更新专属集成" + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChannelIntegrationItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "integration_id": 10001, + "channel_id": 20001, + "integration_key": "0123456789abcdef0123456789abcdef100", + "exclusive_data_source_id": 0, + "plugin_id": 9, + "plugin_type": "standard.alert", + "plugin_type_name": "Standard alert", + "category": "event.alert", + "name": "Payments production alerts", + "description": "", + "status": "enabled", + "created_at": 1767225600, + "updated_at": 1767225600, + "last_time": 0, + "last_source_time": 0, + "settings": {} + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationUpdateRequest" + }, + "example": { + "integration_id": 10001, + "name": "Payments production alerts", + "description": "" + } + } + } + } + } + }, + "/channel/integration/delete": { + "post": { + "operationId": "channel-integration-write-delete", + "summary": "删除专属集成", + "description": "删除已解除资源引用的专属集成。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 存在其他资源引用时，返回 HTTP 400、`ReferenceExist`，并在 `data.refs` 中列出引用；解除引用后再删除。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-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": { + "description": "参数无效或存在资源引用；ReferenceExist 错误包含 data.refs。", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorResponse" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "description": "阻止删除的引用资源。", + "properties": { + "refs": { + "type": "array", + "description": "引用当前集成的资源；解除引用后再重试。", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "description": "引用资源的类型。" + }, + "name": { + "type": "string", + "description": "引用资源的名称。" + }, + "href": { + "type": "string", + "description": "引用资源的控制台链接。" + } + } + } + } + } + } + } + } + ] + }, + "examples": { + "missingParameter": { + "value": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "InvalidParameter", + "message": "The specified parameter is not valid." + } + } + } + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "ReferenceExist", + "message": "There still are associated resources, deletion is blocked." + }, + "data": { + "refs": [ + { + "kind": "channel", + "name": "Payments", + "href": "https://console.flashcat.cloud/channel/20001" + } + ] + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/enable": { + "post": { + "operationId": "channel-integration-write-enable", + "summary": "启用专属集成", + "description": "启用专属集成，使其接收告警。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 权限及订阅校验通过后，已处于目标状态时重复调用成功返回。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-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" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/disable": { + "post": { + "operationId": "channel-integration-write-disable", + "summary": "禁用专属集成", + "description": "禁用专属集成，暂停接收告警。", + "tags": [ + "On-call/专属集成" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 权限校验通过后，已处于禁用状态时重复调用成功返回。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-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" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + }, + "/channel/integration/key/rotate": { + "post": { + "operationId": "channel-integration-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- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 原 Key 失效后，仍使用原 Key 的推送端将无法接入；请将返回的新 Key 配置到对应监控系统。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-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": "0123456789abcdef0123456789abcdef100" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + }, + "423": { + "description": "同一空间的集成正在变更，请稍后重试。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "error": { + "code": "RequestLocked", + "message": "Channel integration is being changed, please try again" + } + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChannelIntegrationIDRequest" + }, + "example": { + "integration_id": 10001 + } + } + } + } + } + } }, "security": [ { @@ -62145,6 +63286,10 @@ { "description": "AI SRE 产物库 —— 发布、浏览并公开分享智能体生成的文件。", "name": "AI SRE/产物" + }, + { + "name": "On-call/专属集成", + "description": "管理各协作空间的专属告警集成。" } ] } diff --git a/docs.json b/docs.json index 9d76c7ca3..1bc091fc3 100644 --- a/docs.json +++ b/docs.json @@ -1446,6 +1446,38 @@ { "source": "/integration/update", "destination": "/zh/api-reference/on-call/integrations/integration-api-write-update" + }, + { + "source": "/channel/integration/create", + "destination": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-create" + }, + { + "source": "/channel/integration/delete", + "destination": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-delete" + }, + { + "source": "/channel/integration/disable", + "destination": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-disable" + }, + { + "source": "/channel/integration/enable", + "destination": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-enable" + }, + { + "source": "/channel/integration/info", + "destination": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-info" + }, + { + "source": "/channel/integration/key/rotate", + "destination": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-rotate-key" + }, + { + "source": "/channel/integration/list", + "destination": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-list" + }, + { + "source": "/channel/integration/update", + "destination": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-update" } ], "navigation": { @@ -2568,18 +2600,36 @@ "group": "集成中心", "icon": "plug", "pages": [ + { + "group": "公共集成", + "pages": [ + "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" + ] + }, + { + "group": "专属集成", + "pages": [ + "POST /channel/integration/list", + "POST /channel/integration/info", + "POST /channel/integration/create", + "POST /channel/integration/update", + "POST /channel/integration/delete", + "POST /channel/integration/enable", + "POST /channel/integration/disable", + "POST /channel/integration/key/rotate" + ] + }, "POST /webhook/history/list", "POST /webhook/history/detail", - "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" + "POST /datasource/im/person/try-link" ] }, { @@ -4217,18 +4267,36 @@ "group": "Integrations", "icon": "plug", "pages": [ + { + "group": "Public integrations", + "pages": [ + "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" + ] + }, + { + "group": "Dedicated integrations", + "pages": [ + "POST /channel/integration/list", + "POST /channel/integration/info", + "POST /channel/integration/create", + "POST /channel/integration/update", + "POST /channel/integration/delete", + "POST /channel/integration/enable", + "POST /channel/integration/disable", + "POST /channel/integration/key/rotate" + ] + }, "POST /webhook/history/list", "POST /webhook/history/detail", - "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" + "POST /datasource/im/person/try-link" ] }, { diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index 6b2d3c550..6d5ab054d 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 **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. +Flashduty Open API provides **355** 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 @@ -127,24 +127,46 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi | POST | [`/alert/pipeline/upsert`](/en/api-reference/on-call/alerts/alert-write-pipeline-upsert) | Create or update alert pipeline | | POST | [`/alert-event/list`](/en/api-reference/on-call/alerts/alert-event-read-list) | List raw alert events | -### Integrations +### Public integrations -The `/integration/*` management APIs cover public (account-level) integrations, including supported IM and webhook types. Channel-owned dedicated integrations are not part of this public API surface. `/integration/list` and `/integration/info` return stored settings and decrypted integration keys without masking. +`/integration/*` manages public (account-level) integrations, including supported IM and webhook types. Use `/channel/integration/*` for channel-owned dedicated integrations. List and info return complete integration keys and mask saved configuration secrets as `******`. + +| Method | Endpoint | Description | +| :--- | :--- | :--- | +| 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 public integrations | +| POST | [`/integration/info`](/en/api-reference/on-call/integrations/integration-api-read-info) | Get public integration detail | +| POST | [`/integration/create`](/en/api-reference/on-call/integrations/integration-api-write-create) | Create public integration | +| POST | [`/integration/update`](/en/api-reference/on-call/integrations/integration-api-write-update) | Update public integration | +| POST | [`/integration/delete`](/en/api-reference/on-call/integrations/integration-api-write-delete) | Delete public integration | +| POST | [`/integration/enable`](/en/api-reference/on-call/integrations/integration-api-write-enable) | Enable public integration | +| POST | [`/integration/disable`](/en/api-reference/on-call/integrations/integration-api-write-disable) | Disable public integration | +| POST | [`/integration/key/rotate`](/en/api-reference/on-call/integrations/integration-api-write-rotate-key) | Rotate public integration key | + +### Dedicated integrations + +`/channel/integration/*` manages channel-owned dedicated integrations. Queries require **Channels Read**, **Channels Manage**, or **Integrations Read**; writes require **Channels Manage**. You also need visibility of the target channel for queries and management access for writes. The shared `/integration/type/list` catalog accepts these three read permissions; a scoped App Key must allow `integration.api:read:typeList` to query it. + +The App Key's `api_scopes` must allow the operation. Private channels are visible to the account owner, an Admin, the channel creator, or members of the owning or managing teams; writes follow channel management access. Queries return the complete integration key and mask saved configuration secrets as `******`. + +| Method | Endpoint | Description | +| :--- | :--- | :--- | +| POST | [`/channel/integration/list`](/en/api-reference/on-call/dedicated-integrations/channel-integration-read-list) | List dedicated integrations | +| POST | [`/channel/integration/info`](/en/api-reference/on-call/dedicated-integrations/channel-integration-read-info) | Get dedicated integration detail | +| POST | [`/channel/integration/create`](/en/api-reference/on-call/dedicated-integrations/channel-integration-write-create) | Create dedicated integration | +| POST | [`/channel/integration/update`](/en/api-reference/on-call/dedicated-integrations/channel-integration-write-update) | Update dedicated integration | +| POST | [`/channel/integration/delete`](/en/api-reference/on-call/dedicated-integrations/channel-integration-write-delete) | Delete dedicated integration | +| POST | [`/channel/integration/enable`](/en/api-reference/on-call/dedicated-integrations/channel-integration-write-enable) | Enable dedicated integration | +| POST | [`/channel/integration/disable`](/en/api-reference/on-call/dedicated-integrations/channel-integration-write-disable) | Disable dedicated integration | +| POST | [`/channel/integration/key/rotate`](/en/api-reference/on-call/dedicated-integrations/channel-integration-write-rotate-key) | Rotate dedicated integration key | + +### Integration utilities | Method | Endpoint | Description | | :--- | :--- | :--- | | 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 2716c137b..3d12cc7b6 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 提供 **347** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 +Flashduty Open API 提供 **355** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 所有接口 URL 均以 `https://api.flashcat.cloud` 为 base，通过 query string 中的 APP Key 认证。 - + ### 故障管理 @@ -127,24 +127,46 @@ Flashduty Open API 提供 **347** 个接口，覆盖 On-call、Monitors、RUM、 | POST | [`/alert/pipeline/upsert`](/zh/api-reference/on-call/alerts/alert-write-pipeline-upsert) | 创建或更新告警处理规则 | | POST | [`/alert-event/list`](/zh/api-reference/on-call/alerts/alert-event-read-list) | 查询原始告警事件列表 | -### 集成中心 +### 公共集成 -`/integration/*` 管理接口用于公共（账户级）集成，包含支持的 IM 与 Webhook 类型，不包含协作空间专属集成。`/integration/list` 与 `/integration/info` 返回存储配置和解密后的集成 Key，不打码。 +`/integration/*` 管理公共（账户级）集成，包含支持的 IM 和 Webhook 类型。协作空间专属集成使用 `/channel/integration/*`。列表和详情返回完整集成 Key，配置中已保存的密钥类值返回 `******`。 + +| 方法 | 接口 | 描述 | +| :--- | :--- | :--- | +| 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 | + +### 专属集成 + +`/channel/integration/*` 管理协作空间专属集成。查询要求**协作空间查看**、**协作空间管理**或**集成中心查看**，写入要求**协作空间管理**。查询还要求目标空间可见，写入还要求目标空间的管理资格。共用的 `/integration/type/list` 类型目录也允许这三项读取权限；限制了接口范围的 App Key 须允许 `integration.api:read:typeList` 才能查询。 + +App Key 的 `api_scopes` 须允许对应操作。私有空间仅对账户所有者、Admin、空间创建者、所属团队和管理团队成员可见；写入按空间管理权限判断。查询返回完整集成 Key，配置中的已保存密钥类值返回 `******`。 + +| 方法 | 接口 | 描述 | +| :--- | :--- | :--- | +| POST | [`/channel/integration/list`](/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-list) | 查询专属集成列表 | +| POST | [`/channel/integration/info`](/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-info) | 查看专属集成详情 | +| POST | [`/channel/integration/create`](/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-create) | 创建专属集成 | +| POST | [`/channel/integration/update`](/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-update) | 更新专属集成 | +| POST | [`/channel/integration/delete`](/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-delete) | 删除专属集成 | +| POST | [`/channel/integration/enable`](/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-enable) | 启用专属集成 | +| POST | [`/channel/integration/disable`](/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-disable) | 禁用专属集成 | +| POST | [`/channel/integration/key/rotate`](/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-rotate-key) | 轮换专属集成 Key | + +### 集成工具 | 方法 | 接口 | 描述 | | :--- | :--- | :--- | | 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 | ### 值班排班