Skip to main content
Back to Documentation

API Reference

Complete documentation for the Hugin Alerts event ingestion endpoint.

Last updated:

Quick Summary

Send events to Hugin by making a POST request to https://api.huginalerts.com/v1/events with your ingest key as a Bearer token.

That's it. No SDK required. Works with curl, Python, Node.js, Go, or any tool that can make HTTP requests.

Endpoint

POST https://api.huginalerts.com/v1/events

Authentication

Include your ingest key in the Authorization header: 

Authorization: Bearer YOUR_INGEST_KEY

You can find your ingest key in the Hugin Alerts mobile app. Basic authentication is also supported.

Request Format

Content Types

Hugin accepts three content types:

Event Fields

Field Type Max Length Description
system string 80 chars High-level category (e.g., "production", "staging")
event string 120 chars Event type (e.g., "deploy", "error", "backup")
component string 160 chars Specific component (e.g., "api-server", "database")
description string 500 chars Detailed message or context
url string 2000 chars Optional link (opens when notification is tapped)

All fields are optional. If you only send a description, that's fine. Hugin will automatically detect the severity (error, warning, success, info, neutral) based on keywords in your payload.

Query Parameter Fallback

For simple integrations, you can send the description as a query parameter: 

curl -X POST \
  "https://api.huginalerts.com/v1/events?description=Server%20restarted" \
  -H "Authorization: Bearer YOUR_INGEST_KEY"

Example Request

Full request example 
curl -X POST https://api.huginalerts.com/v1/events \
  -H "Authorization: Bearer YOUR_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "production",
    "event": "deploy",
    "component": "api-server",
    "description": "v2.1.0 deployed successfully",
    "url": "https://github.com/yourorg/yourrepo/releases/tag/v2.1.0"
  }'

Response Format

Success (201 Created)

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "ingest_time": "2026-02-06T12:34:56.789Z"
}

Error Responses

400 Bad Request

Invalid payload format or field length exceeded.

401 Unauthorized

Missing or invalid ingest key.

429 Too Many Requests

Rate limit exceeded (120 req/min).

Rate Limits

During early access, accounts are limited to 120 requests per minute using a token bucket that refills continuously at 60 requests per minute.

This is plenty for monitoring critical events. If you consistently hit the limit, reach out at hello@huginalerts.com.

Severity Detection

Hugin automatically detects the severity of your events based on keywords:

Severity affects the notification icon and color in the app, but does not change delivery behavior.

Common Questions

Can I use multiple ingest keys?

Yes. You can create multiple ingest keys in the app's Settings screen — useful for separating production, staging, and CI environments. You can revoke any key at any time without affecting the others.

How do I set notification priority?

Hugin automatically detects severity based on keywords. You cannot manually set priority levels—it's based on the content of your event.

What if the API is down?

The API returns standard HTTP status codes. If you receive a 5xx error, retry with exponential backoff. Contact hello@huginalerts.com if issues persist.

Can I delete events via API?

Yes. Use DELETE /v1/events/:id with your device token from the mobile app. Full documentation coming soon.