# API: Emergency dispatch

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/dispatch` | Emergency dispatch: settings (categories, triage script, ladder, owners), on-call shifts and recent emergencies | `settings:read` |
| PUT | `/v1/dispatch` | Change emergency dispatch (owner): categories and their keywords, the triage questions, routine words, the escalation ladder (people or whoever is on call, channels, wait, repeats), the maximum paging time and the owners told when nobody accepts | `settings:write` |
| POST | `/v1/dispatch/incidents` | Report an emergency by hand and page the ladder (owner) | `settings:write` |
| GET | `/v1/dispatch/incidents/:id` | One emergency and its timeline: every page per channel and its delivery, the acceptance, the owner notice, what the caller was told | `settings:read` |
| POST | `/v1/dispatch/incidents/:id/ack` | Accept an emergency (any member): paging stops and the caller is texted your first name | `calls:write` |
| POST | `/v1/dispatch/incidents/:id/cancel` | Stop paging an emergency (owner), with the reason | `settings:write` |
| POST | `/v1/dispatch/incidents/:id/page` | Page an emergency that was held for review (over the hourly paging cap) (owner) | `settings:write` |
| POST | `/v1/dispatch/shifts` | Add an on-call shift or override (owner); overrides win while they run | `settings:write` |
| DELETE | `/v1/dispatch/shifts/:id` | Remove an on-call shift (owner) | `settings:write` |
| POST | `/v1/dispatch/triage-preview` | Try the triage rules on a description | `settings:read` |

## Examples

### GET /v1/dispatch

Emergency dispatch: settings (categories, triage script, ladder, owners), on-call shifts and recent emergencies

```bash
curl -s "https://api.closefinch.com/v1/dispatch" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### PUT /v1/dispatch

Change emergency dispatch (owner): categories and their keywords, the triage questions, routine words, the escalation ladder (people or whoever is on call, channels, wait, repeats), the maximum paging time and the owners told when nobody accepts

```bash
curl -s -X PUT "https://api.closefinch.com/v1/dispatch" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch`, {
  method: "PUT",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/dispatch/incidents

Report an emergency by hand and page the ladder (owner)

```bash
curl -s -X POST "https://api.closefinch.com/v1/dispatch/incidents" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch/incidents`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/dispatch/incidents/$ID

One emergency and its timeline: every page per channel and its delivery, the acceptance, the owner notice, what the caller was told

```bash
curl -s "https://api.closefinch.com/v1/dispatch/incidents/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch/incidents/${id}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/dispatch/incidents/$ID/ack

Accept an emergency (any member): paging stops and the caller is texted your first name

```bash
curl -s -X POST "https://api.closefinch.com/v1/dispatch/incidents/$ID/ack" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch/incidents/${id}/ack`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/dispatch/incidents/$ID/cancel

Stop paging an emergency (owner), with the reason

```bash
curl -s -X POST "https://api.closefinch.com/v1/dispatch/incidents/$ID/cancel" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch/incidents/${id}/cancel`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/dispatch/incidents/$ID/page

Page an emergency that was held for review (over the hourly paging cap) (owner)

```bash
curl -s -X POST "https://api.closefinch.com/v1/dispatch/incidents/$ID/page" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch/incidents/${id}/page`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/dispatch/shifts

Add an on-call shift or override (owner); overrides win while they run

```bash
curl -s -X POST "https://api.closefinch.com/v1/dispatch/shifts" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch/shifts`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### DELETE /v1/dispatch/shifts/$ID

Remove an on-call shift (owner)

```bash
curl -s -X DELETE "https://api.closefinch.com/v1/dispatch/shifts/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch/shifts/${id}`, {
  method: "DELETE",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/dispatch/triage-preview

Try the triage rules on a description

```bash
curl -s -X POST "https://api.closefinch.com/v1/dispatch/triage-preview" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/dispatch/triage-preview`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).