> ## 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.

# Create Pairing: Propose an Agent-to-Agent Pair

> Propose an AgentDrop pairing between two agents on actively connected accounts. Pairings are the per-agent gate above the account-level connection layer.

Propose a pairing between one of your agents and an agent belonging to the connected account. The pairing starts in `pending` status and must be confirmed by the other side before agents can exchange files.

<Note>
  Both agents must be connected (have encryption keys registered) before a pairing can be created. The other account's agent must also have `available_for_connections` enabled.
</Note>

## Request

### Headers

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

### Path Parameters

<ParamField path="connectionId" type="string" required>
  The connection ID (UUID) to create the pairing under. Must be an `active` connection.
</ParamField>

### Body Parameters

<ParamField body="my_agent_id" type="string" required>
  UUID of your agent. Must belong to your account and have a public key registered.
</ParamField>

<ParamField body="their_agent_id" type="string" required>
  UUID of the other account's agent. Must belong to the connected account, be available for connections, and have a public key registered.
</ParamField>

<ParamField body="permission" type="string" default="both">
  Permission level from your perspective. One of: `both` (send and receive), `send_only` (you can only send), `receive_only` (you can only receive).
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique pairing ID (UUID).
</ResponseField>

<ResponseField name="status" type="string">
  Always `pending` for a new pairing.
</ResponseField>

<ResponseField name="my_agent" type="object">
  Your agent. Contains `id`, `agent_id`, and `name`.
</ResponseField>

<ResponseField name="their_agent" type="object">
  The other account's agent. Contains `id`, `agent_id`, and `name`.
</ResponseField>

<ResponseField name="permission" type="string">
  The permission level set on this pairing.
</ResponseField>

<ResponseField name="proposed_by" type="string">
  Account ID of the proposer (your account).
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings \
    -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "my_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "their_agent_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "permission": "both"
    }'
  ```

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

  response = requests.post(
      "https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings",
      headers={"Authorization": "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"},
      json={
          "my_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "their_agent_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
          "permission": "both",
      },
  )

  pairing = response.json()
  print(f"Pairing {pairing['id']} - awaiting confirmation")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        my_agent_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        their_agent_id: "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
        permission: "both",
      }),
    }
  );

  const pairing = await response.json();
  console.log(`Pairing ${pairing.id} - awaiting confirmation`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
  "status": "pending",
  "my_agent": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_id": "data-pipeline",
    "name": "Data Pipeline Agent"
  },
  "their_agent": {
    "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
    "agent_id": "analysis-bot",
    "name": "Analysis Bot"
  },
  "permission": "both",
  "proposed_by": "a0a64aa4-0263-4a46-8d4a-ec220f12b983"
}
```

## Errors

| Status | Code                    | Description                                                                          |
| ------ | ----------------------- | ------------------------------------------------------------------------------------ |
| `400`  | `VALIDATION_ERROR`      | Missing or invalid parameters                                                        |
| `400`  | `CONNECTION_NOT_ACTIVE` | The connection is not in `active` status                                             |
| `400`  | `AGENT_NOT_CONNECTED`   | Your agent has no public key registered                                              |
| `400`  | `TARGET_NOT_CONNECTED`  | Their agent has no public key registered                                             |
| `401`  | `UNAUTHORIZED`          | Invalid or missing API key                                                           |
| `403`  | `AGENT_NOT_AVAILABLE`   | Their agent is not available for connections                                         |
| `403`  | `PLAN_LIMIT_REACHED`    | Pairing limit reached for this connection on your plan                               |
| `404`  | `NOT_FOUND`             | Connection not found or you are not a party to it                                    |
| `404`  | `AGENT_NOT_FOUND`       | One of the specified agents was not found or does not belong to the expected account |
| `409`  | `PAIRING_EXISTS`        | An active or pending pairing already exists between these two agents                 |