---
title: How Trigv works
description: How Trigv delivers alerts to your phone - privacy model, API keys, channels, and authentication.
---
# How Trigv works

Trigv sends alerts from your tools to your phone - Zapier, a cron job, a script, or an AI agent. You trigger an alert; Trigv delivers a native push to subscribed devices. We deliver the message but **don't keep it** on our servers - title and body stay on your device in searchable local history.

## Base URL

All API requests use HTTPS:

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

The public ingest endpoint is `POST /api/v1/events` (full URL: `https://api.trigv.com/api/v1/events`).

## Authentication

Ingest requests authenticate with a **workspace API key** sent in the `Authorization` header as `Bearer trgv_...`. Keys are created and managed in the dashboard at [app.trigv.com](https://app.trigv.com). Each new workspace receives a default key at signup; you can create additional named keys per workspace. See [API security](/docs/security) for key handling best practices.

<table class="ti-table">
  <thead>
    <tr><th>Field / Header</th><th>Value</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr><td><code>Authorization</code></td><td><code>Bearer trgv_XXXXXXXX_...</code></td><td>Required. Plain-text key shown once at creation; stored hashed server-side.</td></tr>
    <tr><td><code>Content-Type</code></td><td><code>application/json</code></td><td>Required for <code>POST /api/v1/events</code>.</td></tr>
    <tr><td><code>Accept</code></td><td><code>application/json</code></td><td>Recommended - ensures JSON error responses instead of HTML redirects.</td></tr>
    <tr><td><code>api_key</code> (body)</td><td>-</td><td><strong>Rejected.</strong> Do not send keys in the JSON body.</td></tr>
  </tbody>
</table>

Manage keys in the dashboard: create named keys, **rotate** (old key stops working immediately), and **revoke**. See [API keys guide](/docs/learn/api-keys) for details.

OpenAPI spec: [api.trigv.com/openapi.yaml](https://api.trigv.com/openapi.yaml)

API key format:

```
trgv_{8 alphanumeric}_{32 alphanumeric}
```

### Invalid API key (401)

```
{
		"message": "Invalid API key."
}
```

### Revoked or restricted key (403)

Examples: revoked key, expired key, missing `events:write` scope, or inactive workspace.

```
{
		"message": "This API key has been revoked."
}
```

## Core concepts

- **Workspace** - owns API keys, channels, events, billing, and monthly usage counters.
- **Channel** - a named routing target (slug, e.g. `general`). Devices subscribe to channels via the mobile app.
- **Event** - server-side metadata record (status, level, timestamps, device count). No notification body stored; metadata is pruned after 7 days.
- **Device** - belongs to a user; receives pushes when subscribed to a channel.

## What the server stores vs. your device

<table class="ti-table">
  <thead>
    <tr><th>Data</th><th>Trigv cloud</th><th>Your device</th></tr>
  </thead>
  <tbody>
    <tr><td>API keys</td><td>Hashed only</td><td>-</td></tr>
    <tr><td>Notification title &amp; body</td><td>In-memory for delivery (not indexed)</td><td>Searchable local history (encrypted on device)</td></tr>
    <tr><td>Event metadata</td><td>Status, level, timestamps, counts (deleted after 7 days)</td><td>Synced via push payload; kept in your local feed</td></tr>
  </tbody>
</table>

<p>
  <a href="/docs/learn">Integration guides →</a>
  <a href="/docs/events">API reference →</a>
</p>