Skip to navigation

Modify Alert

View as Markdown

Modify an existing alert and re-arm it.

Available to: Traders (own alerts); organization administrators (any user in their organization)

Environments: Demo, Live

Rate Limit: No endpoint-specific limit

Update the alert identified by alertId. The server parses the new expression first. When the parse succeeds, it replaces the alert’s expression, validUntil, triggerLimits, and message, resets its trigger counter, clears any failure, sets status back to Active, and resumes watching. The response returns the updated alert.

Request fields:

  • alertId (required): the id of the alert to modify.
  • expression (required): the new condition, up to 4,096 characters.
  • validUntil: an optional new expiration time.
  • triggerLimits: an optional new trigger limit, from 0 to 9. If you omit it, the alert triggers once.
  • message: optional new text (up to 256 characters).

Every field is replaced, so omitting validUntil or message clears that field, and omitting triggerLimits resets it to the default of one trigger. Modifying a deleted alert restores it.

If the new expression can’t be parsed, the alert is left unchanged. If the parse succeeds but the change can’t be saved, the alert isn’t updated: the response returns the unchanged alert with an errorText that starts with "Cannot apply changes: ", and the server resumes watching it using the new condition.

Common Failure Scenarios

  • The new expression can’t be parsed. This returns HTTP 200 with the parser’s explanation in errorText, and the alert doesn’t change.
  • The new expression parses but refers to a contract that doesn’t exist, or to an account that doesn’t exist or that the alert’s owner can’t access. The change is saved (HTTP 200 with the updated alert), but when the server first checks it, the alert’s status changes to Failed, its failure is set to "Access denied", and the server stops watching it. If the account and contract exist but there’s no position, the alert instead stays Active, with failure set to "No data", and the server keeps watching it.
  • The alertId is for an alert you can’t access. This returns HTTP 401 with "Access is denied".
  • No alert matches alertId. This returns HTTP 404 with an empty body.
  • alertId isn’t greater than 0, expression is empty or longer than 4,096 characters, triggerLimits is outside 0 to 9, message is longer than 256 characters, or expression or message contains unsupported characters. These return HTTP 400.
  • The alert service is temporarily unavailable. This returns HTTP 503.
  • The caller’s user type, or the API key’s permissions, don’t include full access to the Alerts resource. This returns HTTP 401 with "Access is denied".

This endpoint returns HTTP 200 for both successful and rejected requests, so check the errorText field to confirm the result. Other failures, such as denied access or an invalid request, return their own HTTP status.

Error Messages

MessageResponseTrigger
"Alert Id should be greater than 0"400alertId isn’t greater than 0.
"Expression should be specified"400expression is empty or null.
"Expression should be no longer than 4096"400expression is longer than 4,096 characters.
"Trigger Limits should be greater or equal than 0"400triggerLimits is less than 0.
"Trigger Limits should be less than 10"400triggerLimits is 10 or more.
"Message should be no longer than 256"400message is longer than 256 characters.
"Unsupported characters"400expression or message contains characters outside the supported range (for example, control characters or most emoji).
"Access is denied"401The caller’s user type, or the API key’s permissions, don’t include full access to the Alerts resource.
"Access is denied"401The alertId is for an alert the caller can’t access.
(no message text)404No alert matches alertId.
"Service Unavailable, error id: {id}"503The alert service is temporarily unavailable. The error ID is generated per request.
(parser message)200 (in errorText)The new expression can’t be parsed. The text describes the parse problem and varies with the expression.
"Cannot apply changes: {reason}"200 (in errorText)The expression parsed, but saving the change failed. The unchanged alert is returned, and watching resumes using the new condition.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
alertIdlongRequired
expressionstringRequired<=4096 characters
validUntildatetimeOptional
triggerLimitsintegerOptional0-10
messagestringOptional<=256 characters

Response

AlertResponse
errorTextstringOptional<=8192 characters

Non-empty if the request failed

alertobjectOptional