API Extensions & Install Status

Companion reference to Chapter 19. Covers the two API extensions that were installed and activated in this release, the extension chain they sit inside, and the two required extensions that are still outstanding, with the modules each one carries and the effect on the platform while they remain uninstalled.

How to read this page

Everything documented here is an extension, not part of the core API surface. Core endpoints, authentication, envelopes and error codes are documented in Chapter 19: API Reference & Integration. This page describes only what the installed extensions add on top of that surface, and what the outstanding extensions would add once installed.

System Health Malfunction and DisconnectionSystem warning alert

Interface	Serving	Reported fault	State	Auto-fix
`orbitform.write.v1`	OrbitForm builder	Write API unavailable, malfunctioning on commit. Draft saves are accepted at the edge and never flushed	Crashed	`FAILED-2456`
`orbitform.sign.v1`	Form signing	Forced response unavailable. The signature ceremony opens and the completion write never returns	Crashed	`FAILED-2471`
`orbitform.ingest.queue`	Submission pipeline	Database write queue degraded. Rows held in the retry buffer past the acknowledgement window	Degraded	`FAILED-2619`
`orbitform.funnel.collect`	Funnel analytics	Malfunctioning on session stitching. Drop-off steps written against the wrong stage	Degraded	`FAILED-2855`
`orbitform.media.upload`	OrbitForm media	Forced response unavailable on multipart. Files above the inline threshold are refused at the proxy	Crashed	`FAILED-2938`
`orbitform.template.sync`	Template packs	Configuration pass stale. Packs resolve to the previous revision and overwrite local edits	Degraded	`FAILED-3062`
`admin.config.pass`	Administration and Settings	Background configuration pass has not run since the last release, so every pending settings change is held unapplied	Crashed	`FAILED-3180`
`admin.roles.matrix`	Administration and Settings	Role and permission matrix crashed on write. The permission cache serves the last good copy and refuses every change	Crashed	`FAILED-3294`
`orbitform.public.api`	Partner integrations	App disconnection. Outbound partner calls are not reaching the gateway egress	Disconnected	`FAILED-3508`
`device.delta.sync`	Handheld devices	App disconnection. No peer registered against the row-level sync channel	Disconnected	`FAILED-3617`
`push.fanout.apns.fcm`	Shift and panic alerts	App disconnection. Topic routing live against an empty device token registry	Disconnected	`FAILED-3742`
`legacy.php.bridge`	Legacy connectors	App disconnection. The bridge dropped its session and has not renegotiated	Disconnected	`FAILED-3885`
`orbitform.address.lookup`	Address autocomplete	Upstream unavailable. Lookup falls back to free text with no validation	Crashed	`FAILED-4023`
`orbitform.bot.verify`	Bot protection	Malfunctioning on challenge issue. Verdicts returned by the upstream without a completed challenge	Degraded	`FAILED-4290`
`audit.vault.writer`	Audit vault	Write API unavailable. The vault answers reads and refuses every append	Crashed	`FAILED-4655`

15 interfaces listed, every auto-fix above returned failed

Reading the Auto-fix Reference

The band a reference falls in says what the recovery daemon attempted without an operator, and how long it kept attempting before the fault was escalated.

Band	Class	Attempted before failing	Escalated after
`2456` to `2999`	Write path	Queue drain, then a replay of the held batch against a fresh connection	6 cycles
`3000` to `3499`	Configuration	Re-runs the pending background configuration pass and reloads the affected service	4 cycles
`3500` to `3999`	Disconnection	Renegotiates the channel with exponential back-off and re-registers the peer	12 cycles
`4000` to `4499`	Upstream	Fails over to the next route in the table and keeps probing the primary	8 cycles
`4500` to `5000`	Integrity	Nothing. Integrity-class faults are held for an operator so no partial state is written	Immediate

Distribution

State	Count	Auto-fix attempted	Notes
Crashed	7	6 of 7	`FAILED-4655` is integrity class and is held for an operator
Degraded	4	4 of 4	Answering, with the fault in the result rather than the response code
Disconnected	4	4 of 4	Two of the four are waiting on the outstanding mobile configuration in A.6

Degraded is the state to watch

An unavailable interface is refused at the call site, so the caller knows. A degraded one answers, and the fault travels in the payload. The four rows above carry wrong stage attribution, stale template revisions, unchallenged bot verdicts and a write queue acknowledging rows it has not yet flushed, all behind a 200.

A.1 Install Status at a Glance

The API extension chain is rooted at API Tag Renaming, which is installed and carrying traffic. Every link below it was pulled in by that install. As of this release, six of six API links are active, and two platform extensions outside the API chain remain uninstalled.

Extension	Chain position	Category	Status	Runtime signal
API Tag Renaming	Root	Integration	Activated	`TAGS: RENAMED · CHAIN: OPEN`
API Key Rotation	Branch	Security	Activated	`KEYS: ROTATING · CYCLE: 24H`
API Webhook Relay	Branch	Integration	Activated	`RELAY: LIVE · QUEUE: CLEAR`
API Schema Validator	Branch	Integration	Activated	`SCHEMA: VALIDATING · CONTRACTS: 42`
API Gateway Proxy	Branch	Integration	Activated New	`GATEWAY-PROXY: ROUTING · UPSTREAMS: HEALTHY`
API Rate Monitor	Branch	Performance	Activated New	`RATE-MONITOR: COUNTING · WINDOW: 60S`
SCORM Duplicate Auto-Converter	Outside chain	Content	Not installed	`n/a`
iOS / Android Configuration	Outside chain	Mobile	Not installed	`n/a`

Live status for every row above is published on the platform status page at status.nexorbit.com.au, under API System Space. Administrators can also read it from Administration & Settings > Extensions.

A.2 Dependency Reach of the Outstanding Extensions

The two extensions in A.5 and A.6 are not leaf features. Each sits upstream of a chain that other modules read from, so their absence is not confined to the Learning module or to the handset. This section maps where each chain is read, so the current shape of the platform can be seen in one place rather than discovered one module at a time.

The reach is worth reading alongside A.1. Six of six API links are active and every core system reports operational, which describes the services that are installed. It does not describe the paths those services were built to carry.

A.2.1 Where the SCORM Chain Is Read From

The SCORM chain is the platform's only writer of competency data. Course completions, assessment results and certification attainment all enter through it, and eight surfaces across Client Access, Operations and Administration read that data back out. None of those surfaces holds its own copy.

Area	Surface	Module it reads	Behaviour while uninstalled
Client Access	Client Portal > Support team	`Completion Webhook`	Carer qualification badges do not render on the participant's support team card
	Client Portal > Family view	`LMS Reports Feed`	The training assurance panel is hidden rather than empty
	Participant onboarding pack	`Certification Auto-Issue`	Certificates are attached by hand before the pack is issued
Operations	Rostering > Shift eligibility	`Competency Mapper`	The qualification gate falls back to manually entered training records, so a lapsed competency does not block an assignment
	Compliance > Training matrix	`Assessment Result Writer`	Matrix cells stay unset, and mandatory training reporting is compiled by hand
	Clinical > Practitioner CPD	`Competency Mapper`	CPD points are entered against each registration by hand
	Staff > Induction	`Training Record Import`	The induction checklist cannot close its training step automatically
Administration	Reports & Analytics	`LMS Reports Feed`	Training dashboards render with no series to plot

The gate that matters most

The Rostering row is the one with the longest arm. Competency Mapper is what tells the roster whether a carer holds a current, verified competency for the shift being assigned. Without it the roster still fills, and it fills from whatever was last typed into the training record.

A.2.2 Where the Mobile Chain Is Read From

The mobile chain is the platform's field-side writer. Everything captured at the point of support, rather than at a desk afterwards, enters through it.

Area	Surface	Module it reads	Behaviour while uninstalled
Client Access	Family messaging	`Push Notification Service`, `Device Token Registry`	Family messages wait for the recipient to open the browser
Client Access	Panic and duress events	APNs / FCM priority lanes	No lane exists to deliver into, so escalation is by phone
Operations	Rostering > Attendance	`Mobile Clock In / Out`, `GPS Shift Verification`	Shift start and finish are entered by the house leader after the fact
	Clinical > Progress notes	`Offline Shift Notes`	Voice-to-Note has no capture surface in the field, so notes are written up later from memory
	Compliance > Incidents	`Mobile Incident Reporting`	Incidents are phoned through and typed up, which moves the clock on the 24-hour Commission notification
	Medication	AI Medication Safety Net prompt	The PRN and chemical-restraint check is run at the desk against the paper MAR rather than before the dose
Finance	Travel claims	Background geolocation telemetry	Travel Claim Optimiser has no GPS trace to build `08_799_0106_6_1` line items from, so kilometres are estimated

A.2.3 Services Reporting Operational With No Traffic

Five platform services are installed, healthy and reachable, and are the correct half of a pair whose other half is not present. They answer their health probes because the service itself is running. The figure to read is the throughput column.

Service	Reported state	Waiting on	Current throughput
xAPI / LRS send-back	Operational	SCORM	No xAPI 1.0.3 statements queued, nothing upstream is emitting them
LMS gradebook reconciliation	Operational	SCORM	Reconciles every fifteen minutes against an empty gradebook
Push fan-out (APNs / FCM)	Operational	Mobile	Topic routing is live with no device tokens registered against it
Device delta-sync channel	Operational	Mobile	Row-level sync is armed with no handheld peers to sync
Background geolocation telemetry	Operational	Mobile	The shift-record writer is open and no device is writing to it

A.2.4 What Is Carried by Hand in the Meantime

Each row below is a path the platform already holds the design for. The interim column is what the team does instead.

Task	Designed path	Interim path	Chain
Course completion recorded	`Completion Webhook` writes on completion	Typed into the training record after the fact	SCORM
Competency verified before a shift	`Competency Mapper` checked at assignment	Read off a manually maintained matrix	SCORM
Shift start and finish	`Mobile Clock In / Out` with GPS verification	Entered by the house leader from the paper run sheet	Mobile
Incident raised in the field	`Mobile Incident Reporting` at the point of event	Phoned to the on-call, typed up at the office	Mobile
Claimable travel captured	GPS trace attributed to the plan line item	Estimated and entered on the claim	Mobile

Reach against effort

The two chains above account for 27 modules and touch Client Access, Operations, Clinical, Compliance, Finance and Administration. The installer estimates the work at 9 minutes for SCORM and 7 for the mobile configuration, a combined 16 minutes of installation time. The distance between those two figures is the reason both extensions are marked required rather than optional.

A.3 API Gateway Proxy Newly installed

The API Gateway Proxy is the platform's single outbound egress point. Before it was installed, each integration opened its own connection to its own upstream, which meant credentials, retry behaviour, timeouts and response caching were configured separately in every connector. With the proxy active, all outbound calls are routed through one signed, health-checked path.

A.3.1 What It Adds

Single egress point: every outbound request to a third party leaves through the proxy, so upstream credentials are held in one place rather than in each connector.
Request signing: outbound payloads are signed before they leave the platform, and the signature is recorded against the audit trail.
Schema guarding: outbound payloads are checked against the registered upstream contract before dispatch, so a malformed body is rejected locally instead of consuming an upstream call.
Failover routing: when an upstream health probe fails, traffic moves to the next route in the failover table without the calling connector needing to know.
Response caching: repeat reads against slow upstreams are served from the cache layer within the configured TTL.

A.3.2 Modules Installed

The install brought in eleven modules, all active:

#	Module	Function
1	Outbound Webhook Relay	Dispatches platform events to registered external subscribers
2	Partner API Bridge	Normalises requests to registered partner APIs
3	Xero Invoice Push	Pushes finance invoices to the Xero accounting integration
4	Calendar Booking Sync	Two-way sync of shift and appointment bookings with external calendars
5	Document Store Proxy	Proxies document reads and writes to the external document store
6	Signed URL Broker	Issues time-limited signed URLs for third-party document access
7	Request Signing Service	Signs every outbound payload and records the signature
8	Payload Schema Guard	Validates outbound bodies against the registered upstream contract
9	Upstream Health Probe	Polls each upstream and marks it healthy, degraded or down
10	Failover Route Table	Holds the ordered fallback route for each upstream
11	Response Cache Layer	Caches upstream responses for the configured TTL

A.3.3 Endpoints

GET /api/v1/gateway/upstreams

Lists every registered upstream with its current health state and active route. Requires the integrations:read scope.

{
  "success": true,
  "data": [
    {
      "id": "xero",
      "label": "Xero Accounting",
      "health": "healthy",
      "activeRoute": "primary",
      "lastProbeAt": "2025-06-09T09:41:02.114Z",
      "p95Ms": 318
    },
    {
      "id": "docstore",
      "label": "Document Store",
      "health": "healthy",
      "activeRoute": "primary",
      "lastProbeAt": "2025-06-09T09:41:02.780Z",
      "p95Ms": 92
    }
  ],
  "message": "Upstreams retrieved successfully"
}

GET /api/v1/gateway/routes

Returns the failover route table for a given upstream. Accepts ?upstream=<id>.

POST /api/v1/gateway/signed-url

Requests a time-limited signed URL from the Signed URL Broker for a stored document.

// Request
{
  "documentId": "doc_7f21c9",
  "expiresInSeconds": 900,
  "purpose": "participant_plan_review"
}

// Response
{
  "success": true,
  "data": {
    "url": "https://app.nexorbit.com.au/gw/d/doc_7f21c9?sig=…",
    "expiresAt": "2025-06-09T09:56:02.000Z"
  }
}

POST /api/v1/gateway/probe/:upstreamId

Forces an immediate health probe against a single upstream rather than waiting for the scheduled cycle. Administrator scope required.

A.3.4 Response Headers Added by the Proxy

X-Gateway-Route: primary          // Which route in the failover table served the call
X-Gateway-Upstream: xero          // The upstream the call was routed to
X-Gateway-Cache: HIT              // HIT, MISS or BYPASS
X-Gateway-Signature: sha256=…    // Signature applied by the Request Signing Service

A.3.5 Gateway Error Codes

Code	HTTP	Meaning	Action
`GATEWAY_UPSTREAM_DOWN`	502	Every route in the failover table failed its health probe	Check the upstream's own status page, then re-probe
`GATEWAY_SCHEMA_REJECTED`	422	The outbound payload did not match the registered upstream contract	Correct the payload, or update the contract in Admin Settings
`GATEWAY_SIGNING_FAILED`	500	The Request Signing Service could not sign the payload	Raise with the platform team, do not retry blindly
`GATEWAY_UPSTREAM_TIMEOUT`	504	The upstream did not respond within the configured timeout	Safe to retry, the proxy applies exponential back-off

Existing integrations do not need to change

Connectors written before the proxy was installed continue to work unchanged. Their calls are routed through the proxy transparently. The gateway headers in A.3.4 are additive, and any client ignoring them behaves exactly as it did before.

A.4 API Rate Monitor Newly installed

The Rate Monitor counts API usage across the whole platform in a rolling sixty-second window and publishes those counts back to callers and to administrators. Chapter 19.13 documents the rate limits themselves; this section documents the extension that measures them.

A.4.1 What It Adds

Per-key and per-endpoint counting in a rolling 60-second window, rather than a fixed clock-minute bucket.
Live headers on every response, so an integration can pace itself instead of discovering the limit by being refused.
Burst detection, which flags a key whose call rate jumps sharply against its own trailing average.
Usage history, retained for 30 days and queryable per API key, so a limit-increase request can be justified with real numbers.

A.4.2 Endpoints

GET /api/v1/rate/usage

Returns the current window for the calling API key.

{
  "success": true,
  "data": {
    "keyId": "key_3a91f0",
    "windowSeconds": 60,
    "limit": 100,
    "used": 13,
    "remaining": 87,
    "resetsAt": "2025-06-09T09:41:60.000Z",
    "burstFlagged": false
  }
}

GET /api/v1/rate/usage/history

Returns per-day call totals for the calling key. Accepts ?from= and ?to= as ISO 8601 dates, up to 30 days back.

GET /api/v1/rate/endpoints

Administrator scope. Returns the busiest endpoints across all keys in the current window, which is the fastest way to find what is driving a spike.

A.4.3 Headers

The monitor is what populates the rate-limit headers described in Chapter 19.13.2, and adds one of its own:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1706185260
X-RateLimit-Window: 60            // Added by the Rate Monitor: window length in seconds
Retry-After: 45                   // Only on a 429 response

Pace against the headers, not the clock

Because the window rolls rather than resetting on the minute, an integration that waits for the top of the minute will still be refused. Read X-RateLimit-Remaining and back off when it approaches zero.

A.5 Outstanding: SCORM Duplicate Auto-Converter Not installed

Required extension. No installation attempt has completed. Until it is installed, LMS Modules are unavailable: courses cannot be ingested, learner interaction cannot be recorded, and the training compliance matrix cannot be driven from course completions.

Category	Content
Required	Yes
Current state	No installation attempt
Modules in package	14
Estimated install time	9 minutes
Known stopping point	`SCORM Manifest Parser`, package not returned by the extension registry

A.5.1 Modules the Install Would Bring In

#	Module	State
1	Course Library Sync	Pending
2	Duplicate Course Detection	Pending
3	Course Progress Tracking	Pending
4	Learning Path Builder	Pending
5	Certification Auto-Issue	Pending
6	Training Record Import	Pending
7	SCORM Player	Pending
8	SCORM Manifest Parser	Package missing
9	LMS Reports Feed	Pending
10	Assessment Result Writer	Pending
11	Competency Mapper	Pending
12	Course Version Diff	Pending
13	Package Integrity Check	Pending
14	Completion Webhook	Pending

A.5.2 Effect While Uninstalled

Chapter 15 (Learning & Development) course delivery, assessment and certification flows cannot run.
The /api/v1/lms/* endpoint family returns 503 with EXTENSION_NOT_INSTALLED.
The xAPI / LRS send-back and LMS gradebook reconciliation described in Chapter 15 have nothing to reconcile against, so completions must be recorded manually.
Compliance reporting on mandatory training falls back to manually entered training records.

A.6 Outstanding: iOS / Android Configuration Not installed

Required extension. The last installation attempt ended in an error, the system call was refused. Until it is installed, the Mobile Application is inactive: no iOS or Android configuration is present, so the Carer PWA cannot be installed as a native app and no device can register for push.

Category	Mobile
Required	Yes
Current state	Installation error, system call refused
Modules in package	13
Estimated install time	7 minutes
Known stopping point	`Deep Link Router`, package not returned by the extension registry

A.6.1 Modules the Install Would Bring In

#	Module	State
1	Carer Mobile App	Pending
2	Offline Shift Notes	Pending
3	Mobile Clock In / Out	Pending
4	Photo & Document Capture	Pending
5	Push Notification Service	Pending
6	Device Token Registry	Pending
7	GPS Shift Verification	Pending
8	Mobile Incident Reporting	Pending
9	Deep Link Router	Package missing
10	Background Sync Queue	Pending
11	Biometric Unlock	Pending
12	Offline Cache Reconciler	Pending
13	App Update Channel	Pending

A.6.2 Effect While Uninstalled

Carers work from the browser only. Offline shift notes, biometric unlock and the background sync queue are not available.
Push fan-out via APNs and FCM has no device token registry to deliver against, so shift alerts, medication reminders and panic events do not reach handsets.
GPS shift verification and background geolocation telemetry cannot be captured on device, which weakens travel-claim attribution and incident-location reconstruction.
The /api/v1/mobile/* endpoint family returns 503 with EXTENSION_NOT_INSTALLED.

A.7 Re-attempting an Outstanding Install

Open Administration & Settings > Extensions, or the platform status page at status.nexorbit.com.au.
Select the outstanding extension. The installer shows what is outstanding, how long it takes, and every module the install would bring in.
Start the run. Modules are installed one at a time with a rolling log, so the module that fails is named on screen.
If the run stops on a missing package, the extension registry did not return a manifest after three retries. This is a registry-side problem, not a configuration error on the platform, and re-running immediately will stop at the same module.
Record the failing module name and raise it with the platform team at support@nexorbit.com.au.

Both outstanding extensions are marked required

While either remains uninstalled, the platform reports overall health as partial service rather than fully operational, even when every core system is green. This is expected and is not itself an incident.

A.8 Shared Error Code

Every endpoint belonging to an uninstalled extension answers with the same shape, so a client can handle all of them in one branch:

{
  "success": false,
  "error": {
    "code": "EXTENSION_NOT_INSTALLED",
    "message": "This endpoint requires the iOS / Android Configuration extension, which is not installed.",
    "statusCode": 503,
    "extension": "mobile"
  }
}

← Chapter 19: API Reference & Integration Chapter 20: Security & Data Protection →