Docs menu
API reference
Base URL https://api.hospify.cloud/v1/org. JSON in and out, times in UTC (ISO 8601). Send Authorization: Bearer <key or token>.
With your secret key (your server)
| Endpoint | Does |
|---|---|
GET/account | Your organisation, whether this key is live, KYB status and whether live is open. |
GET/agents | List agents. ?active=, ?limit= (max 500), ?after= (the next value from the last page). |
PUT/agents/{external_id} | Create (201) or update (200). Body: display_name, team, site, active. |
POST/agents/batch | Up to 500: { agents: [{ external_id, display_name, team, site, active }] }. |
GET/agents/{external_id} | One agent. |
DELETE/agents/{external_id} | Remove the agent and erase their incidents and locations. |
POST/agents/{external_id}/sessions | A one hour session token for the agent's app. |
GET/incidents | ?status=open|closed|all, ?limit= (max 200), ?after=inc_... |
GET/incidents/{id} | One incident with its timeline; ?trail=true adds every location point. |
POST/incidents/{id}/acknowledge | { note, by }: you're responding. |
POST/incidents/{id}/notes | { note, by } |
POST/incidents/{id}/resolve | { outcome: resolved | false_alarm, note, by } |
GET/events | The event feed: ?after=evt_..., ?type=, ?limit= (max 500). |
With a session token (the agent's app)
The SDKs make these calls for you. Also send Hospify-Publishable-Key: hpk_...; Hospify checks it matches the session.
| Endpoint | Does |
|---|---|
GET/me | The agent, and their open SOS if there is one. |
POST/sos | Raise (or update the open) SOS: { note, latitude, longitude, accuracy_m, battery }. |
GET/sos/{id} | Status, escalation step and who is responding. |
POST/sos/{id}/location | { latitude, longitude, accuracy_m, battery }. 204. |
POST/sos/{id}/safe | { note }: the agent is safe. |
POST/sos/{id}/cancel | { note }: raised by mistake, closed as a false alarm. |
Objects
Agent
external_id, display_name, team, site, active, livemode, last_active_at, created_at.
Incident
id (inc_...), status (open, acknowledged, resolved, false_alarm), escalation_step (0 supervisors, 1 every admin), livemode, agent { external_id, display_name }, team, site, note, location { lat, lng, accuracy_m, postcode, at }, battery, acknowledged_at, responder, closed_at, outcome, resolution_note, created_at; with timeline and trail on GET /incidents/{id}.
Event
id (evt_...), type, livemode, created_at, data (the incident). See Webhooks and events.
Paging
Lists return { data, has_more, next }. Pass next as after for the next page.