HYPHAby S33D
Documentation › Administer

HYPHA API

Everything the interface does goes through a JSON API. An application key is enough to automate it.

Authentication

UseKeyHeader
Read and write like the interfaceapplicationX-Hypha-App-Key: hph_…
Send dataingestionX-Hypha-Api-Key: hph_… (OTLP: also Authorization: Bearer hph_…)

Keys are created in Settings › API keys (see Accounts and roles). An application key acts with its author's role. Base address: https://hypha.s33d.fr/api/v1 (when self-hosting, your own address).

Conventions

curl -s -H "X-Hypha-App-Key: $HYPHA_APP_KEY" https://hypha.s33d.fr/api/v1/hosts

Read

RouteReturns
GET /hostshosts, their state and their values over the last 2 minutes (?q=, ?tag=key:value)
GET /hosts/{id}a host, its agent, its latest checks
GET /problemsnon-OK groups, sorted by priority
GET /monitors, GET /monitors/{id}/historymonitors and a monitor's history
POST /metrics/queryseries of one or more queries, with formulas
GET /logs/search, /logs/facets, /logs/histogram, /logs/patternslog search
GET /apm/services, /apm/traces, /apm/traces/{trace_id}services, traces, trace details
GET /inventory, /inventory/packages?name=openssl&version_lt=3.5.2inventory and fleet-wide package search
GET /certificatescollected certificates, sorted by expiry
GET /usageusage per day

Metric query example:

curl -s -H "X-Hypha-App-Key: $HYPHA_APP_KEY" -H "Content-Type: application/json" \
  https://hypha.s33d.fr/api/v1/metrics/query \
  -d '{"queries":[{"id":"a","q":"avg:system.cpu.usage{env:prod} by {host}"}],"max_points":300}'

Write

RouteEffect
POST /monitors, PUT /monitors/{id}, DELETE /monitors/{id}monitors
POST /monitors/from-templatemonitor from a template: {"template": "disk_forecast", "vars": {…}}
POST /monitors/{id}/mutemute until until (ms) or indefinitely (null)
POST /monitors/{id}/groups/ackacknowledge a group, with a comment
POST /downtimesdowntime; {"duration_s": 3600, "scope": {…}} starts right away
POST /incidents, POST /incidents/from-alertincidents
POST /synthetics, POST /synthetics/{id}/runsynthetic tests, immediate run
POST /dashboards, POST /dashboards/importdashboards
POST /actions, POST /actions/{id}/approvepropose and approve a remote action
POST /explainAI explanation: {"kind": "alert", "monitor_id": 6, "group": "host:web-02", "lang": "en"}; kind can also be host, log, trace or error

Events

An event appears on the timeline, overlays charts and can trigger a monitor. Example, at the end of a deployment:

curl -s -H "X-Hypha-App-Key: $HYPHA_APP_KEY" -H "Content-Type: application/json" \
  https://hypha.s33d.fr/api/v1/events \
  -d '{"title":"Deployed shop-api 2.15.0","source":"deploy","type":"deploy","alert_type":"success",
       "tags":{"service":"shop-api","version":"2.15.0"}}'

APM charts and the service page overlay source:deploy events.

Send data

RouteContent
POST /api/v1/intake/metrics, /logs, /checks, /events, /host…agent protocol (JSON body, gzip accepted, 10 MB at most)
POST /v1/traces, /v1/metrics, /v1/logsOpenTelemetry (OTLP/HTTP, protobuf or JSON)
POST /api/v1/intake/rum?token=…browser (RUM script)

For your own applications, prefer OpenTelemetry or StatsD through the agent: see Traces and Integrations. The server accepts timestamps from 14 days in the past to 10 minutes in the future.

Intake responses: 202 {"status":"ok","accepted":N,"dropped":M}; 401 unknown key; 403 revoked or application key; 413 body too large; 429 rate; 402 plan limit.

Public pages

Updated: 19 November 2026