Everdrone AED Broker

Overview

This service answers one question: has an AED been delivered near this alarm? It does that while knowing as little as possible about the alarm.

How it works, in plain terms

1. Someone has a cardiac arrest. SOS Alarm sends out both a Heartrunner and an Everdrone drone.
2. Heartrunners tells the broker there is an alarm in a rough area — never the address.
3. Everdrone tells the broker it has dropped an AED in an area.
4. The broker matches the two by area, so the Heartrunner can see there is an AED nearby to grab.

The broker is just the meeting point between the two sides. It keeps only what it needs to make that match, and forgets it within hours.

What it holds — and doesn't

• No exact position, address, SOS case number, or Everdrone ids. Location is only a coarse H3 grid cell.
• Everdrone only sends, never receives. Both sides poll the broker; there are no callbacks, and Heartrunners can never reach Everdrone's systems.
• Short-lived. A case expires after three hours, and expired data is deleted within a day.
• Request bodies are never logged — only method, path, status, timing and a request id.

Base URL

The pattern is https://hr-<env>.everdrone.com/. Production is live now:

The same host serves both Heartrunners and Everdrone. Every response includes an X-Request-ID header; send your own and it is echoed back, which makes any support question quicker to trace.

Compatibility contract

Responses only ever gain keys:

• New keys can show up in any response at any time.
• Existing keys are never removed or renamed without a coordinated release.
• Ignore keys you don't recognise.
• The broker also ignores unknown keys in a request, so you can start sending a new field before it understands it.

Likely next: richer delivery data from Everdrone, such as where and when a drop is planned.

Grid ids (H3)

A grid_id is an H3 cell index at resolution 9, written as 15 lowercase hex characters.

A resolution-9 cell covers many buildings, so the broker can't point at an address. It's still small enough that two unrelated alarms rarely land in the same cell within one case's lifetime.

Case lifecycle

A case is in exactly one of three states:

Either side may act first

Everdrone is often alerted before Heartrunners, so a delivery can arrive before the case exists. Deliveries are matched on the grid cell, not the case id, which makes the order irrelevant:

• Case first. Heartrunners files the case, Everdrone confirms later, and the case turns delivered right away.
• Delivery first. Everdrone confirms with no case yet; the broker holds it. When Heartrunners files a case for that cell, it comes back delivered on the first response.

So neither side needs retry logic, and no confirmation is lost. A held delivery lasts three hours.

Authentication

OAuth2-style client credentials over HTTPS. Exchange your client_id and client_secret for a short-lived JWT, then send it as Authorization: Bearer <token>.

Access tokens are HS256 JWTs valid for 15 minutes, with claims iss, aud, sub (your client id), scope, iat and exp. Clients need not inspect them — treat the token as opaque.

Renewing

Two equally supported options:

• Call POST /auth/token again with your client credentials.
• Call POST /auth/refresh with the refresh token you were issued.

Auth endpoints

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "case:create case:read",
  "refresh_token": "kNq7v1v0...",
  "refresh_expires_in": 604800
}

Heartrunners endpoints

{
  "hr_case_id": "6f1d5f2c-6c2c-4f4a-9a1f-2b0f1a9c7e31",
  "grid_id": "891fb466257ffff"
}

{
  "hr_case_id": "6f1d5f2c-6c2c-4f4a-9a1f-2b0f1a9c7e31",
  "grid_id": "891fb466257ffff",
  "status": "pending",
  "created_at": "2026-08-26T09:14:02.118431+00:00",
  "delivered_at": null,
  "expires_at": "2026-08-26T12:14:02.118431+00:00"
}

Everdrone endpoints

[
  {
    "hr_case_id": "6f1d5f2c-6c2c-4f4a-9a1f-2b0f1a9c7e31",
    "grid_id": "891fb466257ffff",
    "created_at": "2026-08-26T09:14:02.118431+00:00",
    "expires_at": "2026-08-26T12:14:02.118431+00:00"
  }
]

Health & readiness

{ "status": "ok", "environment": "production", "h3_resolution": 9 }

The machine-readable schema for everything above is at /openapi.json, suitable for generating a client.

Errors

Every error is JSON with a single detail string. Do not parse it — branch on the status code.

{ "detail": "Insufficient scope" }

Rate limits

A sliding 60-second window per client_id, default 600 requests/minute (10/s). Exceeding it returns 429 with a Retry-After header in seconds.

The limit is deliberately generous because both sides poll. If your polling cadence needs more headroom, ask — it is a configuration value, not an architectural one.