Lesen und schreiben Sie Artefakte, Links, Module und Baselines aus eigenen Programmen, Skripten oder Ihrer CI-Pipeline.
Die REST-API setzt das Zusatz-Abo ETRM API zu einem eigenen Single- oder Team-Abo voraus. Ohne beide Abos antwortet sie mit dem Status 403 und dem Fehlercode subscription_required.
Legen Sie unter Profil, API-Zugang einen Zugangsschlüssel an und senden Sie ihn bei jeder Anfrage im Kopf Authorization mit. Der Schlüssel handelt mit Ihren Rechten in den Gruppen. Schlüssel ohne Schreibrecht können nur lesen.
curl -H "Authorization: Bearer etrm_…" https://engineering-toolbox.com/etrm/api/v1/
https://engineering-toolbox.com/etrm/api/v1/. Anfragen und Antworten sind JSON (UTF-8).| GETprojects/ | Ihre Projekte mit Rolle (archivierte mit ?archived=1). |
| GETprojects/<id>/ | Projekt mit Konfiguration: Artefakttypen, Attribute mit erlaubten Werten, Link-Typen, Module. |
| GETprojects/<id>/metrics/ | Kennzahlen wie im Dashboard: Umfang, Abdeckung, verdächtige Links, Volatilität, Formulierungshinweise. |
| GETprojects/<id>/artifacts/ | Liste. Filter: type (mehrfach), module, tag (mehrfach, eines genügt), q (Volltext), changed_since (ISO 8601), attr.<schlüssel>=<wert>, deleted=1 (auch Papierkorb). |
| POSTprojects/<id>/artifacts/ | Anlegen. Optional mit tags (Liste), module, parent (Nummer einer Überschrift im Modul) und position. |
| GETprojects/<id>/artifacts/<nr>/ | Ein Artefakt mit Modulen und Links. |
| PATCHprojects/<id>/artifacts/<nr>/ | Ändern von title, text, type, attributes und tags (ersetzt die ganze Liste). Pflicht ist rev (aktueller Stand); hat sich das Artefakt inzwischen geändert, kommt 409 mit dem aktuellen Stand. In attributes entfernt null einen Wert. |
| DELETEprojects/<id>/artifacts/<nr>/ | In den Papierkorb (wiederherstellbar in der Oberfläche). |
Beispiel: Systemanforderung anlegen
curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" \
-d '{"type": "systemanforderung", "title": "Zellspannung messen",
"text": "<p>Das BMS muss jede Zellspannung mit ±2 mV messen.</p>",
"attributes": {"status": "entwurf", "prioritaet": "muss"}, "module": 3, "parent": 12}' \
https://engineering-toolbox.com/etrm/api/v1/projects/<id>/artifacts/
Antwort (gekürzt)
{"number": 131, "id": "#131", "uid": "6f1c…", "type": "systemanforderung", "title": "Zellspannung messen",
"text": "<p>…</p>", "attributes": {"status": "entwurf", "prioritaet": "muss"}, "tags": [], "rev": 1,
"deleted": false, "quality": [], "url": "…/artifacts/131/"}
Das Feld quality enthält die Hinweise der Formulierungsprüfung (z. B. vage Begriffe oder offene Punkte).
| GETprojects/<id>/tags/ | Schlagworte des Projekts mit color, active und count (Artefakte außerhalb des Papierkorbs). |
| GETprojects/<id>/artifacts/<nr>/tags/ | Schlagworte eines Artefakts. |
| POSTprojects/<id>/artifacts/<nr>/tags/ | Schlagworte anhängen: tags (Liste von Namen). Unbekannte Namen werden im Projekt angelegt. added nennt, was neu dazukam. |
| DELETEprojects/<id>/artifacts/<nr>/tags/<name>/ | Ein Schlagwort abnehmen. Es bleibt im Projekt erhalten; removed ist null, wenn es nicht anhing. |
| POSTprojects/<id>/tags/<name>/artifacts/ | Sammelaktion wie in der Tabelle: ein Schlagwort an mehrere Artefakte hängen (numbers, höchstens 500). |
| DELETEprojects/<id>/tags/<name>/ | Ein ungenutztes Schlagwort aus dem Projekt löschen (nur Gruppenadmins). Antwort: name und deleted. Hängt es noch an Artefakten (auch im Papierkorb), kommt 409 tag_in_use mit count. |
Es gelten dieselben Regeln wie in der Oberfläche: Groß- und Kleinschreibung spielt keine Rolle, Namen haben höchstens 50 Zeichen und kein Komma. Anhängen und Abnehmen lassen sich gefahrlos wiederholen, ändern rev nicht und erscheinen im Verlauf des Artefakts. Namen mit Sonderzeichen in der Adresse URL-kodieren.
Löschen lassen sich nur ungenutzte Schlagworte. Baselines und Verlauf behalten die Namen, frühere Stände bleiben dadurch unverändert.
Beispiel: zwei Schlagworte anhängen
curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" \
-d '{"tags": ["Sicherheit", "ASIL B"]}' \
https://engineering-toolbox.com/etrm/api/v1/projects/<id>/artifacts/131/tags/
Antwort (gekürzt)
{"number": 131, "tags": ["ASIL B", "Sicherheit"], "added": ["ASIL B"]}
| GETprojects/<id>/links/ | Liste. Filter: type, artifact (Nummer, Quelle oder Ziel), suspect=1. |
| POSTprojects/<id>/links/ | Anlegen mit type, source, target (Nummern). Es gelten die erlaubten Quell- und Zieltypen des Link-Typs. |
| DELETEprojects/<id>/links/<link>/ | Löschen. |
| POSTprojects/<id>/links/<link>/clear-suspect/ | Verdacht quittieren (geprüft, passt weiterhin). |
| GETprojects/<id>/modules/ | Liste der Module mit structure_rev. |
| GETprojects/<id>/modules/<modul>/ | Gliederung in Dokumentreihenfolge mit Nummer (1.2, 1.2-3), Tiefe, Artefakt, parent (Nummer der Überschrift) und position. Kopfzeile ETag enthält den Strukturstand. |
| POSTprojects/<id>/modules/<modul>/artifacts/ | Vorhandenes Artefakt einfügen: artifact (Nummer), optional parent und position. Ohne Angabe ans Ende der obersten Ebene. |
| GETprojects/<id>/modules/<modul>/artifacts/<nr>/ | Stelle eines Artefakts im Modul. |
| PATCHprojects/<id>/modules/<modul>/artifacts/<nr>/ | Überschrift (parent, null für die oberste Ebene) und/oder position ändern. Untergeordnete Artefakte wandern mit. |
| DELETEprojects/<id>/modules/<modul>/artifacts/<nr>/ | Aus dem Modul entfernen. Das Artefakt bleibt mit Nummer, UID, Historie und Links im Projekt; untergeordnete Artefakte rücken an seine Stelle. |
position zählt ab 0 innerhalb der Ebene, Artefakte im Papierkorb zählen nicht mit. Ein Artefakt steht in einem Modul höchstens einmal, in mehreren Modulen ist es dasselbe Artefakt.
Gleichzeitige Änderungen: Senden Sie den gelesenen ETag im Kopf If-Match (oder als structure_rev im Inhalt) mit. Hat sich die Gliederung inzwischen geändert, auch in der Oberfläche, kommt 409 mit der aktuellen Gliederung in current. Ohne Angabe wird nicht geprüft.
Beispiel: Artefakt unter Überschrift #12 an die erste Stelle einfügen
curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" -H 'If-Match: "s-7"' \
-d '{"artifact": 131, "parent": 12, "position": 0}' \
https://engineering-toolbox.com/etrm/api/v1/projects/<id>/modules/3/artifacts/
| GETprojects/<id>/baselines/ | Liste. |
| POSTprojects/<id>/baselines/ | Neuen Stand anlegen: name, optional note und module. |
| GETprojects/<id>/baselines/<b>/ | Eine Baseline; mit ?payload=1 der vollständige, unveränderliche Stand. |
| GETprojects/<id>/baselines/<b>/compare/ | Unterschiede zum aktuellen Stand oder mit ?with=<b> zu einer anderen Baseline: neu, entfernt, geändert, verschoben, Links. |
Fehler kommen als JSON mit error (Kennung) und message (Text), bei ungültigen Angaben zusätzlich details je Feld.
| 400 | ungültige Angaben (validation, invalid_json, invalid_parameter) |
| 401 | Token fehlt, ist unbekannt oder widerrufen |
| 403 | Rolle reicht nicht, Token darf nur lesen oder kein aktives Zusatz-Abo ETRM API (subscription_required) |
| 404 | nicht gefunden (auch Projekte, in denen Sie kein Mitglied sind) |
| 405 | Methode nicht erlaubt |
| 409 | Konflikt: Das Artefakt oder die Modulgliederung wurde inzwischen geändert (Antwort enthält current), das Artefakt liegt im Papierkorb oder steht schon im Modul (already_bound) |
{"error": "validation", "message": "Die Angaben sind nicht gültig.", "details": {"prioritaet": ["Pflichtfeld."]}}