Modify Alert
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): theidof 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
expressioncan’t be parsed. This returnsHTTP 200with the parser’s explanation inerrorText, and the alert doesn’t change. - The new
expressionparses 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 200with the updatedalert), but when the server first checks it, the alert’sstatuschanges toFailed, itsfailureis set to"Access denied", and the server stops watching it. If the account and contract exist but there’s no position, the alert instead staysActive, withfailureset to"No data", and the server keeps watching it. - The
alertIdis for an alert you can’t access. This returnsHTTP 401with"Access is denied". - No alert matches
alertId. This returnsHTTP 404with an empty body. alertIdisn’t greater than 0,expressionis empty or longer than 4,096 characters,triggerLimitsis outside 0 to 9,messageis longer than 256 characters, orexpressionormessagecontains unsupported characters. These returnHTTP 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
Alertsresource. This returnsHTTP 401with"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
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
Response
Non-empty if the request failed