Clusters

Reference for the Clusters operations of the Spice Cloud Management API: list cluster monitors, create a cluster monitor, get a cluster monitor, update a cluster monitor, and delete a cluster monitor.

OpenAPIapi.spice.ai/openapi.json

List cluster monitors

GET/v1/clusters/{clusterId}/monitors

Lists live monitors for the cluster. Requires monitors:read and organization membership. The cluster ID is the cluster_name returned by GET /v1/clusters.

Path parameters

Name	Type	Required	Description
`clusterId`	string	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/clusters/<clusterId>/monitors" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Cluster monitors
400Bad Request
Invalid X-Org-Name header
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role
404Not Found
Cluster not found
500Internal Server Error
Internal server error

Create a cluster monitor

POST/v1/clusters/{clusterId}/monitors

Creates and provisions a cluster monitor. Requires monitors:write and organization admin privileges.

Path parameters

Name	Type	Required	Description
`clusterId`	string	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

namestringRequired
- Minimum length: 1
- Maximum length: 100
descriptionstring
- Maximum length: 500
templateIdstringRequired
- Allowed values: cluster_cpu, cluster_memory, cluster_availability
specobjectRequired
14 properties
- opstringRequired
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
- windowstring
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  - Default: 300
  - Minimum: 0
  - Maximum: 86400
- severitystring
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- columnstring
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- valuestring | number
- datasetsarray of string
  - Maximum items: 20
- conditionsarray of object
  - Maximum items: 20
  4 properties
  - datasetstringRequired
    Minimum length: 1
    Maximum length: 128
    Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
  - columnstringRequired
    Minimum length: 1
    Maximum length: 64
    Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
  - opstringRequired
    Allowed values: EQ, NEQ, GT, GEQ, LT, LEQ, CONTAINS, STARTS_WITH, ENDS_WITH, IS_NULL, IS_NOT_NULL
  - valuestring | number
- queryLanguagestring
  - Allowed values: cypher, gql
- returnFieldsarray of object
  Dataset fields returned by generated row-match queries. Include identity and all monitored fields.
  - Maximum items: 20
  2 properties
  - datasetstringRequired
  - columnsarray of stringRequired
    Minimum items: 1
    Maximum items: 1000
- querystring
  - Maximum length: 10000
- includeDetailsboolean
targetobject
Omit to email the caller, or the organization owner for a machine credential.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of object
Full destination set. When present, this replaces target. At most one sink of each type.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
recipientUserIdsarray of integer

Example request

curl -X POST "https://api.spice.ai/v1/clusters/<clusterId>/monitors" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "templateId": "cluster_cpu",
    "spec": {
      "op": "GT",
      "threshold": 0
    }
  }'

Responses

201Created
Monitor created
400Bad Request
Invalid request body or monitor configuration, or the cluster already has 20 live monitors
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role
404Not Found
Cluster not found
409Conflict
Duplicate monitor name or monitor deleted during creation
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: monitor_name_conflict, monitor_deleted_during_creation
413Content Too Large
Request body too large
422Unprocessable Content
Destination is unavailable
500Internal Server Error
Internal server error
502Bad Gateway
Monitor provisioning or cleanup failed. If cleanup is pending, the response includes the monitor ID for a retry with DELETE.

Get a cluster monitor

GET/v1/clusters/{clusterId}/monitors/{alertId}

Returns a live cluster monitor. Requires monitors:read and organization membership.

Path parameters

Name	Type	Required	Description
`clusterId`	string	Yes
`alertId`	string (uuid)	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/clusters/<clusterId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor
400Bad Request
Invalid monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role
404Not Found
Cluster or monitor not found
500Internal Server Error
Internal server error

Update a cluster monitor

PATCH/v1/clusters/{clusterId}/monitors/{alertId}

Updates the rule, destination, or status and reprovisions the monitor. Requires monitors:write and organization admin privileges.

Path parameters

Name	Type	Required	Description
`clusterId`	string	Yes
`alertId`	string (uuid)	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

namestring
- Minimum length: 1
- Maximum length: 100
descriptionstring | null
- Maximum length: 500
statusstring
- Allowed values: active, disabled
templateIdstring
- Allowed values: cluster_cpu, cluster_memory, cluster_availability
specobject
14 properties
- opstringRequired
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
- windowstring
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  - Default: 300
  - Minimum: 0
  - Maximum: 86400
- severitystring
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- columnstring
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- valuestring | number
- datasetsarray of string
  - Maximum items: 20
- conditionsarray of object
  - Maximum items: 20
  4 properties
  - datasetstringRequired
    Minimum length: 1
    Maximum length: 128
    Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
  - columnstringRequired
    Minimum length: 1
    Maximum length: 64
    Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
  - opstringRequired
    Allowed values: EQ, NEQ, GT, GEQ, LT, LEQ, CONTAINS, STARTS_WITH, ENDS_WITH, IS_NULL, IS_NOT_NULL
  - valuestring | number
- queryLanguagestring
  - Allowed values: cypher, gql
- returnFieldsarray of object
  Dataset fields returned by generated row-match queries. Include identity and all monitored fields.
  - Maximum items: 20
  2 properties
  - datasetstringRequired
  - columnsarray of stringRequired
    Minimum items: 1
    Maximum items: 1000
- querystring
  - Maximum length: 10000
- includeDetailsboolean
targetobject
Omit to keep the existing destination.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of object
Full destination set. When present, replaces the stored sinks. Omit to keep them.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
recipientUserIdsarray of integer

Example request

curl -X PATCH "https://api.spice.ai/v1/clusters/<clusterId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "status": "active",
    "templateId": "cluster_cpu",
    "spec": {
      "op": "GT",
      "threshold": 0
    },
    "target": {
      "type": "email"
    },
    "targets": [
      {
        "type": "email"
      }
    ],
    "recipientUserIds": [
      0
    ]
  }'

Responses

200OK
Monitor updated
400Bad Request
Invalid request or monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role
404Not Found
Cluster or monitor not found
409Conflict
Duplicate monitor name or monitor changed during update
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: monitor_name_conflict, monitor_changed
413Content Too Large
Request body too large
422Unprocessable Content
Destination is unavailable
500Internal Server Error
Internal server error
502Bad Gateway
Monitor backend update failed; the saved rule may be pending and the request can be retried

Delete a cluster monitor

DELETE/v1/clusters/{clusterId}/monitors/{alertId}

Soft-deletes the monitor and retires its backend. Requires monitors:write and organization admin privileges. Retry to finish pending cleanup.

Path parameters

Name	Type	Required	Description
`clusterId`	string	Yes
`alertId`	string (uuid)	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl -X DELETE "https://api.spice.ai/v1/clusters/<clusterId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor deleted
400Bad Request
Invalid monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role
404Not Found
Cluster or monitor not found
500Internal Server Error
Internal server error
502Bad Gateway
Backend cleanup failed

List cluster monitors

GET/v1/orgs/{orgId}/clusters/{clusterId}/monitors

The org is orgId in the path. Lists live monitors for the cluster. Requires monitors:read and organization membership. The cluster ID is the cluster_name returned by GET /v1/clusters.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`clusterId`	string	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/orgs/<orgId>/clusters/<clusterId>/monitors" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Cluster monitors
400Bad Request
Invalid X-Org-Name header. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Cluster not found
500Internal Server Error
Internal server error

Create a cluster monitor

POST/v1/orgs/{orgId}/clusters/{clusterId}/monitors

The org is orgId in the path. Creates and provisions a cluster monitor. Requires monitors:write and organization admin privileges.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`clusterId`	string	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

namestringRequired
- Minimum length: 1
- Maximum length: 100
descriptionstring
- Maximum length: 500
templateIdstringRequired
- Allowed values: cluster_cpu, cluster_memory, cluster_availability
specobjectRequired
14 properties
- opstringRequired
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
- windowstring
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  - Default: 300
  - Minimum: 0
  - Maximum: 86400
- severitystring
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- columnstring
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- valuestring | number
- datasetsarray of string
  - Maximum items: 20
- conditionsarray of object
  - Maximum items: 20
  4 properties
  - datasetstringRequired
    Minimum length: 1
    Maximum length: 128
    Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
  - columnstringRequired
    Minimum length: 1
    Maximum length: 64
    Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
  - opstringRequired
    Allowed values: EQ, NEQ, GT, GEQ, LT, LEQ, CONTAINS, STARTS_WITH, ENDS_WITH, IS_NULL, IS_NOT_NULL
  - valuestring | number
- queryLanguagestring
  - Allowed values: cypher, gql
- returnFieldsarray of object
  Dataset fields returned by generated row-match queries. Include identity and all monitored fields.
  - Maximum items: 20
  2 properties
  - datasetstringRequired
  - columnsarray of stringRequired
    Minimum items: 1
    Maximum items: 1000
- querystring
  - Maximum length: 10000
- includeDetailsboolean
targetobject
Omit to email the caller, or the organization owner for a machine credential.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of object
Full destination set. When present, this replaces target. At most one sink of each type.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
recipientUserIdsarray of integer

Example request

curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/clusters/<clusterId>/monitors" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "templateId": "cluster_cpu",
    "spec": {
      "op": "GT",
      "threshold": 0
    }
  }'

Responses

201Created
Monitor created
400Bad Request
Invalid request body or monitor configuration, or the cluster already has 20 live monitors. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Cluster not found
409Conflict
Duplicate monitor name or monitor deleted during creation
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: monitor_name_conflict, monitor_deleted_during_creation
413Content Too Large
Request body too large
422Unprocessable Content
Destination is unavailable
500Internal Server Error
Internal server error
502Bad Gateway
Monitor provisioning or cleanup failed. If cleanup is pending, the response includes the monitor ID for a retry with DELETE.

Get a cluster monitor

GET/v1/orgs/{orgId}/clusters/{clusterId}/monitors/{alertId}

The org is orgId in the path. Returns a live cluster monitor. Requires monitors:read and organization membership.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`clusterId`	string	Yes
`alertId`	string (uuid)	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/orgs/<orgId>/clusters/<clusterId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor
400Bad Request
Invalid monitor ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Cluster or monitor not found
500Internal Server Error
Internal server error

Update a cluster monitor

PATCH/v1/orgs/{orgId}/clusters/{clusterId}/monitors/{alertId}

The org is orgId in the path. Updates the rule, destination, or status and reprovisions the monitor. Requires monitors:write and organization admin privileges.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`clusterId`	string	Yes
`alertId`	string (uuid)	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Required

application/json

namestring
- Minimum length: 1
- Maximum length: 100
descriptionstring | null
- Maximum length: 500
statusstring
- Allowed values: active, disabled
templateIdstring
- Allowed values: cluster_cpu, cluster_memory, cluster_availability
specobject
14 properties
- opstringRequired
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
- windowstring
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  - Default: 300
  - Minimum: 0
  - Maximum: 86400
- severitystring
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- columnstring
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- valuestring | number
- datasetsarray of string
  - Maximum items: 20
- conditionsarray of object
  - Maximum items: 20
  4 properties
  - datasetstringRequired
    Minimum length: 1
    Maximum length: 128
    Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
  - columnstringRequired
    Minimum length: 1
    Maximum length: 64
    Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
  - opstringRequired
    Allowed values: EQ, NEQ, GT, GEQ, LT, LEQ, CONTAINS, STARTS_WITH, ENDS_WITH, IS_NULL, IS_NOT_NULL
  - valuestring | number
- queryLanguagestring
  - Allowed values: cypher, gql
- returnFieldsarray of object
  Dataset fields returned by generated row-match queries. Include identity and all monitored fields.
  - Maximum items: 20
  2 properties
  - datasetstringRequired
  - columnsarray of stringRequired
    Minimum items: 1
    Maximum items: 1000
- querystring
  - Maximum length: 10000
- includeDetailsboolean
targetobject
Omit to keep the existing destination.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of object
Full destination set. When present, replaces the stored sinks. Omit to keep them.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
recipientUserIdsarray of integer

Example request

curl -X PATCH "https://api.spice.ai/v1/orgs/<orgId>/clusters/<clusterId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "status": "active",
    "templateId": "cluster_cpu",
    "spec": {
      "op": "GT",
      "threshold": 0
    },
    "target": {
      "type": "email"
    },
    "targets": [
      {
        "type": "email"
      }
    ],
    "recipientUserIds": [
      0
    ]
  }'

Responses

200OK
Monitor updated
400Bad Request
Invalid request or monitor ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Cluster or monitor not found
409Conflict
Duplicate monitor name or monitor changed during update
application/json
- errorstringRequired
- codestringRequired
  - Allowed values: monitor_name_conflict, monitor_changed
413Content Too Large
Request body too large
422Unprocessable Content
Destination is unavailable
500Internal Server Error
Internal server error
502Bad Gateway
Monitor backend update failed; the saved rule may be pending and the request can be retried

Delete a cluster monitor

DELETE/v1/orgs/{orgId}/clusters/{clusterId}/monitors/{alertId}

The org is orgId in the path. Soft-deletes the monitor and retires its backend. Requires monitors:write and organization admin privileges. Retry to finish pending cleanup.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`clusterId`	string	Yes
`alertId`	string (uuid)	Yes

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl -X DELETE "https://api.spice.ai/v1/orgs/<orgId>/clusters/<clusterId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor deleted
400Bad Request
Invalid monitor ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Cluster or monitor not found
500Internal Server Error
Internal server error
502Bad Gateway
Backend cleanup failed