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

# Update Pairing: Modify Pairing State or Permissions

> Update the permission level on an existing AgentDrop agent pairing without recreating it. Useful when widening or narrowing the pairing's allowed actions.

Update the permission level on an existing pairing. Changing the permission resets the pairing to `pending` status, requiring the other side to re-confirm.

<Note>
  Either side of the pairing can update the permission. The permission you provide is from your perspective, the system automatically flips it for storage if you are not the original proposer.
</Note>

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer agd_live_xxxxxxxxxxxxxxxxxxxx`
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The pairing ID (UUID) to update.
</ParamField>

### Body Parameters

<ParamField body="permission" type="string" required>
  New permission level from your perspective. One of: `both`, `send_only`, `receive_only`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The pairing ID.
</ResponseField>

<ResponseField name="permission" type="string">
  The new permission from your perspective.
</ResponseField>

<ResponseField name="status" type="string">
  Always `pending` after an update (requires re-confirmation).
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `Permission updated. The other side must re-confirm the pairing.`
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://api.agent-drop.com/v1/pairings/d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 \
    -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"permission": "send_only"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.agent-drop.com/v1/pairings/d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
      headers={"Authorization": "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"},
      json={"permission": "send_only"},
  )

  result = response.json()
  print(result["status"])  # "pending"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.agent-drop.com/v1/pairings/d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
    {
      method: "PATCH",
      headers: {
        Authorization: "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ permission: "send_only" }),
    }
  );

  const result = await response.json();
  console.log(result.message);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
  "permission": "send_only",
  "status": "pending",
  "message": "Permission updated. The other side must re-confirm the pairing."
}
```

## Errors

| Status | Code               | Description                                    |
| ------ | ------------------ | ---------------------------------------------- |
| `400`  | `VALIDATION_ERROR` | Invalid permission value                       |
| `400`  | `INVALID_STATUS`   | Cannot update a revoked pairing                |
| `401`  | `UNAUTHORIZED`     | Invalid or missing API key                     |
| `404`  | `NOT_FOUND`        | Pairing not found or you are not a party to it |