Heylerts API

JSON over HTTPS. Read and write alerts, mentions, and stats programmatically. Available on every paid plan (Starter, Pro, Business).

Quick start

  1. Generate an API key in Settings → API Access. Plaintext is shown once.
  2. Set X-API-Key on every request.
  3. Hit /api/v1/hello to confirm the key works.
curl https://heylerts.com/api/v1/hello \
  -H "X-API-Key: hlt_your_key_here"

Authentication

All requests require the X-API-Key header. Keys begin with hlt_ and authenticate the owning account. Revoke a key from Settings — revocation is immediate.

Errors return a JSON body: { "detail": "..." }. Common codes: 401 (missing or invalid key), 403 (downgraded to Free), 404 (resource not yours), 429 (rate-limited).

Rate limits

100 requests per minute per API key. When exceeded the API returns 429 with a Retry-After header in seconds.

Pagination

List endpoints accept page (1-indexed, default 1) and per_page (default 20, max 100). Responses return an envelope:

{
  "items": [...],
  "page": 1,
  "per_page": 20,
  "total_items": 137,
  "total_pages": 7,
  "has_more": true
}

Endpoints

GET/api/v1/hello

Auth ping

Confirms the API key is valid and returns the authenticated account's plan plus the docs URL. Use this as the first call from any new integration.

Response

{
  "ok": true,
  "user": { "email": "[email protected]", "plan": "pro" },
  "rate_limit": "100/minute",
  "docs_url": "https://heylerts.com/docs"
}
GET/api/v1/alerts

List alerts

Returns a paginated list of the account's alerts, newest first. Accepts page and per_page.

Response

{
  "items": [
    {
      "id": "uuid",
      "name": "My brand",
      "keyword": "heylerts",
      "include_keywords": ["saas"],
      "exclude_keywords": ["job"],
      "ignore_domains": ["example.com"],
      "sources": ["brave", "reddit"],
      "frequency": "daily",
      "is_active": true,
      "mention_count": 42,
      "last_checked_at": "2026-05-08T12:00:00Z",
      "created_at": "2026-04-01T09:00:00Z",
      "x_enabled": false,
      "webhook_url": null,
      "webhook_configured": false
    }
  ],
  "page": 1, "per_page": 20, "total_items": 1, "total_pages": 1, "has_more": false
}
GET/api/v1/alerts/{alert_id}

Get alert

Returns a single alert. 404 if not found or not yours.

Response

{
  "id": "uuid",
  "name": "My brand",
  ...
}
POST/api/v1/alerts

Create alert

Creates a new alert. Capped per plan: Free 2, Starter 10, Pro 50, Business 250. 403 when the account is at quota.

Request body

{
  "name": "Competitor X",
  "keyword": "competitor x",
  "include_keywords": ["launch"],
  "exclude_keywords": ["job posting"],
  "ignore_domains": ["spam.example"],
  "sources": ["brave", "reddit", "hackernews"],
  "frequency": "daily"
}

Response

{
  "id": "uuid",
  "name": "Competitor X",
  ...
}
PATCH/api/v1/alerts/{alert_id}

Update alert

Partial update — only the fields you send are modified. Same body shape as create; every field is optional.

Request body

{
  "is_active": false
}

Response

{
  "id": "uuid",
  "is_active": false,
  ...
}
DELETE/api/v1/alerts/{alert_id}

Delete alert

Permanently deletes the alert and all of its mentions. Returns 204 No Content on success.

Response

(empty body, status 204)
GET/api/v1/mentions

List mentions

Returns a paginated list of mentions, newest first. Filters: alert_id, source, sentiment, since (ISO 8601 timestamp). Ignored mentions are excluded.

Response

{
  "items": [
    {
      "id": "uuid",
      "alert_id": "uuid",
      "source": "reddit",
      "url": "https://...",
      "title": "...",
      "snippet": "...",
      "author": "u/example",
      "sentiment": "positive",
      "relevance_score": 0.87,
      "found_at": "2026-05-08T11:00:00Z",
      "published_at": "2026-05-08T10:30:00Z",
      "ignored": false
    }
  ],
  "page": 1, "per_page": 20, "total_items": 137, "total_pages": 7, "has_more": true
}
GET/api/v1/stats

Aggregate stats

Returns total mention count and breakdowns by source, sentiment, and category (web/social/forum). Optional alert_id query param scopes to a single alert.

Response

{
  "total": 137,
  "by_source": { "reddit": 42, "brave": 88, "hackernews": 7 },
  "by_sentiment": { "positive": 60, "neutral": 70, "negative": 7 },
  "by_category": { "web": 110, "social": 24, "forum": 3 }
}

Webhooks

Configure a per-alert webhook_url in the dashboard to receive a signed POST for each new mention and each detected spike. Heylerts sends an X-Heylerts-Signature header containing an HMAC-SHA256 of the raw request body using the alert's webhook secret. Verify it before trusting the payload.

Events: mention.created, spike.detected.

Rotate the secret from the dashboard if it leaks; the next delivery uses the new value.

Hit a snag or want a feature? Email [email protected].