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

AppClientAppClientPOST /api/auth/login {login, password} (hosted: email, then code, then password)Set-Cookie: the session (HttpOnly, SameSite)GET /api/org-context/analyses?kind=risk_register (cookie)200 JSONPOST /api/org-context/analyses/84/approve (cookie + X-ORT-Request: 1)200, or 403 for a role without the right
  • 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 header X-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

See also