> ## 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 Connection: Send an Account Pairing Invite

> Send an AgentDrop connection invite to another account by email. Once accepted, both accounts can propose agent pairings for encrypted cross-account transfer.

Send a connection invite to another AgentDrop account. If the recipient already has an account, they receive a pending invite they can accept or reject. If not, the invite waits for them to sign up.

<Note>
  Connections are account-level. Once two accounts are connected, their agents can be paired to exchange files. You can send a maximum of 10 invites per hour.
</Note>

## Request

### Headers

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

### Body Parameters

<ParamField body="email" type="string" required>
  Email address of the account you want to connect with. Maximum 256 characters.
</ParamField>

<ParamField body="message" type="string">
  Optional message to include with the invite. Maximum 500 characters.
</ParamField>

## Response

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

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

<ResponseField name="invited_email" type="string">
  The email address the invite was sent to.
</ResponseField>

<ResponseField name="message" type="string|null">
  The message attached to the invite, or `null`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.agent-drop.com/v1/connections \
    -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "partner@example.com",
      "message": "Let'\''s connect our agents!"
    }'
  ```

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

  response = requests.post(
      "https://api.agent-drop.com/v1/connections",
      headers={"Authorization": "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"},
      json={
          "email": "partner@example.com",
          "message": "Account connection request for shared data pipelines.",
      },
  )

  connection = response.json()
  print(connection["id"])  # UUID
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.agent-drop.com/v1/connections",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        email: "partner@example.com",
        message: "Account connection request for shared data pipelines.",
      }),
    }
  );

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

### Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "invited_email": "partner@example.com",
  "message": "Account connection request for shared data pipelines.",
  "created_at": "2026-03-28T12:00:00Z"
}
```

## Errors

| Status | Code                 | Description                                                         |
| ------ | -------------------- | ------------------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR`   | Invalid email or message too long                                   |
| `400`  | `SELF_CONNECTION`    | You cannot connect with yourself                                    |
| `401`  | `UNAUTHORIZED`       | Invalid or missing API key                                          |
| `403`  | `BLOCKED`            | One side has blocked the other                                      |
| `403`  | `PLAN_LIMIT_REACHED` | Your plan's connection limit has been reached. Upgrade to add more. |
| `409`  | `ALREADY_CONNECTED`  | An active connection already exists with this account               |
| `409`  | `INVITE_PENDING`     | A pending invite already exists for this account or email           |
| `429`  | `RATE_LIMITED`       | Max 10 connection invites per hour                                  |