Referenz: Maßnahmen (/v1/actions)

Maßnahmen mit Rangstufe, Termin, Status und Wirksamkeitskontrolle. Alle Felder, Filter, Rechte und Fehler dieser Ressource.

Für wen

Entwicklerinnen und Entwickler, die elyph anbinden.

Voraussetzungen

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

Schritt für Schritt

1
Liste abrufen
GET https://api.elyph.io/v1/actions liefert die Objekte des Mandanten, sortiert nach letzter Änderung. Erforderliches Recht: actions:read.
curl
curl -sS "https://api.elyph.io/v1/actions?limit=50&status=approved" \ -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": "MAS-2026-233",
      "title": "Zweihandschaltung instand setzen",
      "type": "technisch",
      "status": "in_progress",
      "priority": "hoch",
      "due_date": "2026-02-14",
      "owner": {
        "name": "Marco List",
        "email": "marco.list@example.com"
      },
      "site": {
        "reference": "WN",
        "name": "Werk Nord"
      },
      "origin": {
        "type": "assessment",
        "reference": "GBU-2026-014"
      },
      "effectiveness_check": {
        "required": true,
        "done": false,
        "result": null,
        "due_at": "2026-03-15"
      },
      "implemented_at": null,
      "completed_at": null,
      "updated_at": "2026-01-21T11:05:00Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 50
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

3
Filter setzen
Verfügbare Filter: `status` — Statuswert exakt wie im Feld `status`. `due_before` — Nur Objekte mit Termin bis einschließlich diesem Datum. `site` — Kennung des Standorts (UUID der Organisationseinheit). `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/actions/{Kennung} liefert genau ein Objekt. Kennung ist `reference`, etwa `MAS-2026-233`. Unbekannte Kennungen ergeben 404 `not_found`.
curl
curl -sS "https://api.elyph.io/v1/actions/{kennung}" \ -H "Authorization: Bearer $ELYPH_API_KEY"
5
Objekt fortschreiben
PATCH /v1/actions/MAS-2026-233 — erforderliches Recht: actions:write. Änderbar sind ausschließlich `status`, `due_date`, `implemented_at` und `priority`. `effectiveness_result` und `effectiveness_checked_at` werden abgewiesen (403 `forbidden_field`) — die Wirksamkeitskontrolle bleibt der Oberfläche vorbehalten. Unbekannte Nummer im Pfad ergibt 404 `not_found`.
curl
curl -sS "https://api.elyph.io/v1/actions/MAS-2026-233" \ -H "Authorization: Bearer $ELYPH_API_KEY" \ -H "Content-Type: application/json" \ -X PATCH \ -d '{ "status": "done", "implemented_at": "2026-02-10T14:00:00Z" }'

Felder der Antwort

Feld	Typ	Bedeutung
reference	string	Nummer der Maßnahme, auch für PATCH im Pfad.
title	string	Bezeichnung der Maßnahme.
type	string \| null	Rangstufe nach STOP: Substitution, Technik, Organisation, Person.
status	string	`open`, `in_progress`, `done`, `verified`, `cancelled`.
priority	string \| null	Dringlichkeit.
due_date	string \| null	Termin (Datum).
owner.name	string \| null	Name der verantwortlichen Person.
owner.email	string \| null	E-Mail der verantwortlichen Person.
site.reference	string \| null	Kurzzeichen des Standorts.
site.name	string \| null	Name des Standorts.
origin.type	string \| null	Herkunft: `assessment` oder `barrier`.
origin.reference	string \| null	Nummer des auslösenden Objekts.
effectiveness_check.required	boolean	Ob eine Wirksamkeitskontrolle vorgesehen ist.
effectiveness_check.done	boolean	Ob die Kontrolle erfolgt ist.
effectiveness_check.result	string \| null	Ergebnis der Kontrolle.
effectiveness_check.due_at	string \| null	Termin der Kontrolle.
implemented_at	string \| null	Zeitpunkt der Umsetzung.
completed_at	string \| null	Zeitpunkt des Abschlusses.
updated_at	string (ISO 8601)	Letzte Änderung. Sortierfeld der Liste und Grundlage für `updated_since`.

Filter

Parameter	Beschreibung	Beispiel
status	Statuswert exakt wie im Feld `status`.	status=approved
due_before	Nur Objekte mit Termin bis einschließlich diesem Datum.	due_before=2026-03-31
site	Kennung des Standorts (UUID der Organisationseinheit).	site=4f4c…
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/actions
Methoden	GET, PATCH
Rechte	actions:read, actions:write
Kennung	`reference`, etwa `MAS-2026-233`

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/actions?limit=10

status

Statuswert exakt wie im Feld `status`.

due_before

Nur Objekte mit Termin bis einschließlich diesem Datum.

site

Kennung des Standorts (UUID der Organisationseinheit).

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.

curl

curl -sS "https://api.elyph.io/v1/actions?limit=10" \
  -H "Authorization: Bearer $ELYPH_API_KEY"

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": "MAS-2026-233",
      "title": "Zweihandschaltung instand setzen",
      "type": "technisch",
      "status": "in_progress",
      "priority": "hoch",
      "due_date": "2026-02-14",
      "owner": {
        "name": "Marco List",
        "email": "marco.list@example.com"
      },
      "site": {
        "reference": "WN",
        "name": "Werk Nord"
      },
      "origin": {
        "type": "assessment",
        "reference": "GBU-2026-014"
      },
      "effectiveness_check": {
        "required": true,
        "done": false,
        "result": null,
        "due_at": "2026-03-15"
      },
      "implemented_at": null,
      "completed_at": null,
      "updated_at": "2026-01-21T11:05:00Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 10
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

Ergebnis

Sie können maßnahmen zuverlässig lesen und schreiben, filtern und mit Ihrem System abgleichen.

Häufige Stolpersteine

Interne UUIDs statt der fachlichen Kennung speichern: Verwenden Sie `reference`, etwa `MAS-2026-233` als stabile Verknüpfung.
Alle Daten bei jedem Lauf neu laden: Mit `updated_since` holen Sie nur Änderungen.
Schreibrechte pauschal vergeben: Erteilen Sie actions: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.