Skip to main content

​
Welcome

The Punch Rescue Public API v1 lets external systems integrate directly with the Rescue platform. Use it to declare emergencies, re-categorize them, mark them resolved, and read an organization’s category catalog and audit log. Every emergency transition fan-outs in real time to the org’s base-station devices and to any registered webhook subscribers — so your integration, our responders, and downstream partners stay in lockstep.

​
Base URL

EnvironmentBase URL
Productionhttps://api.punchrescue.com/api/public/v1
The OpenAPI document is published at https://api.punchrescue.com/api/public/v1/openapi.json. It’s the one path on the API that doesn’t require authentication, so you can paste it into Claude or a codegen tool before issuing your first request.
Need a sandbox before going live? Reach out to your Rescue contact — we’ll provision a dev key and share the corresponding base URL out-of-band.

​
Authentication

All endpoints (except GET /openapi.json) require an API key issued by Rescue. Send it as a Bearer token on every request. 
curl https://api.punchrescue.com/api/public/v1/orgs/{orgId}/emergencies \
  -H "Authorization: Bearer $RESCUE_API_KEY" \
  -H "Content-Type: application/json"
API keys are minted by a Rescue admin and shown exactly once at creation. Each key carries:
  • A subject — partner, enterprise, or org — which determines the set of organizations the key can act on (every org under the subject’s hierarchy).
  • An optional allowedOrgIds whitelist — when set, further restricts the key to a subset of orgs under its subject.
  • Permissions — the v1 vocabulary is read and write. Future versions may introduce granular <resource>:<action> permissions additively.
  • An optional activeUntilDate — hard expiration checked on every request.
OpenAPI security scheme: 
"securitySchemes": {
  "BearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "rk_live_<8hex><64hex>"
  }
}
Treat your API key like a password. Never commit it to source control or ship it in client-side code. If a key is leaked, contact Punch Rescue support to revoke (status=inactive) or rotate it.

​
Core concepts

The tenant scope every emergency, category, and audit-log entry belongs to. Reference an organization by its Punch Rescue orgId (UUID). Your API key must cover that org through its subject (org / enterprise / partner) and any allowedOrgIds whitelist — 403 is returned otherwise.
A classification for emergencies (e.g. Medical, Fire, Security). Each category has a stable categoryId, plus name, color, and severity. Categories are read-only on the public API — they’re authored inside the Punch Rescue admin console.
A real-world incident tracked through three event types:
  • emergency.declared — created via POST /orgs/{orgId}/emergencies.
  • emergency.categorized — re-categorized via PATCH /orgs/{orgId}/emergencies/{emergencyId}.
  • emergency.resolved — closed via POST /orgs/{orgId}/emergencies/{emergencyId}/resolutions.
Every transition fan-outs to base-station devices and to matching webhook subscribers.
Rescue pushes every emergency transition to registered subscribers as a stable PublicWebhookEnvelope. Subscriptions can be scoped at the partner, enterprise, or org level with an optional allowedOrgIds whitelist — so a single subscription can cover many orgs. See Webhooks for the full envelope, event catalog, delivery semantics, and dedup/ordering rules.

​
A typical integration flow

1

Discover an org's categories

GET /orgs/{orgId}/emergencies/categories returns the categoryId values available for that org. (Categories are managed inside Rescue — there’s no public CRUD.)
2

Declare an emergency

POST /orgs/{orgId}/emergencies with a categoryId (and an optional externalId for your own correlation). Returns 201 Created with the full emergency record. Rescue resolves the category color and dispatches a real-time alert to every base-station device in the org.
3

Update or re-categorize

PATCH /orgs/{orgId}/emergencies/{emergencyId} to change the category or other mutable attributes. Returns 200 OK and fires an emergency.categorized webhook.
4

Resolve

POST /orgs/{orgId}/emergencies/{emergencyId}/resolutions. Returns 201 Created with the resolution record and fires an emergency.resolved webhook. Idempotent — resolving an already-resolved emergency returns the existing resolution.
5

Receive webhook deliveries

Have your Rescue admin register a webhook subscription scoped to your partner/enterprise/org. You’ll receive every emergency.declared / emergency.categorized / emergency.resolved event for the orgs your subscription covers. See Webhooks for the envelope shape, the full event catalog, and how to secure and test your endpoint.

​
Endpoint groups

Categories

Read-only listing of an org’s category catalog.

Emergencies

Declare, list, fetch, update, and resolve emergencies.

Webhooks

Receive emergency and device events in real time — envelope, event catalog, and delivery semantics.

​
Responses & errors

Successful responses use standard HTTP codes — 200 OK, 201 Created, 204 No Content. Emergency writes are synchronous: the response reflects committed state. Webhook fan-out happens asynchronously after the response is sent, with retries on transient failures. Validation failures return 422 Unprocessable Entity with a structured payload pointing at the offending field: 
{
  "detail": [
    {
      "loc": ["body", "categoryId"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
Authorization failures:
  • 401 Unauthorized — missing, invalid, expired, or revoked API key.
  • 403 Forbidden — key is valid but its subject doesn’t cover the requested orgId (or the org isn’t in allowedOrgIds).
5xx responses indicate retriable server errors. Idempotency-Key isn’t supported yet — when a write returns 5xx with no body, fetch the emergency via GET /orgs/{orgId}/emergencies/{emergencyId} (or look it up by your own externalId on the list endpoint) before retrying to avoid duplicates.
Need help or hitting unexpected behavior? Reach out to your Rescue contact with the request ID returned by the API — it’s the fastest way for us to trace what happened.