Ingest quickstart

Push your first alert to AlertHive.

A single POST. One token. Less than five minutes from "let me post a fake alert" to "the AI analyst page has it on screen — with severity score and dedupe already applied."

1 · Endpoint

POST /api/alerts/ingest

Server-to-server only. Authenticated by the X-AlertHive-Ingest-Token header against the ALERT_INGEST_TOKEN env var. The token is generated in your workspace's settings page — paste it into the header, do not store it in source control.

2 · First event

One curl, one body.
Send a representative alert from your stack. The queue will see the AI triage result within a few seconds.
curl -X POST https://YOUR_DOMAIN/api/alerts/ingest \
  -H "Content-Type: application/json" \
  -H "X-AlertHive-Ingest-Token: $ALERT_INGEST_TOKEN" \
  -d '{
    "source": "okta",
    "title": "8 failed logins from 203.0.113.7 in 90s",
    "message": "Single source IP across 3 accts. ASN history: credential-stuffing. Force MFA.",
    "externalId": "evt-2026-08-25-0001"
  }'

Replace YOUR_DOMAIN with the host the app is deployed to and $ALERT_INGEST_TOKEN with the token from the workspace settings.

3 · Body shape

What the ingester expects

Four optional and required fields, all flat. The full contract is owned by AlertIngestInput in src/lib/contracts/alerts.ts and the loader validates with zod before the alert enters the pipeline.

source
required

A short identifier for where the alert came from (e.g. "okta", "guardduty", "github"). Free-form, 1–120 chars.

title
required

A single-line summary of the alert. 1–200 chars.

message
required

The full alert text — the body, the context, the relevant fields. Free-form up to 8000 chars. This is what the AI analyst reads first.

externalId
optional

Your internal id for this alert (ticket number, SIEM event uuid). Used for dedupe — sending the same id twice will not generate a second alert.

4 · What happens next

From ingest to triage, in three steps.

  1. 1Allowlist pass. If the alert pattern is on the knowable-noise list — recurring scheduled job, a noisy scan, a known test alert — it auto-resolves with the pattern captured.
  2. 2AI triage. The remaining alert is read by the AI analyst, scored against identity / asset / history, deduped against the rolling window, and bucketed into Critical / High / Medium / Low.
  3. 3Queue routing.Severity drives routing — anything that survives & reaches Low or above lands in your queue with a recommended action, evidence, and the audit trail.

For the full narrative, see the How it works explainer.

Ready to read the broader pipeline? See how it works →

Back to the explainerRequest early access