From cdb469213d2089d6ace3443135b5b51507f855d3 Mon Sep 17 00:00:00 2001 From: alick-liming Date: Mon, 26 Oct 2026 21:04:09 +0800 Subject: [PATCH 1/4] docs: add dedicated integration API reference --- api-reference/on-call.openapi.en.json | 1176 ++++++++++++++++++++++++- api-reference/on-call.openapi.zh.json | 1176 ++++++++++++++++++++++++- api-reference/openapi.en.json | 1176 ++++++++++++++++++++++++- api-reference/openapi.zh.json | 1176 ++++++++++++++++++++++++- docs.json | 104 ++- en/openapi/api-catalog.mdx | 48 +- zh/openapi/api-catalog.mdx | 48 +- 7 files changed, 4792 insertions(+), 112 deletions(-) diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index 02737db6..2d1e3caf 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": { @@ -320,7 +324,7 @@ "/integration/list": { "post": { "operationId": "integration-api-read-list", - "summary": "List integrations", + "summary": "List public integrations", "description": "List public integrations with their stored settings, decrypted keys, and edit permissions.", "tags": [ "On-call/Integrations" @@ -329,7 +333,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- `orderby` defaults to `created_at`; `plugin_type` sorts by the underlying plugin. Rows are ordered by `ref_id` first, so `orderby` applies within each `ref_id` group.\n- `plugin_type`, `status` and `category` accept comma-separated values; `ref_ids` values must start with `c_`, `a_` or `w_`; a `c_` filter is syntactically accepted but does not return channel-owned integrations.\n- With `is_my_team` set, results are limited to your teams and `team_ids` narrows that set further; when you belong to no team, or `team_ids` shares no team with yours, the list is empty.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Items include `settings`, `integration_key`, `plugin_id`, `account_id`, and the legacy `data_source_id` alias. Saved secret values in `settings` are returned as `******`; `integration_key` is returned as is.", "href": "/en/api-reference/on-call/integrations/integration-api-read-list", "metadata": { - "sidebarTitle": "List integrations" + "sidebarTitle": "List public integrations" } }, "responses": { @@ -428,7 +432,7 @@ "/integration/info": { "post": { "operationId": "integration-api-read-info", - "summary": "Get integration detail", + "summary": "Get public integration detail", "description": "Get a public integration with its stored settings and decrypted integration key.", "tags": [ "On-call/Integrations" @@ -437,7 +441,7 @@ "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- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Saved secret values in `settings` are returned as `******`, and unset ones stay empty. The integration key is returned as is.\n- An unknown ID, or the ID of a channel-owned integration, returns `ResourceNotFound`.", "href": "/en/api-reference/on-call/integrations/integration-api-read-info", "metadata": { - "sidebarTitle": "Get integration detail" + "sidebarTitle": "Get public integration detail" } }, "responses": { @@ -524,7 +528,7 @@ "/integration/create": { "post": { "operationId": "integration-api-write-create", - "summary": "Create integration", + "summary": "Create public integration", "description": "Create a public integration for a supported alert, change, IM, or webhook type.", "tags": [ "On-call/Integrations" @@ -533,7 +537,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `plugin_type` must be one of the types listed by `POST /integration/type/list` with `supports_api_create: true`; anything else returns `InvalidParameter`.\n- A type whose `status` is `disabled` returns `InvalidParameter`; a type not included in the account's plan returns `NoLicense`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- An omitted `integration_key` is generated automatically; a supplied key must satisfy the length, account suffix, and uniqueness checks.\n- With `is_test: true`, inspect `test.success`; an HTTP 200 response alone does not establish that the plugin test succeeded.\n- Every call is recorded in the account audit log.", "href": "/en/api-reference/on-call/integrations/integration-api-write-create", "metadata": { - "sidebarTitle": "Create integration" + "sidebarTitle": "Create public integration" } }, "responses": { @@ -612,7 +616,7 @@ "/integration/update": { "post": { "operationId": "integration-api-write-update", - "summary": "Update integration", + "summary": "Update public integration", "description": "Update an integration's name, description, team, or settings.", "tags": [ "On-call/Integrations" @@ -621,7 +625,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields you send are changed; omitted fields keep their current value.\n- Submitting `settings` replaces the configuration; known sensitive fields omitted or sent as `******` retain their value. Keeping a stored secret while changing where it is sent (such as `endpoint`, `url`, a database host or port, or an IM API base URL) is rejected, so send the secrets again with the new destination; `******` on a field with no stored value is rejected too. Send `headers: {}` to clear headers; use the integration type’s explicit empty value to clear a body.\n- Submit `settings` together with `is_test: true` to receive a plugin test result; secrets in the returned settings are masked the same way.\n- If another request changes the same integration's settings while this one is being processed, the call returns `RequestLocked`; retry it. A type no longer included in the account's plan returns `NoLicense`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.\n- Every call is recorded in the account audit log.", "href": "/en/api-reference/on-call/integrations/integration-api-write-update", "metadata": { - "sidebarTitle": "Update integration" + "sidebarTitle": "Update public integration" } }, "responses": { @@ -719,7 +723,7 @@ "/integration/delete": { "post": { "operationId": "integration-api-write-delete", - "summary": "Delete integration", + "summary": "Delete public integration", "description": "Delete an integration that nothing else references.", "tags": [ "On-call/Integrations" @@ -728,7 +732,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Deleting an integration that other objects still reference returns HTTP 400 with `error.code` = `ReferenceExist` and `data.refs` listing them.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.", "href": "/en/api-reference/on-call/integrations/integration-api-write-delete", "metadata": { - "sidebarTitle": "Delete integration" + "sidebarTitle": "Delete public integration" } }, "responses": { @@ -792,7 +796,7 @@ "/integration/enable": { "post": { "operationId": "integration-api-write-enable", - "summary": "Enable integration", + "summary": "Enable public integration", "description": "Re-enable a disabled integration so it accepts events again.", "tags": [ "On-call/Integrations" @@ -801,7 +805,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enabling an integration resumes its scheduled pull task and heartbeat, and requires the integration type to be available on the current plan.\n- Enabling an integration that is already enabled succeeds without change; the same holds for disabling a disabled one.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.", "href": "/en/api-reference/on-call/integrations/integration-api-write-enable", "metadata": { - "sidebarTitle": "Enable integration" + "sidebarTitle": "Enable public integration" } }, "responses": { @@ -865,7 +869,7 @@ "/integration/disable": { "post": { "operationId": "integration-api-write-disable", - "summary": "Disable integration", + "summary": "Disable public integration", "description": "Disable an integration without deleting its configuration.", "tags": [ "On-call/Integrations" @@ -874,7 +878,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Disabling stops event ingestion and pauses the scheduled pull task; settings are kept so the integration can be enabled again.\n- Enabling an integration that is already enabled succeeds without change; the same holds for disabling a disabled one.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.", "href": "/en/api-reference/on-call/integrations/integration-api-write-disable", "metadata": { - "sidebarTitle": "Disable integration" + "sidebarTitle": "Disable public integration" } }, "responses": { @@ -938,7 +942,7 @@ "/integration/key/rotate": { "post": { "operationId": "integration-api-write-rotate-key", - "summary": "Rotate integration key", + "summary": "Rotate public integration key", "description": "Issue a new integration key and invalidate the previous one.", "tags": [ "On-call/Integrations" @@ -947,7 +951,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- The previous key stops working immediately; after rotation, update the pushing side with the new key.\n- The new key can also be read from `/integration/list` and `/integration/info`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.\n- Every call is recorded in the account audit log.", "href": "/en/api-reference/on-call/integrations/integration-api-write-rotate-key", "metadata": { - "sidebarTitle": "Rotate integration key" + "sidebarTitle": "Rotate public integration key" } }, "responses": { @@ -19611,6 +19615,833 @@ } } } + }, + "/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** or **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- 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** or **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- 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- Query `POST /integration/type/list` and select a supported alert type for the dedicated integration.\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 + } + } + } + } + } } }, "components": { @@ -36981,7 +37812,7 @@ "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" } } @@ -37688,6 +38519,317 @@ "description": "What the conversion read from the email. `null` when the email could not be parsed." } } + }, + "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." + } + } + }, + "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." + } + } + }, + "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 `******`." + } + } + }, + "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." + } + } + }, + "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." + } + } } } } diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index 9d5d63ad..c6ae7f6c 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": { @@ -320,7 +324,7 @@ "/integration/list": { "post": { "operationId": "integration-api-read-list", - "summary": "查询集成列表", + "summary": "查询公共集成列表", "description": "查询公共集成列表，返回存储配置、解密 Key 与当前调用者的编辑权限。", "tags": [ "On-call/集成中心" @@ -329,7 +333,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- `orderby` 默认 `created_at`；`plugin_type` 按底层插件排序。结果先按 `ref_id` 升序排列，`orderby` 在相同 `ref_id` 内生效。\n- `plugin_type`、`status`、`category` 支持逗号分隔多值；`ref_ids` 每个值必须以 `c_`、`a_` 或 `w_` 开头；`c_` 过滤值通过格式校验，但不会返回协作空间专属集成。\n- 传入 `is_my_team` 时仅返回你所在团队的集成，`team_ids` 会在该范围内进一步收窄；你不属于任何团队，或 `team_ids` 与你的团队没有交集时，返回空列表。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 列表项包含 `settings`、`integration_key`、`plugin_id`、`account_id` 及旧 ID 别名 `data_source_id`。`settings` 中已保存的密钥类值返回 `******`，`integration_key` 按原值返回。", "href": "/zh/api-reference/on-call/integrations/integration-api-read-list", "metadata": { - "sidebarTitle": "查询集成列表" + "sidebarTitle": "查询公共集成列表" } }, "responses": { @@ -428,7 +432,7 @@ "/integration/info": { "post": { "operationId": "integration-api-read-info", - "summary": "查询集成详情", + "summary": "查看公共集成详情", "description": "查询单个公共集成详情，返回存储配置及解密后的集成 Key。", "tags": [ "On-call/集成中心" @@ -437,7 +441,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- `settings` 中已保存的密钥类值返回 `******`，未设置的保持为空；集成 Key 按原值返回。\n- ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。", "href": "/zh/api-reference/on-call/integrations/integration-api-read-info", "metadata": { - "sidebarTitle": "查询集成详情" + "sidebarTitle": "查看公共集成详情" } }, "responses": { @@ -524,7 +528,7 @@ "/integration/create": { "post": { "operationId": "integration-api-write-create", - "summary": "创建集成", + "summary": "创建公共集成", "description": "创建支持的告警源、变更源、IM 或 Webhook 类型公共集成。", "tags": [ "On-call/集成中心" @@ -533,7 +537,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `plugin_type` 必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型，否则返回 `InvalidParameter`。\n- `status` 为 `disabled` 的类型返回 `InvalidParameter`；当前套餐不包含的类型返回 `NoLicense`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 不传 `integration_key` 时自动生成；传入时须满足长度、账户后缀与唯一性校验。\n- 传 `is_test: true` 时请检查 `test.success`，不能只根据 HTTP 200 判断插件测试成功。\n- 每次调用都会记录到账户审计日志。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-create", "metadata": { - "sidebarTitle": "创建集成" + "sidebarTitle": "创建公共集成" } }, "responses": { @@ -612,7 +616,7 @@ "/integration/update": { "post": { "operationId": "integration-api-write-update", - "summary": "更新集成", + "summary": "更新公共集成", "description": "更新集成的名称、描述、所属团队或配置。", "tags": [ "On-call/集成中心" @@ -621,7 +625,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 仅发送的字段会被修改，未发送的字段保持原值。\n- 提交 `settings` 会替换配置；已识别的敏感字段不传或传 `******` 时保留原值。保留已存密钥的同时修改它的发送目标（如 `endpoint`、`url`、数据库主机或端口、IM 接口地址）会被拒绝，需要随新目标重新填写密钥；没有已存值的字段传 `******` 也会被拒绝。清空 Headers 请传 `headers: {}`；清空 Body 请使用该集成类型的显式空值。\n- 同时提交 `settings` 与 `is_test: true` 可获得插件测试结果，返回的 settings 中密钥同样返回 `******`。\n- 处理期间若有其他请求修改了同一集成的配置，本次调用返回 `RequestLocked`，重试即可。当前套餐已不包含该集成类型时返回 `NoLicense`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。\n- 每次调用都会记录到账户审计日志。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-update", "metadata": { - "sidebarTitle": "更新集成" + "sidebarTitle": "更新公共集成" } }, "responses": { @@ -719,7 +723,7 @@ "/integration/delete": { "post": { "operationId": "integration-api-write-delete", - "summary": "删除集成", + "summary": "删除公共集成", "description": "删除指定的集成。", "tags": [ "On-call/集成中心" @@ -728,7 +732,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 若该集成仍被其他对象引用，删除会返回 HTTP 400，`error.code` 为 `ReferenceExist`，`data.refs` 列出引用方。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-delete", "metadata": { - "sidebarTitle": "删除集成" + "sidebarTitle": "删除公共集成" } }, "responses": { @@ -792,7 +796,7 @@ "/integration/enable": { "post": { "operationId": "integration-api-write-enable", - "summary": "启用集成", + "summary": "启用公共集成", "description": "重新启用已禁用的集成，恢复接收事件。", "tags": [ "On-call/集成中心" @@ -801,7 +805,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 启用会恢复该集成的拉取任务与心跳，并要求当前套餐包含该集成类型。\n- 对已启用的集成调用启用、或对已禁用的集成调用禁用，会直接成功且不做变更。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-enable", "metadata": { - "sidebarTitle": "启用集成" + "sidebarTitle": "启用公共集成" } }, "responses": { @@ -865,7 +869,7 @@ "/integration/disable": { "post": { "operationId": "integration-api-write-disable", - "summary": "禁用集成", + "summary": "禁用公共集成", "description": "禁用集成，但保留其配置。", "tags": [ "On-call/集成中心" @@ -874,7 +878,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 禁用后停止接收事件并暂停定时拉取任务，配置保留，可再次启用。\n- 对已启用的集成调用启用、或对已禁用的集成调用禁用，会直接成功且不做变更。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-disable", "metadata": { - "sidebarTitle": "禁用集成" + "sidebarTitle": "禁用公共集成" } }, "responses": { @@ -938,7 +942,7 @@ "/integration/key/rotate": { "post": { "operationId": "integration-api-write-rotate-key", - "summary": "轮换集成 Key", + "summary": "轮换公共集成 Key", "description": "生成新的集成 Key，并使旧 Key 立即失效。", "tags": [ "On-call/集成中心" @@ -947,7 +951,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 旧 Key 会立即失效；轮换后请将推送端配置更新为新 Key。\n- 新 Key 也可通过 `/integration/list` 和 `/integration/info` 查询。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。\n- 每次调用都会记录到账户审计日志。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-rotate-key", "metadata": { - "sidebarTitle": "轮换集成 Key" + "sidebarTitle": "轮换公共集成 Key" } }, "responses": { @@ -19611,6 +19615,833 @@ } } } + }, + "/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- 通过 `POST /integration/type/list` 查询类型；为专属集成选择支持的告警类型。\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 + } + } + } + } + } } }, "components": { @@ -36981,7 +37812,7 @@ "properties": { "integration_key": { "type": "string", - "description": "新的集成 Key，旧 Key 立即失效；新 Key 也可通过 `/integration/list` 和 `/integration/info` 查询。", + "description": "新的集成 Key；原 Key 立即失效。", "example": "0123456789abcdef0123456789abcdef100" } } @@ -37688,6 +38519,317 @@ "description": "转换实际读到的邮件内容；无法解析邮件时为 `null`。" } } + }, + "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。" + } + } + }, + "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` 表示暂停接入。" + } + } + }, + "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": "集成类型对应的配置；响应中已保存的密钥类值以 `******` 返回。" + } + } + }, + "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。" + } + } + }, + "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 时保留，已脱敏或省略的密钥类字段保留原值。" + } + } } } } diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 50812101..0531e729 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -34477,7 +34477,7 @@ "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" } } @@ -37004,6 +37004,317 @@ "description": "What the conversion read from the email. `null` when the email could not be parsed." } } + }, + "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." + } + } + }, + "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." + } + } + }, + "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 `******`." + } + } + }, + "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." + } + } + }, + "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." + } + } } }, "securitySchemes": { @@ -74606,7 +74917,7 @@ "/integration/list": { "post": { "operationId": "integration-api-read-list", - "summary": "List integrations", + "summary": "List public integrations", "description": "List public integrations with their stored settings, decrypted keys, and edit permissions.", "tags": [ "On-call/Integrations" @@ -74615,7 +74926,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- `orderby` defaults to `created_at`; `plugin_type` sorts by the underlying plugin. Rows are ordered by `ref_id` first, so `orderby` applies within each `ref_id` group.\n- `plugin_type`, `status` and `category` accept comma-separated values; `ref_ids` values must start with `c_`, `a_` or `w_`; a `c_` filter is syntactically accepted but does not return channel-owned integrations.\n- With `is_my_team` set, results are limited to your teams and `team_ids` narrows that set further; when you belong to no team, or `team_ids` shares no team with yours, the list is empty.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Items include `settings`, `integration_key`, `plugin_id`, `account_id`, and the legacy `data_source_id` alias. Saved secret values in `settings` are returned as `******`; `integration_key` is returned as is.", "href": "/en/api-reference/on-call/integrations/integration-api-read-list", "metadata": { - "sidebarTitle": "List integrations" + "sidebarTitle": "List public integrations" } }, "responses": { @@ -74714,7 +75025,7 @@ "/integration/info": { "post": { "operationId": "integration-api-read-info", - "summary": "Get integration detail", + "summary": "Get public integration detail", "description": "Get a public integration with its stored settings and decrypted integration key.", "tags": [ "On-call/Integrations" @@ -74723,7 +75034,7 @@ "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- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Saved secret values in `settings` are returned as `******`, and unset ones stay empty. The integration key is returned as is.\n- An unknown ID, or the ID of a channel-owned integration, returns `ResourceNotFound`.", "href": "/en/api-reference/on-call/integrations/integration-api-read-info", "metadata": { - "sidebarTitle": "Get integration detail" + "sidebarTitle": "Get public integration detail" } }, "responses": { @@ -74810,7 +75121,7 @@ "/integration/create": { "post": { "operationId": "integration-api-write-create", - "summary": "Create integration", + "summary": "Create public integration", "description": "Create a public integration for a supported alert, change, IM, or webhook type.", "tags": [ "On-call/Integrations" @@ -74819,7 +75130,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `plugin_type` must be one of the types listed by `POST /integration/type/list` with `supports_api_create: true`; anything else returns `InvalidParameter`.\n- A type whose `status` is `disabled` returns `InvalidParameter`; a type not included in the account's plan returns `NoLicense`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- An omitted `integration_key` is generated automatically; a supplied key must satisfy the length, account suffix, and uniqueness checks.\n- With `is_test: true`, inspect `test.success`; an HTTP 200 response alone does not establish that the plugin test succeeded.\n- Every call is recorded in the account audit log.", "href": "/en/api-reference/on-call/integrations/integration-api-write-create", "metadata": { - "sidebarTitle": "Create integration" + "sidebarTitle": "Create public integration" } }, "responses": { @@ -74898,7 +75209,7 @@ "/integration/update": { "post": { "operationId": "integration-api-write-update", - "summary": "Update integration", + "summary": "Update public integration", "description": "Update an integration's name, description, team, or settings.", "tags": [ "On-call/Integrations" @@ -74907,7 +75218,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields you send are changed; omitted fields keep their current value.\n- Submitting `settings` replaces the configuration; known sensitive fields omitted or sent as `******` retain their value. Keeping a stored secret while changing where it is sent (such as `endpoint`, `url`, a database host or port, or an IM API base URL) is rejected, so send the secrets again with the new destination; `******` on a field with no stored value is rejected too. Send `headers: {}` to clear headers; use the integration type’s explicit empty value to clear a body.\n- Submit `settings` together with `is_test: true` to receive a plugin test result; secrets in the returned settings are masked the same way.\n- If another request changes the same integration's settings while this one is being processed, the call returns `RequestLocked`; retry it. A type no longer included in the account's plan returns `NoLicense`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.\n- Every call is recorded in the account audit log.", "href": "/en/api-reference/on-call/integrations/integration-api-write-update", "metadata": { - "sidebarTitle": "Update integration" + "sidebarTitle": "Update public integration" } }, "responses": { @@ -75005,7 +75316,7 @@ "/integration/delete": { "post": { "operationId": "integration-api-write-delete", - "summary": "Delete integration", + "summary": "Delete public integration", "description": "Delete an integration that nothing else references.", "tags": [ "On-call/Integrations" @@ -75014,7 +75325,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Deleting an integration that other objects still reference returns HTTP 400 with `error.code` = `ReferenceExist` and `data.refs` listing them.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.", "href": "/en/api-reference/on-call/integrations/integration-api-write-delete", "metadata": { - "sidebarTitle": "Delete integration" + "sidebarTitle": "Delete public integration" } }, "responses": { @@ -75078,7 +75389,7 @@ "/integration/enable": { "post": { "operationId": "integration-api-write-enable", - "summary": "Enable integration", + "summary": "Enable public integration", "description": "Re-enable a disabled integration so it accepts events again.", "tags": [ "On-call/Integrations" @@ -75087,7 +75398,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enabling an integration resumes its scheduled pull task and heartbeat, and requires the integration type to be available on the current plan.\n- Enabling an integration that is already enabled succeeds without change; the same holds for disabling a disabled one.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.", "href": "/en/api-reference/on-call/integrations/integration-api-write-enable", "metadata": { - "sidebarTitle": "Enable integration" + "sidebarTitle": "Enable public integration" } }, "responses": { @@ -75151,7 +75462,7 @@ "/integration/disable": { "post": { "operationId": "integration-api-write-disable", - "summary": "Disable integration", + "summary": "Disable public integration", "description": "Disable an integration without deleting its configuration.", "tags": [ "On-call/Integrations" @@ -75160,7 +75471,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Disabling stops event ingestion and pauses the scheduled pull task; settings are kept so the integration can be enabled again.\n- Enabling an integration that is already enabled succeeds without change; the same holds for disabling a disabled one.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.", "href": "/en/api-reference/on-call/integrations/integration-api-write-disable", "metadata": { - "sidebarTitle": "Disable integration" + "sidebarTitle": "Disable public integration" } }, "responses": { @@ -75224,7 +75535,7 @@ "/integration/key/rotate": { "post": { "operationId": "integration-api-write-rotate-key", - "summary": "Rotate integration key", + "summary": "Rotate public integration key", "description": "Issue a new integration key and invalidate the previous one.", "tags": [ "On-call/Integrations" @@ -75233,7 +75544,7 @@ "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- The previous key stops working immediately; after rotation, update the pushing side with the new key.\n- The new key can also be read from `/integration/list` and `/integration/info`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.\n- Every call is recorded in the account audit log.", "href": "/en/api-reference/on-call/integrations/integration-api-write-rotate-key", "metadata": { - "sidebarTitle": "Rotate integration key" + "sidebarTitle": "Rotate public integration key" } }, "responses": { @@ -76255,6 +76566,833 @@ } } } + }, + "/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** or **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- 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** or **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- 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- Query `POST /integration/type/list` and select a supported alert type for the dedicated integration.\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": [ @@ -76430,6 +77568,10 @@ { "description": "Create and manage RUM custom dashboards, their revision history and the trash.", "name": "RUM/Dashboards" + }, + { + "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 284630f0..0b6c2a67 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -34477,7 +34477,7 @@ "properties": { "integration_key": { "type": "string", - "description": "新的集成 Key，旧 Key 立即失效；新 Key 也可通过 `/integration/list` 和 `/integration/info` 查询。", + "description": "新的集成 Key；原 Key 立即失效。", "example": "0123456789abcdef0123456789abcdef100" } } @@ -37004,6 +37004,317 @@ "description": "转换实际读到的邮件内容；无法解析邮件时为 `null`。" } } + }, + "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。" + } + } + }, + "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` 表示暂停接入。" + } + } + }, + "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": "集成类型对应的配置；响应中已保存的密钥类值以 `******` 返回。" + } + } + }, + "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。" + } + } + }, + "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 时保留，已脱敏或省略的密钥类字段保留原值。" + } + } } }, "securitySchemes": { @@ -74606,7 +74917,7 @@ "/integration/list": { "post": { "operationId": "integration-api-read-list", - "summary": "查询集成列表", + "summary": "查询公共集成列表", "description": "查询公共集成列表，返回存储配置、解密 Key 与当前调用者的编辑权限。", "tags": [ "On-call/集成中心" @@ -74615,7 +74926,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- `orderby` 默认 `created_at`；`plugin_type` 按底层插件排序。结果先按 `ref_id` 升序排列，`orderby` 在相同 `ref_id` 内生效。\n- `plugin_type`、`status`、`category` 支持逗号分隔多值；`ref_ids` 每个值必须以 `c_`、`a_` 或 `w_` 开头；`c_` 过滤值通过格式校验，但不会返回协作空间专属集成。\n- 传入 `is_my_team` 时仅返回你所在团队的集成，`team_ids` 会在该范围内进一步收窄；你不属于任何团队，或 `team_ids` 与你的团队没有交集时，返回空列表。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 列表项包含 `settings`、`integration_key`、`plugin_id`、`account_id` 及旧 ID 别名 `data_source_id`。`settings` 中已保存的密钥类值返回 `******`，`integration_key` 按原值返回。", "href": "/zh/api-reference/on-call/integrations/integration-api-read-list", "metadata": { - "sidebarTitle": "查询集成列表" + "sidebarTitle": "查询公共集成列表" } }, "responses": { @@ -74714,7 +75025,7 @@ "/integration/info": { "post": { "operationId": "integration-api-read-info", - "summary": "查询集成详情", + "summary": "查看公共集成详情", "description": "查询单个公共集成详情，返回存储配置及解密后的集成 Key。", "tags": [ "On-call/集成中心" @@ -74723,7 +75034,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- `settings` 中已保存的密钥类值返回 `******`，未设置的保持为空；集成 Key 按原值返回。\n- ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。", "href": "/zh/api-reference/on-call/integrations/integration-api-read-info", "metadata": { - "sidebarTitle": "查询集成详情" + "sidebarTitle": "查看公共集成详情" } }, "responses": { @@ -74810,7 +75121,7 @@ "/integration/create": { "post": { "operationId": "integration-api-write-create", - "summary": "创建集成", + "summary": "创建公共集成", "description": "创建支持的告警源、变更源、IM 或 Webhook 类型公共集成。", "tags": [ "On-call/集成中心" @@ -74819,7 +75130,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `plugin_type` 必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型，否则返回 `InvalidParameter`。\n- `status` 为 `disabled` 的类型返回 `InvalidParameter`；当前套餐不包含的类型返回 `NoLicense`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 不传 `integration_key` 时自动生成；传入时须满足长度、账户后缀与唯一性校验。\n- 传 `is_test: true` 时请检查 `test.success`，不能只根据 HTTP 200 判断插件测试成功。\n- 每次调用都会记录到账户审计日志。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-create", "metadata": { - "sidebarTitle": "创建集成" + "sidebarTitle": "创建公共集成" } }, "responses": { @@ -74898,7 +75209,7 @@ "/integration/update": { "post": { "operationId": "integration-api-write-update", - "summary": "更新集成", + "summary": "更新公共集成", "description": "更新集成的名称、描述、所属团队或配置。", "tags": [ "On-call/集成中心" @@ -74907,7 +75218,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 仅发送的字段会被修改，未发送的字段保持原值。\n- 提交 `settings` 会替换配置；已识别的敏感字段不传或传 `******` 时保留原值。保留已存密钥的同时修改它的发送目标（如 `endpoint`、`url`、数据库主机或端口、IM 接口地址）会被拒绝，需要随新目标重新填写密钥；没有已存值的字段传 `******` 也会被拒绝。清空 Headers 请传 `headers: {}`；清空 Body 请使用该集成类型的显式空值。\n- 同时提交 `settings` 与 `is_test: true` 可获得插件测试结果，返回的 settings 中密钥同样返回 `******`。\n- 处理期间若有其他请求修改了同一集成的配置，本次调用返回 `RequestLocked`，重试即可。当前套餐已不包含该集成类型时返回 `NoLicense`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。\n- 每次调用都会记录到账户审计日志。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-update", "metadata": { - "sidebarTitle": "更新集成" + "sidebarTitle": "更新公共集成" } }, "responses": { @@ -75005,7 +75316,7 @@ "/integration/delete": { "post": { "operationId": "integration-api-write-delete", - "summary": "删除集成", + "summary": "删除公共集成", "description": "删除指定的集成。", "tags": [ "On-call/集成中心" @@ -75014,7 +75325,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 若该集成仍被其他对象引用，删除会返回 HTTP 400，`error.code` 为 `ReferenceExist`，`data.refs` 列出引用方。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-delete", "metadata": { - "sidebarTitle": "删除集成" + "sidebarTitle": "删除公共集成" } }, "responses": { @@ -75078,7 +75389,7 @@ "/integration/enable": { "post": { "operationId": "integration-api-write-enable", - "summary": "启用集成", + "summary": "启用公共集成", "description": "重新启用已禁用的集成，恢复接收事件。", "tags": [ "On-call/集成中心" @@ -75087,7 +75398,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 启用会恢复该集成的拉取任务与心跳，并要求当前套餐包含该集成类型。\n- 对已启用的集成调用启用、或对已禁用的集成调用禁用，会直接成功且不做变更。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-enable", "metadata": { - "sidebarTitle": "启用集成" + "sidebarTitle": "启用公共集成" } }, "responses": { @@ -75151,7 +75462,7 @@ "/integration/disable": { "post": { "operationId": "integration-api-write-disable", - "summary": "禁用集成", + "summary": "禁用公共集成", "description": "禁用集成，但保留其配置。", "tags": [ "On-call/集成中心" @@ -75160,7 +75471,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 禁用后停止接收事件并暂停定时拉取任务，配置保留，可再次启用。\n- 对已启用的集成调用启用、或对已禁用的集成调用禁用，会直接成功且不做变更。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-disable", "metadata": { - "sidebarTitle": "禁用集成" + "sidebarTitle": "禁用公共集成" } }, "responses": { @@ -75224,7 +75535,7 @@ "/integration/key/rotate": { "post": { "operationId": "integration-api-write-rotate-key", - "summary": "轮换集成 Key", + "summary": "轮换公共集成 Key", "description": "生成新的集成 Key，并使旧 Key 立即失效。", "tags": [ "On-call/集成中心" @@ -75233,7 +75544,7 @@ "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 旧 Key 会立即失效；轮换后请将推送端配置更新为新 Key。\n- 新 Key 也可通过 `/integration/list` 和 `/integration/info` 查询。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。\n- 每次调用都会记录到账户审计日志。", "href": "/zh/api-reference/on-call/integrations/integration-api-write-rotate-key", "metadata": { - "sidebarTitle": "轮换集成 Key" + "sidebarTitle": "轮换公共集成 Key" } }, "responses": { @@ -76255,6 +76566,833 @@ } } } + }, + "/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- 通过 `POST /integration/type/list` 查询类型；为专属集成选择支持的告警类型。\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": [ @@ -76430,6 +77568,10 @@ { "description": "创建和管理 RUM 自定义仪表盘及其版本历史与回收站。", "name": "RUM/仪表盘" + }, + { + "name": "On-call/专属集成", + "description": "管理各协作空间的专属告警集成。" } ] } diff --git a/docs.json b/docs.json index a77690c3..98e1dc1e 100644 --- a/docs.json +++ b/docs.json @@ -1679,6 +1679,38 @@ "source": "/channel/inhibit/rule/update", "destination": "/zh/api-reference/on-call/channels/channel-inhibit-rule-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" + }, { "source": "/channel/list", "destination": "/zh/api-reference/on-call/channels/channel-list" @@ -4170,18 +4202,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 /alert/email/preview" ] }, @@ -5948,18 +5998,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 /alert/email/preview" ] }, diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index bd5c061d..a221ebd4 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 **383** 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 **392** 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 through APP Key through query string. - + ### Incidents @@ -129,24 +129,46 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated th | POST | [`/alert/pipeline/preview`](/en/api-reference/on-call/alerts/alert-read-pipeline-preview) | Preview alert pipeline processing | | 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 with each saved secret as `******`, and the integration key as is. +`/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** or **Channels Manage**; writes require **Channels Manage**. You also need the corresponding access to the target channel; integration-center permissions do not grant access to this API group. + +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 | | POST | [`/alert/email/preview`](/en/api-reference/on-call/integrations/alert-read-email-preview) | Preview email-to-alert conversion | ### Schedules diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 7b21b448..008cafec 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 提供 **383** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 +Flashduty Open API 提供 **392** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 所有接口 URL 均以 `https://api.flashcat.cloud` 为 base，通过 query string 中的 APP Key 认证。 - + ### 故障管理 @@ -129,24 +129,46 @@ Flashduty Open API 提供 **383** 个接口，覆盖 On-call、Monitors、RUM、 | POST | [`/alert/pipeline/preview`](/zh/api-reference/on-call/alerts/alert-read-pipeline-preview) | 预览告警处理规则效果 | | 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/*` 管理协作空间专属集成。查询要求**协作空间查看**或**协作空间管理**，写入要求**协作空间管理**。您还须拥有目标空间对应的数据权限；集成中心权限不授予本组接口访问权。 + +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 | | POST | [`/alert/email/preview`](/zh/api-reference/on-call/integrations/alert-read-email-preview) | 预览邮件转告警效果 | ### 值班排班 From 5b9aff48a9e788ba8a3caad77b1e8e2a1279617b Mon Sep 17 00:00:00 2001 From: alick-liming Date: Tue, 27 Oct 2026 12:44:29 +0800 Subject: [PATCH 2/4] docs: make dedicated integration type lookup optional --- api-reference/on-call.openapi.en.json | 2 +- api-reference/on-call.openapi.zh.json | 2 +- api-reference/openapi.en.json | 2 +- api-reference/openapi.zh.json | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index 2d1e3caf..aa96f327 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -19814,7 +19814,7 @@ "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- Query `POST /integration/type/list` and select a supported alert type for the dedicated integration.\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.", + "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 supported alert types if you have **Integrations Read** permission.\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" diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index c6ae7f6c..c21c1702 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -19814,7 +19814,7 @@ "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- 通过 `POST /integration/type/list` 查询类型；为专属集成选择支持的告警类型。\n- 省略 `name` 时使用集成类型的默认名称；省略 `integration_key` 时自动生成。自带 Key 须为 35 个字符、匹配账户后缀，且未被其他集成使用。\n- 成功后返回 `integration_id` 和 `integration_key`；后续操作使用返回的 `integration_id`。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "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` 查询支持的告警类型。\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": "创建专属集成" diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 0531e729..0004f2b0 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -76765,7 +76765,7 @@ "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- Query `POST /integration/type/list` and select a supported alert type for the dedicated integration.\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.", + "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 supported alert types if you have **Integrations Read** permission.\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" diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 0b6c2a67..84a716d2 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -76765,7 +76765,7 @@ "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- 通过 `POST /integration/type/list` 查询类型；为专属集成选择支持的告警类型。\n- 省略 `name` 时使用集成类型的默认名称；省略 `integration_key` 时自动生成。自带 Key 须为 35 个字符、匹配账户后缀，且未被其他集成使用。\n- 成功后返回 `integration_id` 和 `integration_key`；后续操作使用返回的 `integration_id`。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "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` 查询支持的告警类型。\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": "创建专属集成" From e9b3793bbf689fc3b0846a5cbaccf1a3f801bfd2 Mon Sep 17 00:00:00 2001 From: alick-liming Date: Tue, 27 Oct 2026 14:43:13 +0800 Subject: [PATCH 3/4] docs: clarify shared integration catalog permissions --- api-reference/on-call.openapi.en.json | 8 ++++---- api-reference/on-call.openapi.zh.json | 8 ++++---- api-reference/openapi.en.json | 8 ++++---- api-reference/openapi.zh.json | 8 ++++---- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index aa96f327..edfc6a04 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -233,7 +233,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.\n- `category` values are not validated; an unknown value returns an empty list.", + "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" @@ -19625,7 +19625,7 @@ "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** or **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- 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.", + "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" @@ -19724,7 +19724,7 @@ "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** or **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- 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.", + "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" @@ -19814,7 +19814,7 @@ "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 supported alert types if you have **Integrations Read** permission.\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.", + "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" diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index c21c1702..65894d81 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -233,7 +233,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` 创建。\n- `category` 取值不做校验，未知值会返回空列表。", + "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": "查询集成类型列表" @@ -19625,7 +19625,7 @@ "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 不同。", + "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": "查询专属集成列表" @@ -19724,7 +19724,7 @@ "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 不同。", + "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": "查看专属集成详情" @@ -19814,7 +19814,7 @@ "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` 查询支持的告警类型。\n- 省略 `name` 时使用集成类型的默认名称；省略 `integration_key` 时自动生成。自带 Key 须为 35 个字符、匹配账户后缀，且未被其他集成使用。\n- 成功后返回 `integration_id` 和 `integration_key`；后续操作使用返回的 `integration_id`。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "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": "创建专属集成" diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 0004f2b0..b976beb0 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -74826,7 +74826,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.\n- `category` values are not validated; an unknown value returns an empty list.", + "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" @@ -76576,7 +76576,7 @@ "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** or **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- 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.", + "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" @@ -76675,7 +76675,7 @@ "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** or **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- 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.", + "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" @@ -76765,7 +76765,7 @@ "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 supported alert types if you have **Integrations Read** permission.\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.", + "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" diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 84a716d2..876a6bd6 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -74826,7 +74826,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` 创建。\n- `category` 取值不做校验，未知值会返回空列表。", + "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": "查询集成类型列表" @@ -76576,7 +76576,7 @@ "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 不同。", + "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": "查询专属集成列表" @@ -76675,7 +76675,7 @@ "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 不同。", + "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": "查看专属集成详情" @@ -76765,7 +76765,7 @@ "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` 查询支持的告警类型。\n- 省略 `name` 时使用集成类型的默认名称；省略 `integration_key` 时自动生成。自带 Key 须为 35 个字符、匹配账户后缀，且未被其他集成使用。\n- 成功后返回 `integration_id` 和 `integration_key`；后续操作使用返回的 `integration_id`。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "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": "创建专属集成" From 246cb1f7e113c68fa545fb8f4e2147843bb51b8c Mon Sep 17 00:00:00 2001 From: alick-liming Date: Tue, 27 Oct 2026 14:46:27 +0800 Subject: [PATCH 4/4] docs: align catalog with integration read permissions --- en/openapi/api-catalog.mdx | 2 +- zh/openapi/api-catalog.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index a221ebd4..48ef6a7e 100644 --- a/en/openapi/api-catalog.mdx +++ b/en/openapi/api-catalog.mdx @@ -147,7 +147,7 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated th ### Dedicated integrations -`/channel/integration/*` manages channel-owned dedicated integrations. Queries require **Channels Read** or **Channels Manage**; writes require **Channels Manage**. You also need the corresponding access to the target channel; integration-center permissions do not grant access to this API group. +`/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 `******`. diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 008cafec..fdc974ea 100644 --- a/zh/openapi/api-catalog.mdx +++ b/zh/openapi/api-catalog.mdx @@ -147,7 +147,7 @@ Flashduty Open API 提供 **392** 个接口，覆盖 On-call、Monitors、RUM、 ### 专属集成 -`/channel/integration/*` 管理协作空间专属集成。查询要求**协作空间查看**或**协作空间管理**，写入要求**协作空间管理**。您还须拥有目标空间对应的数据权限；集成中心权限不授予本组接口访问权。 +`/channel/integration/*` 管理协作空间专属集成。查询要求**协作空间查看**、**协作空间管理**或**集成中心查看**，写入要求**协作空间管理**。查询还要求目标空间可见，写入还要求目标空间的管理资格。共用的 `/integration/type/list` 类型目录也允许这三项读取权限；限制了接口范围的 App Key 须允许 `integration.api:read:typeList` 才能查询。 App Key 的 `api_scopes` 须允许对应操作。私有空间仅对账户所有者、Admin、空间创建者、所属团队和管理团队成员可见；写入按空间管理权限判断。查询返回完整集成 Key，配置中的已保存密钥类值返回 `******`。