API reference
REST. JSON in, JSON out. Token auth.
Base URL
All endpoints below are rooted at /api/v1 on your own instance, for example
https://tprm.example.com/api/v1.
Authentication
An administrator generates API keys under Organization > API keys in the UI.
Keys are formatted mlab_ + a unique identifier. Send the key in the
Authorization header using the token scheme:
curl -H "Authorization: token mlab_a1b2c3d4e5f6" \
https://tprm.example.com/api/v1/providers/Free tier is read-only. On the Free tier, API keys can only perform GET
requests. Writes require the Licensed tier and return 403 otherwise.
Conventions
Collection paths end with a slash (/providers/). Writes are POST to a verb
suffix rather than REST verbs on the collection: /create, /update, and
DELETE on /delete. The target of an update or a delete is identified by a
uuid field in the JSON body, not in the path.
POST /api/v1/providers/update
{
"uuid": "b6f1...",
"name": "Acme Cloud",
"criticality": "critical"
}Errors
Standard HTTP codes. The body is always { "error": "human-readable message" }.
| Code | Meaning |
|---|---|
400 | Validation error, or an SQL constraint surfaced from the write. |
401 | Missing or invalid token, or no organisation resolved from the key. |
403 | Licensed-only feature, or a write attempted on the Free tier. |
404 | Unknown route, or the record does not exist. |
Providers
| Endpoint | Method | Purpose |
|---|---|---|
/providers/ | GET | List ICT third-party providers. |
/providers/count | GET | Provider count for the organisation. |
/providers/stats | GET | Aggregates by criticality, category and status. |
/providers/create | POST | Register a provider (Licensed). Feeds B_05.01. |
/providers/update | POST | Update a provider (Licensed). |
/providers/delete | DELETE | Remove a provider (Licensed). |
Contracts and services
| Endpoint | Method | Purpose |
|---|---|---|
/contracts/ | GET | List contractual arrangements. Feed B_02.01, B_02.02, B_03.x and B_04.01. |
/contracts/create · /contracts/update | POST | Write an arrangement. contract_ref is mandatory and unique. |
/contracts/delete | DELETE | Remove an arrangement. |
/contract_services/ | GET | Services carried by an arrangement, each with its own nature. |
/contract_services/create · /update | POST | Declare a service. service_nature is ict, non_ict or other. |
/contract_services/delete | DELETE | Remove a service. |
/contracts/gdpr/ · /contracts/gdpr/{uuid} | GET | GDPR processor agreement, sub-processors and transfers, per contract. |
/contracts/gdpr/save | POST | { "contract_uuid": "...", "data": {...} }. Signed-in sessions only. |
/contracts/notice/ · /contracts/notice/{uuid} | GET | Art. 28(3): contracts that need the competent authority informed, with their status (notified, missing, not_required). Licensed. |
/contracts/notice/save | POST | { "contract_uuid": "...", "data": { "notified_date": "yyyy-mm-dd", "authority": "...", "reference": "...", "notes": "..." } }. Licensed, signed-in sessions only. |
Contract documents have their own endpoints, for signed-in sessions only: see Documents.
Only ICT services reach the register. An arrangement with no service at all blocks the export until it is classified. See EBA export.
Risk assessments
| Endpoint | Method | Purpose |
|---|---|---|
/assessments/ | GET | List assessments. Feeds B_07.01. |
/assessments/create · /update | POST | Write an assessment. Overall score plus operational, security, compliance, financial and concentration scores. |
/assessments/new-version | POST | Open a new version of an assessment. |
/assessments/submit-approval · /approve · /reject | POST | Drive the approval workflow. |
/assessments/delete | DELETE | Remove an assessment. |
Register modules
Each of these follows the same shape: GET on the collection, POST on
/create and /update, DELETE on /delete.
| Resource | Path | Feeds |
|---|---|---|
| Reporting entity | /entity_info/ (GET, /update) | B_01.01 |
| Scope entities | /scope_entities/ | B_01.02 |
| Branches | /branches/ | B_01.03 |
| Intra-group links | /intragroup/ | B_02.03 |
| Business functions | /functions/ (plus /link-provider, /unlink-provider) | B_06.01 |
| Supply chains | /subcontracting/ | B_05.02 |
| Material subcontracting changes | /subcontracting/changes/ (GET, /save, /delete) | RTS 2025/532 Art. 5-6 |
| Register definitions | /definitions/ (GET, /update) | B_99.01 |
| Third-party incidents | /tp_incidents/ | Incident tracking |
| Exit strategies | /exits/ | Art. 28(8), derived plan existence |
| Due diligence | /due_diligence/ (plus GET /{uuid}/supervision: suggestions for the Art. 28(4)(b) checks) | Art. 28(4) |
| Audit tracking | /audit_log/ | Art. 28(5)-(6) |
| Art. 30 checklist | /art30/ | Art. 30(2)/(3) |
| Proportionality register | /proportionality/ | Proportionality decisions |
| Provider reviews | /reviews/ | Annual monitoring |
Incident classification (DORA)
Licensed. One classification per third-party incident.
| Endpoint | Method | Purpose |
|---|---|---|
/tp_incidents/dora/ | GET | Every incident with its classification, major verdict and deadlines. |
/tp_incidents/dora/{uuid} | GET | One incident: criteria, thresholds met, verdict and its legal basis, recurring incidents, deadlines. |
/tp_incidents/dora/save | POST | Save the classification of an incident. |
/tp_incidents/dora/{uuid}/report/{kind} | GET | Report draft laid out as Implementing Regulation 2025/302; kind is initial, intermediate or final. |
Reference data
GET /nca/ and GET /nca/{authority_code}
The DORA Article 2(1) entity-type catalogue and, per competent authority, the
subset it supervises. An authority with no entry returns "authority": null,
which callers should treat as the generic case rather than an error.
Risk analysis
| Endpoint | Method | Purpose |
|---|---|---|
/risks/summary | GET | Portfolio counts and average risk score. |
/risks/concentration | GET | Concentration by criticality, category, country, status and data access, and the Art. 29 assessment per provider (Licensed). |
/risks/ctpp | GET | Designated CTPPs among your providers and their suspension/termination readiness (Art. 42) (Licensed). |
EBA export
| Endpoint | Method | Purpose |
|---|---|---|
/eba_export/ | GET | All 15 templates as JSON rows with eba_* codes resolved. |
/eba_export/download | GET | The templates as CSV. ?template=b_02_02 returns a single one. |
/eba_export/validate | GET | The EBA checks (reception, keys, foreign keys, allowed values, business rules, optional identifier checks), by category and severity. |
/eba_export/feedback | GET | The same findings as the EBA's detailed-feedback.csv. |
/eba_export/package | GET | The deposit-ready xBRL-CSV package as a file map. |
download and package return 400 while any arrangement is unclassified, with
the list of arrangements at fault. See
EBA export.
Register view
| Endpoint | Method | Purpose |
|---|---|---|
/register/ | GET | The aggregate register view with per-provider completion scoring. |
/register/export | GET | The register as CSV (Licensed). |
Public footprint
| Endpoint | Method | Purpose |
|---|---|---|
/providers/footprint/{uuid} | GET | The provider's last scan, the mlab.sh key status and quota. Never starts a scan. |
/providers/footprint/start | POST | { "provider_uuid": "...", "domain": "example.com", "force": false }. Reuses a scan under 7 days old unless force is true. Signed-in sessions only. |
Organisation settings
Administrators only, from a signed-in session.
| Endpoint | Method | Purpose |
|---|---|---|
/orga/sso · /orga/update/sso | GET · POST | Single sign-on settings. The client secret is never returned. |
/orga/mlab_api_key · /orga/update/mlab_api_key | GET · POST | mlab.sh API key: whether it is set and its last 4 characters; an empty key removes it. |
/orga/mlab_api_key/test | GET | Asks mlab.sh whether the key is valid, and the domain scans left. |
/orga/update/identifier_check | POST | { "enabled": true }: online LEI checks during validation. |
/orga/update/reporting_framework | POST | { "framework": "dora" } or "none". |
Dashboards and licensing
| Endpoint | Method | Purpose |
|---|---|---|
/dashboards/stats · /dashboards/activity | GET | Overview counters and recent activity. |
/license/status · /license/info | GET | Current tier, limits and validation state (status is admin only). |
/license/check | POST | Admin only. Check the license with mlab.sh now. |
/license/takeover | POST | Admin only. Take a place when every place is taken; the instance heard from least recently gives up its place. |