Read safety events, context and evidence, submit authorized safety events and request operational safety assessments.
GET /api/v1/safety/retrieve_safety_event retrieve_safety_event safety:read Tier e ₦1,000.00
Returns a single owned safety event with its level, status, source, summary and lifecycle timestamps.
Parameters Name In Type Required Description event_id query string (uuid) Yes Identifier of the safety event to retrieve.
Idempotency Safe read; no side effects.
Response One safety event on the journey.
{
"data": {
"event_id": "e1f2a3b4-2222-4bbb-9ccc-3d4e5f6a7b8c",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"level": "level_2_assistance",
"status": "under_investigation",
"source": "operations",
"summary": "Unscheduled stop reported near Mile 12.",
"created_at": "2026-09-28T09:40:00.000Z",
"resolved_at": null
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The event_id parameter is not a valid resource identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the safety:read scope or the organization is not linked to an ORN platform account. RESOURCE_NOT_FOUND 404 The requested safety event was not found or is not owned by the linked ride-owner account.
Next steps GET /api/v1/safety/retrieve_safety_status retrieve_safety_status safety:read Tier e ₦1,000.00
Reports whether an owned journey currently has active safety events and lists the open events with their levels and statuses.
Parameters Name In Type Required Description journey_id query string (uuid) Yes Identifier of the owned journey whose active safety events are summarized.
Idempotency Safe read; no side effects.
Response Whether an emergency is active and the events behind it.
{
"data": {
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"has_active_emergency": true,
"active_events": [
{
"event_id": "e1f2a3b4-2222-4bbb-9ccc-3d4e5f6a7b8c",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"level": "level_2_assistance",
"status": "under_investigation",
"source": "operations",
"summary": "Unscheduled stop reported near Mile 12.",
"created_at": "2026-09-28T09:40:00.000Z",
"resolved_at": null
}
]
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The journey_id parameter is not a valid resource identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the safety:read scope or the organization is not linked to an ORN platform account. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier.
Next steps GET /api/v1/safety/retrieve_safety_history retrieve_safety_history safety:read Tier e ₦1,100.00
Returns the most recent safety events for an owned journey in reverse chronological order, capped at one hundred records.
Parameters Name In Type Required Description journey_id query string (uuid) Yes Identifier of the owned journey whose safety event history is returned.
Idempotency Safe read; no side effects.
Response Safety events for the journey, newest first.
{
"data": {
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"events": [
{
"event_id": "e1f2a3b4-2222-4bbb-9ccc-3d4e5f6a7b8c",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"level": "level_2_assistance",
"status": "under_investigation",
"source": "operations",
"summary": "Unscheduled stop reported near Mile 12.",
"created_at": "2026-09-28T09:40:00.000Z",
"resolved_at": null
}
]
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The journey_id parameter is not a valid resource identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the safety:read scope or the organization is not linked to an ORN platform account. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier.
Next steps GET /api/v1/safety/retrieve_safety_context retrieve_safety_context safety:read Tier e ₦1,250.00
Combines the active safety events of an owned journey with its latest ORION risk assessment.
Parameters Name In Type Required Description journey_id query string (uuid) Yes Identifier of the owned journey whose safety context is composed.
Idempotency Safe read; no side effects.
Response Active events plus the latest ORION assessment.
{
"data": {
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"active_events": [
{
"event_id": "e1f2a3b4-2222-4bbb-9ccc-3d4e5f6a7b8c",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"level": "level_2_assistance",
"status": "under_investigation",
"source": "operations",
"summary": "Unscheduled stop reported near Mile 12.",
"created_at": "2026-09-28T09:40:00.000Z",
"resolved_at": null
}
],
"orion_context": {
"assessment_id": "a9b8c7d6-3333-4ccc-8ddd-4e5f6a7b8c9d",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"risk_level": "low",
"summary": "Journey is progressing on schedule. All recorded checkpoints are completed and no safety events are active.",
"created_at": "2026-09-28T09:45:00.000Z"
}
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The journey_id parameter is not a valid resource identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the safety:read scope or the organization is not linked to an ORN platform account. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier.
Next steps GET /api/v1/safety/retrieve_safety_evidence_summary retrieve_safety_evidence_summary safety:read Tier e ₦1,250.00
Lists the evidence items captured for an owned safety event in reverse chronological order with a total count, capped at fifty records.
Parameters Name In Type Required Description event_id query string (uuid) Yes Identifier of the safety event whose evidence summary is returned.
Idempotency Safe read; no side effects.
Response Evidence items attached to a safety event.
{
"data": {
"event_id": "e1f2a3b4-2222-4bbb-9ccc-3d4e5f6a7b8c",
"evidence_count": 2,
"evidence": [
{
"id": "a1b2c3d4-8888-4bbb-8ccc-9d0e1f2a3b4c",
"evidence_type": "photo",
"captured_by": "Adaeze Okafor",
"captured_at": "2026-09-28T09:41:00.000Z"
},
{
"id": "b2c3d4e5-9999-4ccc-9ddd-0e1f2a3b4c5d",
"evidence_type": "note",
"captured_by": "Operations desk",
"captured_at": "2026-09-28T09:43:30.000Z"
}
]
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The event_id parameter is not a valid resource identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the safety:read scope or the organization is not linked to an ORN platform account. RESOURCE_NOT_FOUND 404 The requested safety event was not found or is not owned by the linked ride-owner account.
Next steps POST /api/v1/safety/submit_authorized_safety_event submit_authorized_safety_event safety:write Tier e ₦1,250.00
Records an authorized partner safety event on an owned journey through the authoritative emergency event recorder with optional GPS evidence.
Parameters Name In Type Required Description journey_id body string (uuid) Yes Identifier of the owned journey the safety event belongs to. level body string Yes Severity of the event and must be one of level_1_concern, level_2_assistance or level_3_critical. summary body string No Optional short description of the incident stored with the event. gps_lat body number No Optional latitude of the reporter position captured as initial GPS evidence. gps_lng body number No Optional longitude of the reporter position captured as initial GPS evidence. gps_accuracy_m body number No Optional GPS accuracy in meters stored with the initial GPS evidence.
Deterministic rules Duplicate-suppression window: if an active event of the same level was recorded within the last 60 seconds, the platform reuses that event instead of inserting a duplicate — an immediate retry with the same payload returns the existing event. Idempotency Within the 60-second duplicate-suppression window, retries with the same level return the existing event; outside the window, each call creates a new event.
Response The newly recorded event. source is always "operations"; status starts at "created".
{
"data": {
"event_id": "e1f2a3b4-2222-4bbb-9ccc-3d4e5f6a7b8c",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"level": "level_2_assistance",
"source": "operations",
"status": "created"
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The body is not a JSON object, journey_id is not a valid resource identifier, an optional field has the wrong type, level is not one of the three supported levels, or the authoritative recorder rejected the event. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the safety:write scope or the organization is not linked to an ORN platform account. FORBIDDEN 403 Write operations are refused for API keys issued in the sandbox environment. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier.
Events safety.event_recorded
Next steps POST /api/v1/safety/request_operational_safety_assessment request_operational_safety_assessment safety:write Tier e ₦1,500.00
Composes an operational safety posture for an owned journey from its active events, checkpoint progress and latest ORION risk assessment.
Parameters Name In Type Required Description journey_id body string (uuid) Yes Identifier of the owned journey to assess. focus body string No Optional focus label echoed back in the assessment that defaults to general when omitted.
Idempotency Not idempotent — retrying may repeat the effect.
Response A focused operational assessment across checkpoints, emergencies and ORION.
{
"data": {
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"requested_focus": "checkpoint_progress",
"assessment": {
"active_emergencies": 1,
"checkpoint_progress": {
"planned_total": 4,
"completed": 2
},
"latest_orion_assessment": {
"assessment_id": "a9b8c7d6-3333-4ccc-8ddd-4e5f6a7b8c9d",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"risk_level": "low",
"summary": "Journey is progressing on schedule. All recorded checkpoints are completed and no safety events are active.",
"created_at": "2026-09-28T09:45:00.000Z"
}
}
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The body is not a JSON object, journey_id is not a valid resource identifier, or focus is not a string. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the safety:write scope or the organization is not linked to an ORN platform account. FORBIDDEN 403 Write operations are refused for API keys issued in the sandbox environment. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier.
Next steps GET /api/v1/safety/advanced_safety_intelligence advanced_safety_intelligence intelligence:read Tier h ₦7,500.00
Returns a fused read-only deep safety analysis for one owned journey combining emergency events, evidence, ORION risk assessments, checkpoint escalations and passenger exposure counts.
Parameters Name In Type Required Description journey_id query string (uuid) Yes Identifier of the owned journey to analyze.
Idempotency Safe read; no side effects.
Response Aggregated safety intelligence across all domains for the journey.
{
"data": {
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"totals": {
"events": 1,
"evidence": 2,
"orion_assessments": 3,
"passenger_exposure": 12
},
"events_by_level": {
"level_1_concern": 0,
"level_2_assistance": 1,
"level_3_critical": 0
},
"events_by_status": {
"created": 0,
"awaiting_review": 0,
"under_investigation": 1,
"monitoring": 0
},
"checkpoints_by_status": {
"triggered": 0,
"completed": 2,
"missed": 0,
"escalated": 0
},
"evidence_by_event": [
{
"event_id": "e1f2a3b4-2222-4bbb-9ccc-3d4e5f6a7b8c",
"evidence_count": 2
}
],
"active_events": [
{
"event_id": "e1f2a3b4-2222-4bbb-9ccc-3d4e5f6a7b8c",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"level": "level_2_assistance",
"status": "under_investigation",
"source": "operations",
"summary": "Unscheduled stop reported near Mile 12.",
"created_at": "2026-09-28T09:40:00.000Z",
"resolved_at": null
}
],
"latest_orion_assessment": {
"assessment_id": "a9b8c7d6-3333-4ccc-8ddd-4e5f6a7b8c9d",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"risk_level": "low",
"summary": "Journey is progressing on schedule. All recorded checkpoints are completed and no safety events are active.",
"created_at": "2026-09-28T09:45:00.000Z"
}
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The journey_id parameter is not a valid resource identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the intelligence:read scope or the organization is not linked to an ORN platform account. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier.
Next steps