Monitors

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

OpenAPIapi.spice.ai/openapi.json

List project monitors

GET/v1/projects/{projectId}/monitors

Returns the project's monitors. Requires monitors:read. Monitors on a project that is not managed, or on a template that is not available to the organization, are omitted. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project

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/projects/<projectId>/monitors" \
  -H "Authorization: Bearer <token>"

Responses

200OK
List of project monitors
application/json
- monitorsarray of object
  18 properties
  idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
  org_idintegerRequired
  Organization that owns the project
  app_idintegerRequired
  Project the monitor or reaction belongs to
  created_byinteger | nullRequired
  User who created it, when it was created by a user credential
  namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
  descriptionstring | nullRequired
  kindstringRequired
  The monitors endpoints only ever return runtime.
  Value: runtime
  statusstringRequired
  Whether it is evaluating
  Allowed values: active, disabled
  template_idstringRequired
  Template it was created from
  specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
  targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
  targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  Minimum items: 1
  Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
  recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
  last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
  last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
  created_atstring (date-time)Required
  updated_atstring (date-time)Required
  evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  Value: cpu_limit_missing
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
500Internal Server Error
Internal server error

Create a project monitor

POST/v1/projects/{projectId}/monitors

Creates a project monitor from a runtime template. Requires monitors:write. A monitor evaluates a runtime metric on a schedule and fires when the comparison holds; to fire on matching dataset rows instead, create a data reaction at /v1/projects/{projectId}/reactions.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project

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
Display name. Unique, case-insensitively, among the project's live monitors and data reactions — a collision answers 409.
- Minimum length: 1
- Maximum length: 100
descriptionstring
- Maximum length: 500
kindstring
Optional assertion that templateId names a monitor. A value that disagrees with the template is refused rather than ignored; omit it and the template decides.
- Value: runtime
templateIdstringRequired
The runtime template the monitor evaluates. query_latency_p95 is retained for existing monitors but cannot be used to create new ones; use query_latency_p99. container_cpu is available only on managed projects with a defined CPU limit. A data-reaction template is refused here — create those at /v1/projects/{projectId}/reactions.
- Allowed values: query_failures, query_latency_p95, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, memory_working_set, container_cpu, dataset_status, instance_health
specobjectRequired
Monitor parameters. Which properties apply is decided by templateId — each property below names the templates that read it, and a property no monitor template reads is stored rather than rejected. spec is shared with data reactions, so it accepts their properties too; model is the one that is refused rather than stored.
15 properties
- opstringRequired
  Comparison applied to the metric. Required on every monitor spec. instance_health requires GT.
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
  Value compared against the metric. HTTP failure monitors count estimated 5xx responses in the selected window. Rate-based conditions use responses per second. dataset_refresh_errors counts refresh errors in the window. query_latency_p99 uses milliseconds. memory_working_set uses percent of the instance memory limit. A stored memory threshold above 1000 uses bytes. container_cpu uses percent of the defined CPU limit. dataset_status compares load-state numbers. instance_health requires 0. Every monitor spec requires a threshold.
- windowstring
  Range evaluated by query_failures, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, and container_cpu. memory_working_set and dataset_status read the current value and ignore this field. instance_health reads current failure states and uses a fixed five-minute eviction observation window, independent of this field. Data reactions store this field but do not use it.
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  Sustain delay in seconds. Failure monitors default to 0. Other monitors default to 300. Explicit values are preserved.
  - Minimum: 0
  - Maximum: 86400
- severitystring
  Severity the monitor fires at. Recorded on each monitor event and carried into the email or webhook notification.
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  Read by dataset_status, which watches this one dataset. Omit it to match any dataset in the project.
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- includeDetailsboolean
  When true, the recorded event and the notification may carry a details string quoted from the firing payload when it contains useful information. Off by default, because that payload may be sensitive. A notification's own summary, description, and observed value do not depend on it.
- valuestring | number
  Read by dataset_status for notification wording only, and only when threshold is not one of the state numbers above and this names a state. It never changes what the monitor evaluates. Otherwise a data-reaction property.
- columnstring
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying both column and dataset has its notification describe that row predicate instead of its own metric comparison.
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- datasetsarray of string
  A data-reaction property that no monitor reads.
  - Maximum items: 20
- conditionsarray of object
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying conditions has its notification describe them instead of its own metric comparison. IS_NULL and IS_NOT_NULL omit value.
  - 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
    Required except for IS_NULL and IS_NOT_NULL.
- 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
- queryLanguagestring
  A data-reaction property that no monitor reads.
  - Allowed values: cypher, gql
- querystring
  A data-reaction property that no monitor reads.
  - Maximum length: 10000
- modelobject
  Model transform. Data reactions only — sending it with a monitor template is refused with 400, not ignored.
  2 properties
  - modelstringRequired
    Minimum length: 1
    Maximum length: 128
  - instructionsstringRequired
    Minimum length: 1
    Maximum length: 4000
targetobject
Notification sink. Omit it to email the user the credential belongs to; a machine credential has no user, so its monitors email the organization owner.
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 and is the complete list. 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
Legacy spelling of target.recipientUserIds, read only when an email target omits its own.
- Maximum items: 50

Example request

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

Responses

201Created
Monitor created
application/json
A project monitor, as returned by the list, get, create and update operations. Every required property is always present; a nullable one carries null rather than being omitted. evaluation_unavailable_reason is present only when an Instance CPU monitor has lost its CPU limit. Fields not listed here are internal to the platform and are not part of the contract.
- idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
- org_idintegerRequired
  Organization that owns the project
- app_idintegerRequired
  Project the monitor or reaction belongs to
- created_byinteger | nullRequired
  User who created it, when it was created by a user credential
- namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
- descriptionstring | nullRequired
- kindstringRequired
  The monitors endpoints only ever return runtime.
  - Value: runtime
- statusstringRequired
  Whether it is evaluating
  - Allowed values: active, disabled
- template_idstringRequired
  Template it was created from
- specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
- targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  - Minimum items: 1
  - Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
- last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
- last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
- created_atstring (date-time)Required
- updated_atstring (date-time)Required
- evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  - Value: cpu_limit_missing
400Bad Request
Invalid request body or project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found, or the template is not available for this project (code is monitor_template_unavailable). Monitors run only on managed projects, and only released templates are available unless the organization has early access.
409Conflict
A live monitor or data reaction in this project already has this name
413Content Too Large
Request body too large
422Unprocessable Content
Slack is not connected for the organization
500Internal Server Error
Internal server error
502Bad Gateway
Failed to provision monitor

Get a project monitor

GET/v1/projects/{projectId}/monitors/{alertId}

Returns a single project monitor. Requires monitors:read. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Path parameters

Name	Type	Required	Description
`projectId`	integer	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/projects/<projectId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor
application/json
A project monitor, as returned by the list, get, create and update operations. Every required property is always present; a nullable one carries null rather than being omitted. evaluation_unavailable_reason is present only when an Instance CPU monitor has lost its CPU limit. Fields not listed here are internal to the platform and are not part of the contract.
- idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
- org_idintegerRequired
  Organization that owns the project
- app_idintegerRequired
  Project the monitor or reaction belongs to
- created_byinteger | nullRequired
  User who created it, when it was created by a user credential
- namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
- descriptionstring | nullRequired
- kindstringRequired
  The monitors endpoints only ever return runtime.
  - Value: runtime
- statusstringRequired
  Whether it is evaluating
  - Allowed values: active, disabled
- template_idstringRequired
  Template it was created from
- specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
- targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  - Minimum items: 1
  - Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
- last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
- last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
- created_atstring (date-time)Required
- updated_atstring (date-time)Required
- evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  - Value: cpu_limit_missing
400Bad Request
Invalid project or monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project or monitor not found
500Internal Server Error
Internal server error

Update a project monitor

PATCH/v1/projects/{projectId}/monitors/{alertId}

Updates a project monitor. Requires monitors:write and organization admin privileges.

Path parameters

Name	Type	Required	Description
`projectId`	integer	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
specobject
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
recipientUserIdsarray of integer

Example request

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

Responses

200OK
Monitor updated
400Bad Request
Invalid request or monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role
404Not Found
Project or monitor not found
409Conflict
Duplicate monitor name or monitor changed during update
413Content Too Large
Request body too large
422Unprocessable Content
Destination is unavailable or project configuration is incomplete
500Internal Server Error
Internal server error
502Bad Gateway
Monitor backend update failed

Delete a project monitor

DELETE/v1/projects/{projectId}/monitors/{alertId}

Soft-deletes a project monitor and tears down the monitor it provisioned. Requires monitors:write.

Path parameters

Name	Type	Required	Description
`projectId`	integer	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/projects/<projectId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor deleted
400Bad Request
Invalid project or monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project or monitor not found
500Internal Server Error
Internal server error
502Bad Gateway
Failed to delete monitor

List project monitors

GET/v1/orgs/{orgId}/projects/{projectId}/monitors

The org is orgId in the path. Returns the project's monitors. Requires monitors:read. Monitors on a project that is not managed, or on a template that is not available to the organization, are omitted. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project

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>/projects/<projectId>/monitors" \
  -H "Authorization: Bearer <token>"

Responses

200OK
List of project monitors
application/json
- monitorsarray of object
  18 properties
  idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
  org_idintegerRequired
  Organization that owns the project
  app_idintegerRequired
  Project the monitor or reaction belongs to
  created_byinteger | nullRequired
  User who created it, when it was created by a user credential
  namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
  descriptionstring | nullRequired
  kindstringRequired
  The monitors endpoints only ever return runtime.
  Value: runtime
  statusstringRequired
  Whether it is evaluating
  Allowed values: active, disabled
  template_idstringRequired
  Template it was created from
  specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
  targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
  targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  Minimum items: 1
  Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
  recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
  last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
  last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
  created_atstring (date-time)Required
  updated_atstring (date-time)Required
  evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  Value: cpu_limit_missing
400Bad Request
Invalid project 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. 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
Project not found
500Internal Server Error
Internal server error

Create a project monitor

POST/v1/orgs/{orgId}/projects/{projectId}/monitors

The org is orgId in the path. Creates a project monitor from a runtime template. Requires monitors:write. A monitor evaluates a runtime metric on a schedule and fires when the comparison holds; to fire on matching dataset rows instead, create a data reaction at /v1/projects/{projectId}/reactions.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project

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
Display name. Unique, case-insensitively, among the project's live monitors and data reactions — a collision answers 409.
- Minimum length: 1
- Maximum length: 100
descriptionstring
- Maximum length: 500
kindstring
Optional assertion that templateId names a monitor. A value that disagrees with the template is refused rather than ignored; omit it and the template decides.
- Value: runtime
templateIdstringRequired
The runtime template the monitor evaluates. query_latency_p95 is retained for existing monitors but cannot be used to create new ones; use query_latency_p99. container_cpu is available only on managed projects with a defined CPU limit. A data-reaction template is refused here — create those at /v1/projects/{projectId}/reactions.
- Allowed values: query_failures, query_latency_p95, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, memory_working_set, container_cpu, dataset_status, instance_health
specobjectRequired
Monitor parameters. Which properties apply is decided by templateId — each property below names the templates that read it, and a property no monitor template reads is stored rather than rejected. spec is shared with data reactions, so it accepts their properties too; model is the one that is refused rather than stored.
15 properties
- opstringRequired
  Comparison applied to the metric. Required on every monitor spec. instance_health requires GT.
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
  Value compared against the metric. HTTP failure monitors count estimated 5xx responses in the selected window. Rate-based conditions use responses per second. dataset_refresh_errors counts refresh errors in the window. query_latency_p99 uses milliseconds. memory_working_set uses percent of the instance memory limit. A stored memory threshold above 1000 uses bytes. container_cpu uses percent of the defined CPU limit. dataset_status compares load-state numbers. instance_health requires 0. Every monitor spec requires a threshold.
- windowstring
  Range evaluated by query_failures, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, and container_cpu. memory_working_set and dataset_status read the current value and ignore this field. instance_health reads current failure states and uses a fixed five-minute eviction observation window, independent of this field. Data reactions store this field but do not use it.
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  Sustain delay in seconds. Failure monitors default to 0. Other monitors default to 300. Explicit values are preserved.
  - Minimum: 0
  - Maximum: 86400
- severitystring
  Severity the monitor fires at. Recorded on each monitor event and carried into the email or webhook notification.
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  Read by dataset_status, which watches this one dataset. Omit it to match any dataset in the project.
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- includeDetailsboolean
  When true, the recorded event and the notification may carry a details string quoted from the firing payload when it contains useful information. Off by default, because that payload may be sensitive. A notification's own summary, description, and observed value do not depend on it.
- valuestring | number
  Read by dataset_status for notification wording only, and only when threshold is not one of the state numbers above and this names a state. It never changes what the monitor evaluates. Otherwise a data-reaction property.
- columnstring
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying both column and dataset has its notification describe that row predicate instead of its own metric comparison.
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- datasetsarray of string
  A data-reaction property that no monitor reads.
  - Maximum items: 20
- conditionsarray of object
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying conditions has its notification describe them instead of its own metric comparison. IS_NULL and IS_NOT_NULL omit value.
  - 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
    Required except for IS_NULL and IS_NOT_NULL.
- 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
- queryLanguagestring
  A data-reaction property that no monitor reads.
  - Allowed values: cypher, gql
- querystring
  A data-reaction property that no monitor reads.
  - Maximum length: 10000
- modelobject
  Model transform. Data reactions only — sending it with a monitor template is refused with 400, not ignored.
  2 properties
  - modelstringRequired
    Minimum length: 1
    Maximum length: 128
  - instructionsstringRequired
    Minimum length: 1
    Maximum length: 4000
targetobject
Notification sink. Omit it to email the user the credential belongs to; a machine credential has no user, so its monitors email the organization owner.
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 and is the complete list. 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
Legacy spelling of target.recipientUserIds, read only when an email target omits its own.
- Maximum items: 50

Example request

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

Responses

201Created
Monitor created
application/json
A project monitor, as returned by the list, get, create and update operations. Every required property is always present; a nullable one carries null rather than being omitted. evaluation_unavailable_reason is present only when an Instance CPU monitor has lost its CPU limit. Fields not listed here are internal to the platform and are not part of the contract.
- idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
- org_idintegerRequired
  Organization that owns the project
- app_idintegerRequired
  Project the monitor or reaction belongs to
- created_byinteger | nullRequired
  User who created it, when it was created by a user credential
- namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
- descriptionstring | nullRequired
- kindstringRequired
  The monitors endpoints only ever return runtime.
  - Value: runtime
- statusstringRequired
  Whether it is evaluating
  - Allowed values: active, disabled
- template_idstringRequired
  Template it was created from
- specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
- targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  - Minimum items: 1
  - Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
- last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
- last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
- created_atstring (date-time)Required
- updated_atstring (date-time)Required
- evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  - Value: cpu_limit_missing
400Bad Request
Invalid request body or project 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. 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
Project not found, or the template is not available for this project (code is monitor_template_unavailable). Monitors run only on managed projects, and only released templates are available unless the organization has early access.
409Conflict
A live monitor or data reaction in this project already has this name
413Content Too Large
Request body too large
422Unprocessable Content
Slack is not connected for the organization
500Internal Server Error
Internal server error
502Bad Gateway
Failed to provision monitor

Get a project monitor

GET/v1/orgs/{orgId}/projects/{projectId}/monitors/{alertId}

The org is orgId in the path. Returns a single project monitor. Requires monitors:read. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	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>/projects/<projectId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor
application/json
A project monitor, as returned by the list, get, create and update operations. Every required property is always present; a nullable one carries null rather than being omitted. evaluation_unavailable_reason is present only when an Instance CPU monitor has lost its CPU limit. Fields not listed here are internal to the platform and are not part of the contract.
- idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
- org_idintegerRequired
  Organization that owns the project
- app_idintegerRequired
  Project the monitor or reaction belongs to
- created_byinteger | nullRequired
  User who created it, when it was created by a user credential
- namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
- descriptionstring | nullRequired
- kindstringRequired
  The monitors endpoints only ever return runtime.
  - Value: runtime
- statusstringRequired
  Whether it is evaluating
  - Allowed values: active, disabled
- template_idstringRequired
  Template it was created from
- specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
- targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  - Minimum items: 1
  - Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
- last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
- last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
- created_atstring (date-time)Required
- updated_atstring (date-time)Required
- evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  - Value: cpu_limit_missing
400Bad Request
Invalid project 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. 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
Project or monitor not found
500Internal Server Error
Internal server error

Update a project monitor

PATCH/v1/orgs/{orgId}/projects/{projectId}/monitors/{alertId}

The org is orgId in the path. Updates a project 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`
`projectId`	integer	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
specobject
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
recipientUserIdsarray of integer

Example request

curl -X PATCH "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "status": "active",
    "templateId": "string",
    "spec": {},
    "target": {
      "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
Project or monitor not found
409Conflict
Duplicate monitor name or monitor changed during update
413Content Too Large
Request body too large
422Unprocessable Content
Destination is unavailable or project configuration is incomplete
500Internal Server Error
Internal server error
502Bad Gateway
Monitor backend update failed

Delete a project monitor

DELETE/v1/orgs/{orgId}/projects/{projectId}/monitors/{alertId}

The org is orgId in the path. Soft-deletes a project monitor and tears down the monitor it provisioned. Requires monitors:write.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	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>/projects/<projectId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor deleted
400Bad Request
Invalid project 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. 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
Project or monitor not found
500Internal Server Error
Internal server error
502Bad Gateway
Failed to delete monitor

List project monitors

GET/v1/apps/{appId}/monitorsDeprecated

Legacy alias of /v1/projects/{projectId}/monitors — projects were previously called apps. Returns the project's monitors. Requires monitors:read. Monitors on a project that is not managed, or on a template that is not available to the organization, are omitted. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project

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/apps/<appId>/monitors" \
  -H "Authorization: Bearer <token>"

Responses

200OK
List of project monitors
application/json
- monitorsarray of object
  18 properties
  idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
  org_idintegerRequired
  Organization that owns the project
  app_idintegerRequired
  Project the monitor or reaction belongs to
  created_byinteger | nullRequired
  User who created it, when it was created by a user credential
  namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
  descriptionstring | nullRequired
  kindstringRequired
  The monitors endpoints only ever return runtime.
  Value: runtime
  statusstringRequired
  Whether it is evaluating
  Allowed values: active, disabled
  template_idstringRequired
  Template it was created from
  specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
  targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
  targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  Minimum items: 1
  Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
  recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
  last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
  last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
  created_atstring (date-time)Required
  updated_atstring (date-time)Required
  evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  Value: cpu_limit_missing
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
500Internal Server Error
Internal server error

Create a project monitor

POST/v1/apps/{appId}/monitorsDeprecated

Legacy alias of /v1/projects/{projectId}/monitors — projects were previously called apps. Creates a project monitor from a runtime template. Requires monitors:write. A monitor evaluates a runtime metric on a schedule and fires when the comparison holds; to fire on matching dataset rows instead, create a data reaction at /v1/projects/{projectId}/reactions.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project

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
Display name. Unique, case-insensitively, among the project's live monitors and data reactions — a collision answers 409.
- Minimum length: 1
- Maximum length: 100
descriptionstring
- Maximum length: 500
kindstring
Optional assertion that templateId names a monitor. A value that disagrees with the template is refused rather than ignored; omit it and the template decides.
- Value: runtime
templateIdstringRequired
The runtime template the monitor evaluates. query_latency_p95 is retained for existing monitors but cannot be used to create new ones; use query_latency_p99. container_cpu is available only on managed projects with a defined CPU limit. A data-reaction template is refused here — create those at /v1/projects/{projectId}/reactions.
- Allowed values: query_failures, query_latency_p95, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, memory_working_set, container_cpu, dataset_status, instance_health
specobjectRequired
Monitor parameters. Which properties apply is decided by templateId — each property below names the templates that read it, and a property no monitor template reads is stored rather than rejected. spec is shared with data reactions, so it accepts their properties too; model is the one that is refused rather than stored.
15 properties
- opstringRequired
  Comparison applied to the metric. Required on every monitor spec. instance_health requires GT.
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
  Value compared against the metric. HTTP failure monitors count estimated 5xx responses in the selected window. Rate-based conditions use responses per second. dataset_refresh_errors counts refresh errors in the window. query_latency_p99 uses milliseconds. memory_working_set uses percent of the instance memory limit. A stored memory threshold above 1000 uses bytes. container_cpu uses percent of the defined CPU limit. dataset_status compares load-state numbers. instance_health requires 0. Every monitor spec requires a threshold.
- windowstring
  Range evaluated by query_failures, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, and container_cpu. memory_working_set and dataset_status read the current value and ignore this field. instance_health reads current failure states and uses a fixed five-minute eviction observation window, independent of this field. Data reactions store this field but do not use it.
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  Sustain delay in seconds. Failure monitors default to 0. Other monitors default to 300. Explicit values are preserved.
  - Minimum: 0
  - Maximum: 86400
- severitystring
  Severity the monitor fires at. Recorded on each monitor event and carried into the email or webhook notification.
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  Read by dataset_status, which watches this one dataset. Omit it to match any dataset in the project.
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- includeDetailsboolean
  When true, the recorded event and the notification may carry a details string quoted from the firing payload when it contains useful information. Off by default, because that payload may be sensitive. A notification's own summary, description, and observed value do not depend on it.
- valuestring | number
  Read by dataset_status for notification wording only, and only when threshold is not one of the state numbers above and this names a state. It never changes what the monitor evaluates. Otherwise a data-reaction property.
- columnstring
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying both column and dataset has its notification describe that row predicate instead of its own metric comparison.
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- datasetsarray of string
  A data-reaction property that no monitor reads.
  - Maximum items: 20
- conditionsarray of object
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying conditions has its notification describe them instead of its own metric comparison. IS_NULL and IS_NOT_NULL omit value.
  - 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
    Required except for IS_NULL and IS_NOT_NULL.
- 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
- queryLanguagestring
  A data-reaction property that no monitor reads.
  - Allowed values: cypher, gql
- querystring
  A data-reaction property that no monitor reads.
  - Maximum length: 10000
- modelobject
  Model transform. Data reactions only — sending it with a monitor template is refused with 400, not ignored.
  2 properties
  - modelstringRequired
    Minimum length: 1
    Maximum length: 128
  - instructionsstringRequired
    Minimum length: 1
    Maximum length: 4000
targetobject
Notification sink. Omit it to email the user the credential belongs to; a machine credential has no user, so its monitors email the organization owner.
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 and is the complete list. 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
Legacy spelling of target.recipientUserIds, read only when an email target omits its own.
- Maximum items: 50

Example request

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

Responses

201Created
Monitor created
application/json
A project monitor, as returned by the list, get, create and update operations. Every required property is always present; a nullable one carries null rather than being omitted. evaluation_unavailable_reason is present only when an Instance CPU monitor has lost its CPU limit. Fields not listed here are internal to the platform and are not part of the contract.
- idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
- org_idintegerRequired
  Organization that owns the project
- app_idintegerRequired
  Project the monitor or reaction belongs to
- created_byinteger | nullRequired
  User who created it, when it was created by a user credential
- namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
- descriptionstring | nullRequired
- kindstringRequired
  The monitors endpoints only ever return runtime.
  - Value: runtime
- statusstringRequired
  Whether it is evaluating
  - Allowed values: active, disabled
- template_idstringRequired
  Template it was created from
- specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
- targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  - Minimum items: 1
  - Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
- last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
- last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
- created_atstring (date-time)Required
- updated_atstring (date-time)Required
- evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  - Value: cpu_limit_missing
400Bad Request
Invalid request body or project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found, or the template is not available for this project (code is monitor_template_unavailable). Monitors run only on managed projects, and only released templates are available unless the organization has early access.
409Conflict
A live monitor or data reaction in this project already has this name
413Content Too Large
Request body too large
422Unprocessable Content
Slack is not connected for the organization
500Internal Server Error
Internal server error
502Bad Gateway
Failed to provision monitor

Get a project monitor

GET/v1/apps/{appId}/monitors/{alertId}Deprecated

Legacy alias of /v1/projects/{projectId}/monitors/{alertId} — projects were previously called apps. Returns a single project monitor. Requires monitors:read. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Path parameters

Name	Type	Required	Description
`appId`	integer	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/apps/<appId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor
application/json
A project monitor, as returned by the list, get, create and update operations. Every required property is always present; a nullable one carries null rather than being omitted. evaluation_unavailable_reason is present only when an Instance CPU monitor has lost its CPU limit. Fields not listed here are internal to the platform and are not part of the contract.
- idstring (uuid)Required
  Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
- org_idintegerRequired
  Organization that owns the project
- app_idintegerRequired
  Project the monitor or reaction belongs to
- created_byinteger | nullRequired
  User who created it, when it was created by a user credential
- namestringRequired
  Display name, unique case-insensitively among the project's live monitors and data reactions
- descriptionstring | nullRequired
- kindstringRequired
  The monitors endpoints only ever return runtime.
  - Value: runtime
- statusstringRequired
  Whether it is evaluating
  - Allowed values: active, disabled
- template_idstringRequired
  Template it was created from
- specobjectRequired
  Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
- targetobjectRequired
  The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- targetsarray of objectRequired
  Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
  - Minimum items: 1
  - Maximum items: 3
  3 options
  One of
  type: emailobject
  typestringRequired
  Value: email
  recipientUserIdsarray of integer
  emailsarray of string (email)
  type: httpobject
  typestringRequired
  Value: http
  urlstring (uri) | ""Required
  The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  methodstring
  Allowed values: POST, PUT, PATCH
  type: slackobject
  typestringRequired
  Value: slack
  channelIdstring | ""Required
  The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
  channelNamestring
  Minimum length: 1
  Maximum length: 80
- recipient_user_idsarray of integerRequired
  Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
- last_fired_atstring (date-time) | nullRequired
  When it last fired, or null if it never has
- last_resolved_atstring (date-time) | nullRequired
  When it last resolved, or null if it never has
- created_atstring (date-time)Required
- updated_atstring (date-time)Required
- evaluation_unavailable_reasonstring
  Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
  - Value: cpu_limit_missing
400Bad Request
Invalid project or monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project or monitor not found
500Internal Server Error
Internal server error

Update a project monitor

PATCH/v1/apps/{appId}/monitors/{alertId}Deprecated

Legacy alias of /v1/projects/{projectId}/monitors/{alertId} — projects were previously called apps. Updates a project monitor. Requires monitors:write and organization admin privileges.

Path parameters

Name	Type	Required	Description
`appId`	integer	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
specobject
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
recipientUserIdsarray of integer

Example request

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

Responses

200OK
Monitor updated
400Bad Request
Invalid request or monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or role
404Not Found
Project or monitor not found
409Conflict
Duplicate monitor name or monitor changed during update
413Content Too Large
Request body too large
422Unprocessable Content
Destination is unavailable or project configuration is incomplete
500Internal Server Error
Internal server error
502Bad Gateway
Monitor backend update failed

Delete a project monitor

DELETE/v1/apps/{appId}/monitors/{alertId}Deprecated

Legacy alias of /v1/projects/{projectId}/monitors/{alertId} — projects were previously called apps. Soft-deletes a project monitor and tears down the monitor it provisioned. Requires monitors:write.

Path parameters

Name	Type	Required	Description
`appId`	integer	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/apps/<appId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Monitor deleted
400Bad Request
Invalid project or monitor ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project or monitor not found
500Internal Server Error
Internal server error
502Bad Gateway
Failed to delete monitor