Skip to main content

​
Get Queue

​
/api/v1/queue
GET
Retrieve all dispatch queue items sorted by priority

​
Endpoint

GET /api/v1/queue

​
Description

Returns all items in the dispatch queue, sorted by risk level, status, and creation time. Items remain in the queue through their lifecycle (OPEN → IN_PROGRESS → DISPATCHED → RESOLVED).

​
Request

No parameters required.

​
cURL Example

curl http://localhost:8000/api/v1/queue

​
Response

Returns an array of queue items.
​
id
string
required
Call ID (same as call_session_id)
​
risk_level
string
required
Risk classification: CRITICAL, ELEVATED, NORMAL, or LOW
​
risk_score
number
required
Numeric risk score (0.0 to 1.0)
​
category
string
required
Service category: EMS, FIRE, POLICE, or OTHER
​
tags
array
required
Array of semantic tags extracted from call (e.g., ["FIRE", "SMOKE"])
​
emotion
string
Caller’s emotional state (e.g., "DISTRESSED", "CALM")
​
summary
string
AI-generated summary of the call
​
status
string
required
Current queue status: OPEN, IN_PROGRESS, DISPATCHED, RESOLVED, or CANCELLED
​
created_at
string
required
ISO 8601 timestamp when call ended and queue item was created
​
from_masked
string
Masked caller phone number (only last 4 digits, e.g., "•••1234")
​
to
string
Emergency number called

​
Success Response (200 OK)

[
  {
    "id": "abc123-def456-ghi789",
    "risk_level": "CRITICAL",
    "risk_score": 0.89,
    "category": "FIRE",
    "tags": ["FIRE", "SMOKE"],
    "emotion": "DISTRESSED",
    "summary": "Caller reports active fire in kitchen with heavy smoke",
    "status": "OPEN",
    "created_at": "2026-03-03T23:17:45Z",
    "from_masked": "•••1234",
    "to": "+15555559911"
  },
  {
    "id": "xyz789-uvw456-rst123",
    "risk_level": "ELEVATED",
    "risk_score": 0.65,
    "category": "EMS",
    "tags": ["CHEST_PAIN"],
    "emotion": "WORRIED",
    "summary": "Male caller experiencing chest pain and shortness of breath",
    "status": "IN_PROGRESS",
    "created_at": "2026-03-03T23:15:22Z",
    "from_masked": "•••5678",
    "to": "+15555559911"
  }
]

​
Empty Queue (200 OK)

[]

​
Sorting Logic

Items are sorted by:
  1. Combined Weight (descending)
    • Risk weight: CRITICAL=3, ELEVATED=2, NORMAL=1, LOW=0
    • Status weight: OPEN=100, IN_PROGRESS=80, DISPATCHED=60, RESOLVED=-100, CANCELLED=-120
    • Combined = Risk weight + Status weight
  2. Risk Score (descending) - for items with same weight
  3. Creation Time (ascending) - oldest first for items with same weight and score
This ensures:
  • CRITICAL + OPEN items appear first
  • Active items (OPEN, IN_PROGRESS) stay at top
  • Resolved/cancelled items sink to bottom
  • Within same priority, older calls come first

​
Implementation

Location: app/main.py:732-775

​
Get Live Queue

​
/api/v1/live_queue
GET
Retrieve calls currently in progress with real-time updates

​
Endpoint

GET /api/v1/live_queue

​
Description

Returns calls that are currently active and streaming audio. This endpoint provides real-time updates of transcription, distress scores, and risk levels while calls are in progress.

​
Request

No parameters required.

​
cURL Example

curl http://localhost:8000/api/v1/live_queue

​
Response

​
id
string
required
Call session ID
​
call_control_id
string
required
Telnyx call control ID
​
from_masked
string
required
Masked caller number
​
to
string
required
Called number
​
started_at
string
required
ISO 8601 timestamp when call started
​
status
string
required
Call status: LIVE
​
transcript_live
string
Real-time partial transcript (updated as caller speaks)
​
distress
number
Current distress score (0.0 to 1.0)
​
max_distress
number
Maximum distress score observed during call
​
voiced_seconds
number
Seconds of voice activity detected
​
risk_level
string
required
Current risk assessment (updates in real-time)
​
risk_score
number
required
Current risk score
​
emotion
string
Detected emotion (may be null during active call)
​
category
string
Service category (may be null during active call)
​
tags
array
required
Extracted tags (usually empty during active call)
​
summary
string
required
Summary text (usually “Listening…” during active call)

​
Success Response (200 OK)

[
  {
    "id": "live-call-123",
    "call_control_id": "v3:control-789",
    "from_masked": "•••9876",
    "to": "+15555559911",
    "started_at": "2026-03-03T23:20:15Z",
    "status": "LIVE",
    "transcript_live": "There's someone breaking into my house right now",
    "distress": 0.78,
    "max_distress": 0.83,
    "voiced_seconds": 12.4,
    "risk_level": "CRITICAL",
    "risk_score": 0.78,
    "emotion": null,
    "category": null,
    "tags": [],
    "summary": "Listening…"
  }
]

​
Implementation

Location: app/main.py:777-811

​
Usage Notes

  • This endpoint is designed for polling (every 1-2 seconds)
  • Used by live call monitoring dashboards
  • Items appear when call is answered, removed when call ends
  • Risk levels update in real-time based on audio analysis
  • Final analysis happens on hangup and creates queue item

​
Update Queue Status

​
/api/v1/queue/{call_id}/status
PATCH
Update the status of a queue item

​
Endpoint

PATCH /api/v1/queue/{call_id}/status

​
Path Parameters

​
call_id
string
required
The call ID (queue item ID) to update

​
Request

​
Headers

​
Content-Type
string
required
Must be application/json

​
Request Body

​
status
string
required
New status value: OPEN, IN_PROGRESS, DISPATCHED, RESOLVED, or CANCELLED
​
note
string
Optional note to record with status change

​
Example Request

{
  "status": "IN_PROGRESS",
  "note": "Dispatcher reviewing call details"
}

​
cURL Example

curl -X PATCH http://localhost:8000/api/v1/queue/abc123-def456-ghi789/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "DISPATCHED",
    "note": "Fire unit #3 dispatched to location"
  }'

​
Response

Returns the updated queue item.
​
id
string
required
Call ID
​
status
string
required
Updated status
​
risk_level
string
required
Risk level
​
risk_score
number
required
Risk score
​
category
string
required
Service category
​
tags
array
required
Semantic tags
​
emotion
string
Caller emotion
​
summary
string
Call summary
​
created_at
string
required
Creation timestamp
​
status_history
array
Array of status change records (if notes were provided)

​
Success Response (200 OK)

{
  "id": "abc123-def456-ghi789",
  "status": "DISPATCHED",
  "risk_level": "CRITICAL",
  "risk_score": 0.89,
  "category": "FIRE",
  "tags": ["FIRE", "SMOKE"],
  "emotion": "DISTRESSED",
  "summary": "Caller reports active fire in kitchen with heavy smoke",
  "created_at": "2026-03-03T23:17:45Z",
  "status_history": [
    {
      "new_status": "DISPATCHED",
      "note": "Fire unit #3 dispatched to location",
      "ts": "2026-03-03T23:18:30Z"
    }
  ]
}

​
Error Response (404 Not Found)

{
  "detail": "Queue item not found"
}

​
Implementation

Location: app/main.py:847-878

​
Usage Notes

  • Status transitions are not enforced (can move to any status)
  • Consider implementing workflow rules in production:
    • OPEN → IN_PROGRESS → DISPATCHED → RESOLVED
    • Prevent moving back to earlier states
    • Log all status changes
  • The note field is optional but recommended for audit trails
  • Status history is stored in memory (will be lost on restart in dev mode)

Build docs developers (and LLMs) love

Get started for freeTalk to us