Skip to navigation
REST API EndpointsAlerts

Create Alert

View as Markdown

Create an alert for the authenticated user.

Available to: Traders (own alerts)

Environments: Demo, Live

Rate Limit: No endpoint-specific limit

Create an alert owned by the calling user. Put the condition to watch for in expression; the server parses it before saving the alert. When the parse succeeds, the alert is created with status set to Active, the server starts watching the condition, and the response returns the new alert, including the id you pass to later alert calls.

Request fields:

  • expression (required): the condition the alert watches for, up to 4,096 characters.
  • validUntil: an optional time after which the alert stops watching.
  • triggerLimits: an optional maximum number of times the alert can trigger, from 0 to 9. If you omit it, the alert triggers once.
  • message: optional text (up to 256 characters) for the push notification sent when the alert triggers.

Once an alert has used all its allowed triggers, it stops watching until you re-arm it with resetAlert. To stop an alert without removing it, call dismissAlert. To change it, call modifyAlert; to remove it, call deleteAlert.

Common Failure Scenarios

  • The expression can’t be parsed. The alert isn’t created, and the response returns HTTP 200 with the parser’s explanation in errorText and no alert.
  • The expression parses but refers to a contract that doesn’t exist, or to an account that doesn’t exist or that you can’t access. The alert is still created (HTTP 200 with the new alert and no errorText), 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.
  • 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".
  • Saving the alert fails unexpectedly. This returns HTTP 200 with the reason in errorText.

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
"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.
"Service Unavailable, error id: {id}"503The alert service is temporarily unavailable. The error ID is generated per request.
(parser message)200 (in errorText)The expression can’t be parsed. The text describes the parse problem and varies with the expression.
"Internal Error. Error ID: {id}"200 (in errorText)Saving the alert failed unexpectedly. The error ID is generated per request.

Authentication

AuthorizationBearer

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

Request

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

Response

AlertResponse
errorTextstringOptional<=8192 characters

Non-empty if the request failed

alertobjectOptional