Alerts API
This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.
Another system — an order portal, a billing service, a monitoring script — can report its own problems to Tickiti as Alert tickets. Each reporting system has one open Alert ticket. The first problem raises it; later problems are added to it as internal notes; once it is closed, the next problem raises a new one. A caller can report every problem it finds on every check and leave the de-duplication to Tickiti.
Alert tickets, and this endpoint, are for a self-hosted installation. A site hosted by Tickiti has no System alerts team, so its API keys cannot hold alerts:write.
Endpoint
POST /api/v1/tickets/alertHeaders
Authorization: Bearer YOUR_TOKEN— required. The token must hold thealerts:writeability (see Authentication and tokens).Content-Type: application/json— required.
No Idempotency-Key is needed: reporting the same problem twice adds nothing.
Body
source— required. The reporting system’s name, for exampleorder-portal: letters, digits, dots, hyphens and underscores, starting with a letter or digit, up to 64 characters. Every problem from one source goes into that source’s Alert ticket.tickitiis reserved for Tickiti’s own alerts.problem_key— required. A stable name for the problem, for examplehealth:payment_queue, up to 191 characters. It is what makes a repeat report recognisable.title— required, one line, up to 200 characters. When the report raises a new ticket, its subject is Alert: <source> - <title>.content— required. The note, as HTML (one<p>per line), up to 20,000 characters.latched— optional boolean. Use it for a problem that must not pass unnoticed, such as a rate limit that may be an attack. See Latched problems.severity— optional,criticalornormal(the default). A critical alert’s WhatsApp message comes through Do Not Disturb for staff who let critical alerts through; a normal one waits until Do Not Disturb ends.originator_email_address— optional. The staff account the ticket and notes are written as. It must be a member of staff; it defaults to the System user.
Example
curl -X POST https://support.sole-provider.example/api/v1/tickets/alert \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"source": "order-portal",
"problem_key": "health:payment_queue",
"title": "Payment queue is not draining",
"content": "<p>42 payments have waited more than 15 minutes.</p><p>Oldest: 09:12.</p>",
"severity": "critical"
}'Response
{
"ok": true,
"data": {
"ticket_number": "418230",
"created": true,
"noted": true
}
}ticket_number— the source’s open Alert ticket.created— true when this report raised the ticket.noted— true when this report added something. A repeat of aproblem_keythat is already on the open ticket returnscreated: falseandnoted: false, and the ticket is unchanged.
Latched problems
A report with latched: true is always added as a note, even when the same problem is already on the ticket. It also keeps Tickiti’s health check unhealthy until someone confirms it on the Health page, which links to the note. Most problems come and go and need no latch.
Errors
422 validation_failed— a missing or malformed field, or the sourcetickiti;errorsnames each field.422with anerrormessage — the alert could not be raised, for example becauseoriginator_email_addressis not a member of staff.401— a bad or missing token;403— the token does not holdalerts:write.
Raising an Alert through the create endpoint
A token holding alerts:write can also send "priority": "50" to the Create ticket API. That raises a new Alert ticket every time and has no de-duplication, so tickets/alert is the better fit for a system reporting its health.