Developer guide
The API
The front end is a client of the app's JSON API, and so can anything else: every page's data comes from it. The app
describes the whole API itself, as OpenAPI, at /api/docs (interactive) and /api/openapi.json.
Its parts
| Prefix | What |
|---|---|
/api/app, /api/me, /api/home |
The site, the menu, the documents of clauses 6 to 10, the installed plugins; who is signed in; the home page's figures |
/api/auth/... |
Sign in, sign out, change password |
/api/help, /api/help/{page}, /api/help/images/{name} |
The user guide, as Markdown (the in-app help) |
/api/jobs, /api/tasks |
Jobs (queue, progress, log, stop) and scheduled tasks |
/api/settings/..., /api/secrets, /api/people, /api/claude |
Settings (site admins) |
/api/org-context/... |
The documents: analyses (list, get, write a new one, save, approve, copy, discard, compare, export as docx, xlsx, md, sharepoint), comments, images, reviews (and reviews/map, the document map), the facts |
/api/drawings/... |
The drawing register: runs, documents, review, corrections, EAM, the folder pages |
/api/assets/... |
Asset information: the registers, uploads and comparisons, the structure, Claude's proposals, the EAM load workbook |
/api/plugins/... |
Installed plugins: records, workflow steps, actions, proposals, activity; /api/plugins/requests asking for a plugin (anyone signed in); /api/plugins/admin installing (company admins) and settings (site admins) |
/api/company, /api/platform/..., /api/publish/... |
On hosted IMS Creator: company administration, the platform console, the publisher portal |
Signing in and permissions
- Roles. Reading (
GET) needs viewer; changing needs engineer; settings, secrets, tasks, people, the Claude connection and a plugin's settings need site admin; installing, updating and removing a plugin need a company admin (on a site of its own, a site admin). Asking for a plugin (POST /api/plugins/requests) needs only viewer. - CSRF. Every change (
POST,PUT,PATCH,DELETE) must carry the headerX-ORT-Request: 1, which another site's page cannot add. - Long work answers at once with a job number: follow it at
/api/jobs/{id}(its state, progress and log), or on Tasks.
Examples
With a session cookie from signing in (saved by curl -c and sent with -b):
# sign in (a single-site app)
curl -c jar -H 'X-ORT-Request: 1' -H 'Content-Type: application/json' \
-d '{"login": "admin", "password": "..."}' http://127.0.0.1:8765/api/auth/login
# the approved risk register, as JSON
curl -b jar 'http://127.0.0.1:8765/api/org-context/analyses?kind=risk_register'
curl -b jar http://127.0.0.1:8765/api/org-context/analyses/83
# its Word report
curl -b jar -o risks.docx http://127.0.0.1:8765/api/org-context/analyses/83/export.docx
# a plugin's records
curl -b jar http://127.0.0.1:8765/api/plugins/controls-tracker/records/control