POST/api/v1/events

Send an event

Ingest a notification event for a workspace channel. Trigv validates the API key and channel, increments the workspace monthly usage counter, queues push delivery to subscribed devices, and returns event metadata. Use idempotency_key to safely retry without double-counting.

Request

URL: https://api.trigv.com/api/v1/events

Headers:

Code

Content-Type: application/json
Accept: application/json
Authorization: Bearer trgv_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyy

Body parameters (JSON)

Parameter	Type	Required	Description
`channel`	string	Yes	Channel slug in your workspace (e.g. `general`). Max 120 chars. Case-sensitive.
`title`	string	Yes	Notification headline. Max 255 characters.
`description`	string	No	Secondary body text. Max 1000 characters. If omitted, the push body uses `title`.
`icon`	string	No	Rejected. Put emoji in `title` if you want it on the push banner.
`image_url`	string (URL)	No	HTTPS image URL passed through to your devices. Max 2048 characters. Not stored on Trigv servers. The app fetches the image locally; links may expire after delivery.
`url`	string (URL)	No	Optional destination link. Max 2048 characters. Passed through in push data; not stored on Trigv servers.
`level`	string	No	One of `info`, `success`, `warning`, `error`. Default: `info`. Affects in-app styling only.
`delivery_urgency`	string	No	`standard` (default) or `time_sensitive`. On iOS, `time_sensitive` can break through Focus when allowed.
`event_type`	string	No	Machine-readable type (e.g. `deploy.complete`). Max 120 characters.
`idempotency_key`	string	No	Stable key for retries. Duplicate requests return `200` with the original event and do not increment usage again.
`api_key`	string	No	Rejected. Use `Authorization: Bearer` instead.

Code examples

cURL

Code

curl -X POST https://api.trigv.com/api/v1/events \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-H "Authorization: Bearer trgv_abcd1234_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
	-d '{
		"channel": "general",
		"title": "✅ Database backup complete",
		"description": "Cron finished in 4.2 seconds.",
		"level": "success",
		"delivery_urgency": "time_sensitive",
		"event_type": "backup.complete"
	}'

Laravel / PHP

Code

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.trigv.api_key'))
	->post('https://api.trigv.com/api/v1/events', [
		'channel' => 'general',
		'title' => 'App exploded 💥',
		'description' => 'Fatal error in OrderController.php:42',
		'level' => 'error',
		'idempotency_key' => 'order-job-'.now()->format('Y-m-d-H'),
	]);

Responses

202 Accepted

New event queued for push delivery.

Code

{
	"event": {
		"public_id": "evt_01JXXXXXXXX",
		"event_uuid": "550e8400-e29b-41d4-a716-446655440000",
		"status": "queued",
		"level": "success",
		"event_type": "backup.complete",
		"target_device_count": 2,
		"received_at": "2026-06-06T12:00:00+00:00"
	}
}

200 OK

Duplicate idempotency_key - same event returned, usage not incremented again.

422 Unprocessable

Missing or invalid fields (e.g. channel, title).

Code

{
	"message": "The channel field is required. (and 1 more error)",
	"errors": {
		"channel": ["The channel field is required."],
		"title": ["The title field is required."]
	}
}

404 Not Found

Unknown or inactive channel slug for this workspace.

Code

{ "message": "Channel not found." }

More examples: Guides · Errors & rate limits