Referenz: Gefährdungen (/v1/hazards)

Gefährdungen des Mandanten mit Katalogbezug und Rechtsgrundlage. Alle Felder, Filter, Rechte und Fehler dieser Ressource.

Für wen

Entwicklerinnen und Entwickler, die elyph anbinden.

Voraussetzungen

Schlüssel mit dem Recht hazards:read bzw. hazards:write Grundlagen aus „Erste Anfrage an die elyph API“

Schritt für Schritt

1
Liste abrufen
GET https://api.elyph.io/v1/hazards liefert die Objekte des Mandanten, sortiert nach letzter Änderung. Erforderliches Recht: hazards:read.
curl
curl -sS "https://api.elyph.io/v1/hazards?limit=50&category=mechanisch" \ -H "Authorization: Bearer $ELYPH_API_KEY"

Antwort lesen

Die Antwort enthält `data` mit den Objekten, `page.next` als Fortsetzungsmarke und `rate` mit dem verbleibenden Abfragekontingent.

Antwort

{
  "data": [
    {
      "reference": "GEF-0112",
      "name": "Quetschen zwischen bewegten Maschinenteilen",
      "category": "mechanisch",
      "subcategory": "bewegte Teile",
      "description": "Körperteile können zwischen Werkzeug und Aufspanntisch geraten.",
      "typical_consequences": "Quetschung, Amputation",
      "legal_basis": "BetrSichV Anhang 1, DGUV Regel 100-500",
      "source": "katalog",
      "jurisdiction": "DE",
      "active": true,
      "updated_at": "2026-01-14T07:31:02Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 50
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

3
Filter setzen
Verfügbare Filter: `category` — Katalogkategorie exakt wie im Feld `category`. `updated_since` — Nur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601). Grundlage jeder Synchronisation. `limit` — Anzahl der Objekte je Seite, 1 bis 200. Standard 50. `page` — Fortsetzungsmarke aus `page.next` der vorherigen Antwort. Keine Seitenzahl. Mehrere Filter werden mit `&` verbunden und wirken zusammen.
4
Einzelnes Objekt holen
Der Pfad /v1/hazards/{Kennung} liefert genau ein Objekt. Kennung ist `reference` (Katalogkürzel, etwa `GEF-0112`). Unbekannte Kennungen ergeben 404 `not_found`.
curl
curl -sS "https://api.elyph.io/v1/hazards/{kennung}" \ -H "Authorization: Bearer $ELYPH_API_KEY"
5
Objekt anlegen
POST /v1/hazards — erforderliches Recht: hazards:write. Nur `name` ist Pflicht; fehlt es, antwortet die Schnittstelle mit 422 `invalid_body`. Ohne Angabe wird `category` auf `sonstige` gesetzt und `source` auf `api`. Die Antwort enthält `reference` und die interne `id`; die Anlage wird revisionssicher protokolliert.
curl
curl -sS "https://api.elyph.io/v1/hazards" \ -H "Authorization: Bearer $ELYPH_API_KEY" \ -H "Content-Type: application/json" \ -X POST \ -d '{ "name": "Heißes Medium beim Entleeren", "category": "thermisch", "description": "Austritt von Kondensat beim Öffnen.", "legal_basis": "BetrSichV § 6" }'

Felder der Antwort

Feld	Typ	Bedeutung
reference	string	Eindeutiges Kürzel der Gefährdung.
name	string	Bezeichnung der Gefährdung.
category	string	Oberkategorie, etwa `mechanisch`, `elektrisch`, `psychisch`.
subcategory	string \| null	Feinere Einordnung innerhalb der Kategorie.
description	string \| null	Beschreibung der Gefährdung.
typical_consequences	string \| null	Typische Folgen bei Wirksamwerden.
legal_basis	string \| null	Rechtsgrundlage oder Regelwerk.
source	string	Herkunft: `katalog`, `tenant` oder `api`.
jurisdiction	string \| null	Rechtsraum, etwa `DE`, `AT`, `CH`, `FR`.
active	boolean	Ob die Gefährdung aktiv verwendet wird.
updated_at	string (ISO 8601)	Letzte Änderung. Sortierfeld der Liste und Grundlage für `updated_since`.

Filter

Parameter	Beschreibung	Beispiel
category	Katalogkategorie exakt wie im Feld `category`.	category=mechanisch
updated_since	Nur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601). Grundlage jeder Synchronisation.	updated_since=2026-01-01T00:00:00Z
limit	Anzahl der Objekte je Seite, 1 bis 200. Standard 50.	limit=100
page	Fortsetzungsmarke aus `page.next` der vorherigen Antwort. Keine Seitenzahl.	page=eyJ1IjoiMjAy…

Rechte und Methoden

Angabe	Wert
Pfad	/v1/hazards
Methoden	GET, POST
Rechte	hazards:read, hazards:write
Kennung	`reference` (Katalogkürzel, etwa `GEF-0112`)

API-Konsole

Anfrage zusammenstellen, Code kopieren und — angemeldet und mit eigenem Schlüssel — wirklich ausführen. Die Konsole führt ausschließlich lesende Aufrufe aus.

Ressource

Adresse

GET https://api.elyph.io/v1/hazards?limit=10

Echttest

Nach der Anmeldung führen Sie dieselbe Anfrage hier mit Ihrem eigenen Schlüssel aus. So sieht eine echte Antwort aus:

Beispielantwort

{
  "data": [
    {
      "reference": "GEF-0112",
      "name": "Quetschen zwischen bewegten Maschinenteilen",
      "category": "mechanisch",
      "subcategory": "bewegte Teile",
      "description": "Körperteile können zwischen Werkzeug und Aufspanntisch geraten.",
      "typical_consequences": "Quetschung, Amputation",
      "legal_basis": "BetrSichV Anhang 1, DGUV Regel 100-500",
      "source": "katalog",
      "jurisdiction": "DE",
      "active": true,
      "updated_at": "2026-01-14T07:31:02Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 10
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

Ergebnis

Sie können gefährdungen zuverlässig lesen und schreiben, filtern und mit Ihrem System abgleichen.

Häufige Stolpersteine

Interne UUIDs statt der fachlichen Kennung speichern: Verwenden Sie `reference` (Katalogkürzel, etwa `GEF-0112`) als stabile Verknüpfung.
Alle Daten bei jedem Lauf neu laden: Mit `updated_since` holen Sie nur Änderungen.
Schreibrechte pauschal vergeben: Erteilen Sie hazards:write nur dem System, das wirklich schreibt.

Hintergrund

Die Ressource ist streng auf den Mandanten des Schlüssels begrenzt. Ist der Zugang auf Standorte eingeschränkt, liefert die Liste nur Objekte dieser Standorte. Jede Anfrage wird mit Zeitpunkt, Pfad, Status und Trefferzahl protokolliert und ist in der Verwaltung einsehbar.