Skip to main content

​
Endpoint

POST /api/v1/admin/cancel/{call_id}
Cancel an active call by its ID. This endpoint stops the call session and attempts to hang up the OpenAI Realtime API connection.

​
Authentication

Requires admin authentication using the admin_auth security dependency.
​
X-Admin-Token
string
required
Admin authentication token configured via ADMIN_TOKEN environment variable

​
Path Parameters

​
call_id
string
required
The unique identifier for the call to cancel (OpenAI call ID from webhook)

​
Response

​
ok
boolean
Whether the cancellation request was processed successfully
​
message
string
Confirmation message with the canceled call ID
​
error
string
Error message if the cancellation failed (only present if ok is false)

​
How It Works

The cancel endpoint performs two operations:
  1. Stop Call Session (src/apps/calls/app/call_manager.py:110):
    • Calls CallManager.stop_call(call_id, reason="admin_cancel")
    • Marks the session for termination
    • Cancels all running tasks in the session
  2. Hangup API Connection (src/apps/calls/api/v1/endpoints/admin.py:32):
    • Makes a best-effort call to OpenAI’s hangup API
    • Uses idempotency key: admin_hangup_{call_id}_{uuid}
    • Logs errors but doesn’t fail the request if hangup fails

​
Example Request

curl -X POST https://your-domain.com/api/v1/admin/cancel/call_abc123 \
  -H "X-Admin-Token: your-admin-token"

​
Example Responses

​
Success

{
  "ok": true,
  "message": "Call call_abc123 canceled"
}

​
Error

{
  "ok": false,
  "error": "Call not found or already ended"
}

​
Use Cases

  • Emergency Shutdown: Immediately terminate problematic calls
  • Testing: Clean up test calls during development
  • Operational Control: Manual intervention when automated systems fail
  • Cost Management: Stop runaway calls that are consuming resources

​
Notes

This is a destructive operation. The call will be terminated immediately without graceful cleanup or notification to the caller.
Even if the OpenAI API hangup fails, the local session will be stopped, so the call will not continue processing events.

Build docs developers (and LLMs) love

Get started for freeTalk to us