## Request or return a handoff

**post** `/v1/chats/{chat}/handoff`

Requests a human takeover, or returns control to your system.

**Behavior**

- `to: "human"` moves the chat to `human_pending`; closed to your sends
  until a human accepts or control returns.
- `to: "partner"` returns control to your system.
- The event log records who asked: a request carries actor `partner`, a
  return carries actor `human`, and an operator name appears only beside
  a `human` actor.

### Path Parameters

- `chat: string`

### Body Parameters

- `to: "human" or "partner"`

  `human` requests a human (owner → `human_pending`); `partner` returns control. Anything else returns HTTP 422 `code` 1071.

  - `"human"`

  - `"partner"`

- `reason: optional string`

  Free-text reason, recorded on the ownership event (absent → empty).

### Returns

- `ok: true`

  - `true`

### Example

```http
curl https://messages.api.linqapp.com/v1/chats/$CHAT/handoff \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_AMB_API_KEY" \
    -d '{
          "to": "human"
        }'
```

#### Response

```json
{
  "ok": true
}
```