---
title: Trigv API
description: Introduction to the Trigv API - ingest events, authenticate with workspace API keys, connection test, OpenAPI, and response codes.
---
# Trigv API

The Trigv API lets your stack send native push alerts to subscribed devices. For most integrators, that means one thing: **ingest** - POST a JSON event with a workspace API key and Trigv delivers the push. The same platform also exposes mobile and dashboard session routes (Sanctum tokens) for the iOS app and app.trigv.com; this page focuses on ingest and the endpoints you wire from scripts, CI, and automation tools.

## Base URL

All API requests use HTTPS. Production base path:

```
https://api.trigv.com/api
```

Example ingest URL: `https://api.trigv.com/api/v1/events`. Always send `Accept: application/json` so errors return JSON, not HTML redirects.

## Authentication

Ingest routes authenticate with a **workspace API key** in the `Authorization` header: `Bearer trgv_...`. Keys are created in the dashboard, shown once at create/rotate, and stored hashed server-side. Never put keys in the JSON body.

See [API keys](/docs/learn/api-keys) for create, rotate, and revoke. Session routes (app login, device registration) use Sanctum tokens - not workspace keys. See [API security](/docs/security) for the full credential model.

## Primary endpoint - send an event

<div>
  POST
  /api/v1/events
</div>

Queue a push notification for a channel in your workspace. Required fields: `channel` (slug) and `title`. Optional: `description`, `level`, `delivery_urgency`, `image_url`, `url`, `idempotency_key`.

```
curl -X POST https://api.trigv.com/api/v1/events \
		-H "Content-Type: application/json" \
		-H "Accept: application/json" \
		-H "Authorization: Bearer trgv_YOUR_KEY" \
		-d '{"channel":"general","title":"Deploy finished","level":"success"}'
```

Full parameter reference: [POST /api/v1/events](/docs/events).

## Connection test - verify API key

<div>
  GET
  /api/v1/connection
</div>

Confirms your workspace API key is valid and authorized for ingest. Use this in Zapier, Make, n8n, or OttoKit connection tests. Does **not** create an event, bill usage, or send a push.

```
curl -sS "https://api.trigv.com/api/v1/connection" \
		-H "Accept: application/json" \
		-H "Authorization: Bearer trgv_YOUR_KEY"
```

Success returns `200 OK` with workspace and key metadata. Same auth failures as ingest: `401` (invalid key), `403` (revoked/expired/wrong scope), `429` (connection abuse throttle - separate from POST rate limits).

## OpenAPI

Machine-readable spec: [api.trigv.com/openapi.yaml](https://api.trigv.com/openapi.yaml). Use it for codegen, Postman import, or agent-assisted integration.

## Response codes

Common ingest status codes. Full detail: [Errors & rate limits](/docs/errors).

<div>
  <div class="ti-table-scroll"><table class="ti-table">
    <thead>
      <tr><th>Code</th><th>When</th></tr>
    </thead>
    <tbody>
      <tr><td><code>200</code></td><td>Duplicate <code>idempotency_key</code> - returns existing event, no extra usage</td></tr>
      <tr><td><code>202</code></td><td>Event accepted and queued for delivery</td></tr>
      <tr><td><code>400</code></td><td>Malformed JSON or invalid request shape</td></tr>
      <tr><td><code>401</code></td><td>Missing or invalid Bearer API key</td></tr>
      <tr><td><code>403</code></td><td>Revoked/expired key, missing <code>events:write</code>, or inactive workspace</td></tr>
      <tr><td><code>404</code></td><td>Channel slug not found or inactive</td></tr>
      <tr><td><code>422</code></td><td>Validation failed (e.g. missing <code>channel</code> or <code>title</code>)</td></tr>
      <tr><td><code>429</code></td><td>Monthly event cap or per-key burst rate limit (60 req/min default)</td></tr>
      <tr><td><code>5xx</code></td><td>Server error - retry with backoff</td></tr>
    </tbody>
  </table></div>
</div>

## Rate limits

Each API key defaults to **60 requests per minute** (burst). Workspaces also have a monthly event allowance by plan. Both return `429` with different `message` strings - see [Errors & rate limits](/docs/errors) to tell them apart.