> ## Documentation Index
> Fetch the complete documentation index at: https://docs.burki.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminate Call

> Terminate an ongoing call.

This will hang up the call via the telephony provider (Twilio, Telnyx, or SIP).
Only works for calls that are currently in 'ongoing' status.

Immediately terminate an ongoing call. This endpoint allows you to programmatically hang up a call that is currently in progress.

This endpoint requires an authenticated, verified user account.

## Use Cases

* **Admin intervention**: Manually end calls that need immediate termination
* **Automatic cutoff**: End calls when certain conditions are met (e.g., time limits, budget caps)
* **Emergency stop**: Quickly terminate all active calls during system maintenance
* **Quality control**: End calls that are not meeting quality standards

## Path Parameters

| Parameter  | Type   | Required | Description                                                   |
| ---------- | ------ | -------- | ------------------------------------------------------------- |
| `call_sid` | string | Yes      | The unique call SID (Session ID) from your telephony provider |

## Request

This endpoint does not require a request body.

```bash theme={null}
curl -X POST "https://api.burki.dev/api/v1/calls/CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/terminate" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response

### Success (200 OK)

```json theme={null}
{
  "success": true,
  "message": "Call terminated successfully via twilio"
}
```

| Field     | Type    | Description                                |
| --------- | ------- | ------------------------------------------ |
| `success` | boolean | Whether the termination was successful     |
| `message` | string  | Status message including the provider used |

## Error Responses

### 400 Bad Request

Returned when the call is not in an "ongoing" status.

```json theme={null}
{
  "detail": "Cannot terminate call - current status is 'completed'"
}
```

### 404 Not Found

Returned when the call doesn't exist or doesn't belong to your organization.

```json theme={null}
{
  "detail": "Call not found or you don't have permission to terminate it"
}
```

### 500 Internal Server Error

Returned when the telephony provider fails to terminate the call.

```json theme={null}
{
  "detail": "Failed to terminate call via twilio"
}
```

## Provider Support

This endpoint works with all supported telephony providers:

| Provider   | Notes                                           |
| ---------- | ----------------------------------------------- |
| Twilio     | Uses Twilio's call update API                   |
| Telnyx     | Uses Telnyx Call Control API                    |
| Vonage     | Uses Vonage Voice API                           |
| SIP bridge | Uses the configured SIP bridge termination path |

The system automatically detects which provider to use based on the call's metadata.

## Examples

### Python

```python theme={null}
import requests

def terminate_call(call_sid):
    response = requests.post(
        f"https://api.burki.dev/api/v1/calls/{call_sid}/terminate",
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    )
    
    if response.status_code == 200:
        print(f"Call {call_sid} terminated successfully")
        return response.json()
    else:
        print(f"Failed to terminate: {response.json()['detail']}")
        return None
```

### Node.js

```javascript theme={null}
const axios = require('axios');

async function terminateCall(callSid) {
  try {
    const response = await axios.post(
      `https://api.burki.dev/api/v1/calls/${callSid}/terminate`,
      {},
      {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );
    
    console.log('Call terminated:', response.data);
    return response.data;
  } catch (error) {
    console.error('Failed to terminate:', error.response.data.detail);
    throw error;
  }
}
```

### Terminate All Active Calls

```python theme={null}
import requests

def terminate_all_active_calls():
    # First, get all ongoing calls
    calls_response = requests.get(
        "https://api.burki.dev/api/v1/calls",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        params={"status": "ongoing"}
    )
    
    ongoing_calls = calls_response.json()["items"]
    
    # Terminate each one
    for call in ongoing_calls:
        terminate_call(call["call_sid"])
        print(f"Terminated call {call['call_sid']}")
```

## Notes

* The call status will be updated to "completed" in the database after termination
* Call duration is calculated up to the termination time
* Billing is recorded for the portion of the call that occurred
* Termination is immediate - there is no graceful hangup message by default


## OpenAPI

````yaml POST /api/v1/calls/{call_sid}/terminate
openapi: 3.1.0
info:
  title: Burki
  description: A system that uses AI to answer customer Calls.
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/calls/{call_sid}/terminate:
    post:
      tags:
        - calls
      summary: Terminate Call
      description: >-
        Terminate an ongoing call.


        This will hang up the call via the telephony provider (Twilio, Telnyx,
        or SIP).

        Only works for calls that are currently in 'ongoing' status.
      operationId: terminate_call_api_v1_calls__call_sid__terminate_post
      parameters:
        - name: call_sid
          in: path
          required: true
          schema:
            type: string
            title: Call Sid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````