Skip to content

docs(api): sync OpenAPI specs with backend API changes #461

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ysyneu wants to merge 1 commit into
base: feat/api-review-sync
Choose a base branch
from
Open

docs(api): sync OpenAPI specs with backend API changes #461

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 83 additions & 7 deletions api-reference/monitors.openapi.en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@
"Monitors/Data sources"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`.\n- `edge_cluster_name` specifies which Monitors edge cluster evaluates rules using this datasource.\n- For `elasticsearch`, set `payload.elasticsearch.deployment` to `cloud` or `self-managed`.\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `manage_team_id` and `readonly_team_ids` control team-level authorization: the managing team may update, delete, and view credentials; readonly teams may query and reference. Both are omitted by default (unrestricted). Setting `readonly_team_ids` requires `manage_team_id` in the same request, otherwise the call fails with `400`.\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`.\n- `edge_cluster_name` specifies which Monitors edge cluster evaluates rules using this datasource.\n- For `elasticsearch`, set `payload.elasticsearch.deployment` to `cloud` or `self-managed`.\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
"href": "/en/api-reference/monitors/data-sources/monit-datasource-write-create",
"metadata": {
"sidebarTitle": "Create datasource"
Expand Down Expand Up @@ -206,7 +206,7 @@
"Monitors/Data sources"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `manage_team_id` and `readonly_team_ids` follow presence semantics: omit to preserve the current value; explicit null clears it. Setting `readonly_team_ids` requires `manage_team_id` to remain set — the call fails with `400` when the merged state restricts query access without a managing team.\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
"href": "/en/api-reference/monitors/data-sources/monit-datasource-write-update",
"metadata": {
"sidebarTitle": "Update datasource"
Expand Down Expand Up @@ -1088,7 +1088,7 @@
"Monitors/Data sources"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type_ident` to return all types.\n- Sensitive credential fields (passwords, keys) are not returned in the list response.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Only datasources the caller may query are returned, and each item carries `my_perm` — the caller's permission level (`manage` or `readonly`). App key callers see every datasource with `my_perm` `manage`.\n- Omit `type_ident` to return all types.\n- Sensitive credential fields (passwords, keys) are not returned in the list response.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
"href": "/en/api-reference/monitors/data-sources/monit-datasource-read-list",
"metadata": {
"sidebarTitle": "List datasources"
Expand Down Expand Up @@ -1128,7 +1128,8 @@
"edge_cluster_name": "default",
"updated_at": 1712000000,
"payload": null,
"alerting_enabled": true
"alerting_enabled": true,
"my_perm": "manage"
}
]
}
Expand Down Expand Up @@ -3637,7 +3638,10 @@
"edge_cluster_name",
"updated_at",
"payload",
"alerting_enabled"
"alerting_enabled",
"manage_team_id",
"readonly_team_ids",
"creator_id"
],
"properties": {
"id": {
Expand Down Expand Up @@ -3694,6 +3698,33 @@
"alerting_enabled": {
"description": "Whether alert evaluation is allowed. Alerting also requires enabled=true and an alerting-capable type. Always false for diagnostic-only types; false does not block non-alerting queries or tools.",
"type": "boolean"
},
"manage_team_id": {
"type": [
"integer",
"null"
],
"format": "uint64",
"description": "Team ID allowed to manage this datasource (update, delete, view credentials). Null means no managing team, so any member with the Datasources Manage permission may manage it."
},
"readonly_team_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint64"
},
"description": "Team IDs additionally allowed to query and reference this datasource; the managing team always implies query access. Empty or null means unrestricted, so any member with the Datasources Read permission may query."
},
"creator_id": {
"type": [
"integer",
"null"
],
"format": "uint64",
"description": "ID of the user who created this datasource; the account ID when created through the API with an app key. Null for datasources created before this field was tracked."
}
}
},
Expand All @@ -3709,9 +3740,9 @@
},
"DataSourceListResponse": {
"type": "array",
"description": "List of datasources. The `payload` column is not read by this endpoint, so `payload` is `null` in every item.",
"description": "List of datasources. The `payload` column is not read by this endpoint, so `payload` is `null` in every item. Every item carries `my_perm`, the caller's permission level on that datasource.",
"items": {
"$ref": "#/components/schemas/DataSourceItem"
"$ref": "#/components/schemas/DataSourceListItem"
}
},
"DataSourceUpsertRequest": {
Expand Down Expand Up @@ -3763,6 +3794,27 @@
"description": "Whether this datasource may evaluate alerts. Omitted on create: true for alerting types, false for diagnostic-only types; omitted on update: preserve current value. null is invalid. redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka reject true. Disabling is rejected with conflict when enabled rules reference the datasource.",
"type": "boolean",
"x-flashduty-preserve-absence": true
},
"manage_team_id": {
"type": [
"integer",
"null"
],
"format": "uint64",
"description": "Team ID allowed to manage this datasource (update, delete, view credentials). Omit on create: no managing team, so any member with the Datasources Manage permission may manage it. On update, omit to preserve the current value; explicit null clears it. Setting `readonly_team_ids` requires a managing team: the request fails with `400` otherwise.",
"x-flashduty-preserve-absence": true
},
"readonly_team_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint64"
},
"description": "Team IDs additionally allowed to query and reference this datasource; the managing team always implies query access. Omit on create: unrestricted, so any member with the Datasources Read permission may query. On update, omit to preserve the current value; explicit null clears it back to unrestricted.",
"x-flashduty-preserve-absence": true
}
}
},
Expand Down Expand Up @@ -6362,6 +6414,30 @@
"expr",
"args"
]
},
"DataSourceListItem": {
"description": "A monitoring datasource as returned by the list endpoint: the full datasource row plus the caller's permission level on it.",
"allOf": [
{
"$ref": "#/components/schemas/DataSourceItem"
},
{
"type": "object",
"required": [
"my_perm"
],
"properties": {
"my_perm": {
"type": "string",
"enum": [
"manage",
"readonly"
],
"description": "The caller's permission level on this datasource: `manage` (update, delete, view credentials, query) or `readonly` (query and reference only). Callers authenticated with an app key always receive `manage`."
}
}
}
]
}
}
}
Expand Down
Loading
Loading