Advertising

REST API v1

Read and write artifacts, links, modules and baselines from your own programs, scripts or CI pipeline.

Authentication

The REST API requires the ETRM API add-on to your own Single or Team subscription. Without both subscriptions it responds with status 403 and the error code subscription_required.

Create an access key under Profile, API access and send it with every request in the Authorization header. The key acts with your rights in the groups. Keys without write permission can only read.

curl -H "Authorization: Bearer etrm_…" https://engineering-toolbox.com/etrm/api/v1/

Basics

  • Base address: https://engineering-toolbox.com/etrm/api/v1/. Requests and responses are JSON (UTF-8).
  • Projects have the same ID as in the addresses of the user interface. Artifacts are addressed by their number (#12 becomes 12).
  • Permissions as in the user interface: reading requires the role READ, creating, changing and deleting the role EDIT.
  • Lists are paginated: parameters limit (at most 500, default 100) and offset; the response contains count and next_offset.
  • Texts are restricted rich text (HTML). The server sanitises them as when saving in the user interface.
  • Every change creates a new version in the history and marks links as suspect, as in the user interface.

Projects

GETprojects/Your projects with role (archived ones with ?archived=1).
GETprojects/<id>/Project with configuration: artifact types, attributes with allowed values, link types, modules.
GETprojects/<id>/metrics/Metrics as in the dashboard: size, coverage, suspect links, volatility, wording hints.

Artifacts

GETprojects/<id>/artifacts/List. Filters: type (multiple), module, tag (multiple, any one matches), q (full text), changed_since (ISO 8601), attr.<key>=<value>, deleted=1 (including trash).
POSTprojects/<id>/artifacts/Create. Optionally with tags (list), module, parent (number of a heading in the module) and position.
GETprojects/<id>/artifacts/<nr>/One artifact with modules and links.
PATCHprojects/<id>/artifacts/<nr>/Change title, text, type, attributes and tags (replaces the whole list). rev (current state) is required; if the artifact has changed in the meantime, 409 is returned with the current state. In attributes, null removes a value.
DELETEprojects/<id>/artifacts/<nr>/Move to trash (can be restored in the user interface).

Example: create a system requirement

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/

Response (shortened)

{"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/"}

The field quality contains the hints of the wording check (e.g. vague terms or open points).

Tags

GETprojects/<id>/tags/Tags of the project with color, active and count (artifacts outside the trash).
GETprojects/<id>/artifacts/<nr>/tags/Tags of an artifact.
POSTprojects/<id>/artifacts/<nr>/tags/Add tags: tags (list of names). Unknown names are created in the project. added lists what was newly attached.
DELETEprojects/<id>/artifacts/<nr>/tags/<name>/Remove a tag from the artifact. It remains in the project; removed is null if it was not attached.
POSTprojects/<id>/tags/<name>/artifacts/Bulk action as in the table: attach one tag to several artifacts (numbers, at most 500).
DELETEprojects/<id>/tags/<name>/Delete an unused tag from the project (group admins only). Response: name and deleted. If it is still attached to artifacts (including the trash), the response is 409 tag_in_use with count.

The same rules apply as in the user interface: upper and lower case do not matter, names have at most 50 characters and no comma. Adding and removing can be repeated safely, do not change rev and appear in the artifact's history. URL-encode names with special characters in the address.

Only unused tags can be deleted. Baselines and history keep the names, so earlier states remain unchanged.

Example: add two tags

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/

Response (shortened)

{"number": 131, "tags": ["ASIL B", "Sicherheit"], "added": ["ASIL B"]}

Modules

GETprojects/<id>/modules/List of modules with structure_rev.
GETprojects/<id>/modules/<modul>/Outline in document order with number (1.2, 1.2-3), depth, artifact, parent (number of the heading) and position. The ETag header contains the structure state.
POSTprojects/<id>/modules/<modul>/artifacts/Insert an existing artifact: artifact (number), optionally parent and position. Without them, at the end of the top level.
GETprojects/<id>/modules/<modul>/artifacts/<nr>/Position of an artifact in the module.
PATCHprojects/<id>/modules/<modul>/artifacts/<nr>/Change the heading (parent, null for the top level) and/or position. Subordinate artifacts move along.
DELETEprojects/<id>/modules/<modul>/artifacts/<nr>/Remove from the module. The artifact remains in the project with its number, UID, history and links; subordinate artifacts take its place.

position counts from 0 within the level; artifacts in the trash are not counted. An artifact appears at most once per module; in several modules it is the same artifact.

Concurrent changes: send the ETag you read in the If-Match header (or as structure_rev in the body). If the outline has changed in the meantime, including in the user interface, you get 409 with the current outline in current. Without it, no check is made.

Example: insert an artifact as the first item under heading #12

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/

Baselines

GETprojects/<id>/baselines/List.
POSTprojects/<id>/baselines/Create a new state: name, optionally note and module.
GETprojects/<id>/baselines/<b>/One baseline; with ?payload=1 the complete, immutable state.
GETprojects/<id>/baselines/<b>/compare/Differences to the current state or, with ?with=<b>, to another baseline: new, removed, changed, moved, links.

Error

Errors are returned as JSON with error (code) and message (text), for invalid input additionally details per field.

400invalid input (validation, invalid_json, invalid_parameter)
401token missing, unknown or revoked
403Role not sufficient, token may only read, or no active ETRM API add-on (subscription_required)
404not found (also projects in which you are not a member)
405method not allowed
409conflict: the artifact or the module outline has been changed in the meantime (response contains current), the artifact is in the trash or is already in the module (already_bound)
{"error": "validation", "message": "Die Angaben sind nicht gültig.", "details": {"prioritaet": ["Pflichtfeld."]}}