Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.punchrescue.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Welcome

The Punch Rescue Public API lets external systems integrate directly with the Rescue platform. Use it to onboard organizations, define and maintain their alert categories, and drive emergencies through their full lifecycle — from the moment an alert is declared, through categorization, to final resolution. Every emergency triggered through this API is fanned out to the organization’s base-station devices in real time, so integrations stay in sync with what responders see on the ground.

​
Base URLs

The API is available in three environments. Use Production for live traffic and Dev for integration testing.
EnvironmentBase URL
Productionhttps://api.punchrescue.com
Devhttps://api.rescue-serverless.dev.back2back.team

​
Authentication

All endpoints are authenticated with an API key issued by Rescue. Send it on every request in the X-API-Key header. 
curl https://api.punchrescue.com/api/v1/public/notify/organizations \
  -H "X-API-Key: $RESCUE_API_KEY" \
  -H "Content-Type: application/json"
The corresponding security scheme in the OpenAPI document: 
"securitySchemes": {
  "ApiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
  }
}
Treat your API key like a password. Never commit it to source control or expose it in client-side code. If a key is leaked, contact Rescue support to rotate it immediately.

​
Core concepts

The top-level tenant in Rescue. External systems reference an organization by its notifyOrgId. Organizations can exist in either an approved state or as a pending join request — most endpoints support both.
A classification for emergencies (e.g. Medical, Fire, Security). Each category has a severity of "1" (Low) or "2" (High) and may be marked as the default. Categories are scoped to an organization.
A real-world incident tracked through three event types:
  • DECLARED — the alert is raised and dispatched to base-station devices.
  • CATEGORIZED — the category is assigned or updated.
  • RESOLVED — the incident is closed.

​
A typical integration flow

1

Submit the organization

POST /organizations with the org’s notifyOrgId, name, system user, and an initial set of categories. The request is stored in pending state and returns a tracking ID.
2

Manage categories

Add, replace, or remove categories with the /categories endpoints. Use PUT /categories?mode=upsert|replace|remove for bulk changes, or POST / PATCH / DELETE for single-category operations.
3

Trigger an emergency

POST /organizations/{notifyOrgId}/emergencies with a categoryId to declare a new alert. Rescue resolves the category color and pushes a particle alert to every base-station device in the organization.
4

Update or resolve

Use PUT /emergencies/{emergencyId}/category to re-categorize, or POST /emergencies/{emergencyId}/resolve to close the incident. Both return 202 Accepted.

​
Endpoint groups

Organizations

Onboard organizations and update their details.

Categories

Define the alert categories an organization can use.

Emergencies

Declare, categorize, and resolve emergency alerts.

Lifecycle helpers

Dedicated endpoints for category updates and resolution.

​
Responses & errors

Successful requests return 200 OK, 201 Created, 202 Accepted, or 204 No Content depending on the operation. Lifecycle endpoints (category change, resolve) return 202 Accepted because dispatch to devices happens asynchronously. Validation failures return 422 Unprocessable Entity with a structured payload pointing at the offending field: 
{
  "detail": [
    {
      "loc": ["body", "categories", 0, "severity"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
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.