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

# Calls API

> Create, inspect, and end FaceTime calls.

Use the base URL `https://facetime.trychert.com/api` with [project authentication](/facetime/authentication).

## Endpoints

| Method | Path                        | Purpose                        |
| ------ | --------------------------- | ------------------------------ |
| `POST` | `/v1/calls`                 | Request an outbound call       |
| `GET`  | `/v1/calls`                 | List project calls             |
| `GET`  | `/v1/calls/{callId}`        | Read a call                    |
| `GET`  | `/v1/calls/{callId}/events` | Read recorded lifecycle events |
| `POST` | `/v1/calls/{callId}/end`    | Request that a call end        |

See [BYOR outbound calls](/facetime/outbound) for the complete request body, bridge credentials, and idempotency requirements.

<a id="record" />

## Call records

A successful creation returns HTTP `201` and an envelope containing `data` and `request_id`. Read the new call ID from `data.id`. Creation does not prove that the destination answered or that media is ready.

```bash theme={null}
curl "https://facetime.trychert.com/api/v1/calls/$CALL_ID" \
  -H "Authorization: Bearer $CHERT_API_KEY" \
  -H "X-Chert-Project-Id: $PROJECT_ID"
```

<a id="events" />

## Lifecycle and cleanup

For outbound audio, wait for `bridge_ready` (or the corresponding outbound `call.started` webhook) before starting the greeting. Deduplicate by call ID and ignore activation after termination.

Monitor status, lifecycle events, and terminal reason. If your integration receives a call-ended or failure event, release your agent resources. Chert cleans up its bridge and stored room credentials; your service owns its room and agent cleanup.

Choose a unique end key (`END_KEY`, 8–200 characters). HTTP `202` acknowledges the request; continue observing until the call is terminal and cleanup completes.

```bash theme={null}
curl -X POST "https://facetime.trychert.com/api/v1/calls/$CALL_ID/end" \
  -H "Authorization: Bearer $CHERT_API_KEY" \
  -H "X-Chert-Project-Id: $PROJECT_ID" \
  -H "Idempotency-Key: $END_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{}'
```