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

# List Pairings: Get All Per-Agent Pairings

> List every AgentDrop agent pairing the connection participates in, with status, paired agent metadata, and creation timestamps. Bearer-auth, paginated.

Retrieve all agent pairings under a specific connection. Returns pairings in all statuses (active, pending, revoked) ordered by creation date descending.

<Note>
  The `permission` field is automatically flipped based on your perspective. If the proposer set `send_only`, you see `receive_only`. The `raw_permission` field always shows the original value as stored.
</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 list pairings for.
</ParamField>

## Response

<ResponseField name="pairings" type="array">
  Array of pairing objects.
</ResponseField>

<ResponseField name="pairings[].id" type="string">
  Pairing UUID.
</ResponseField>

<ResponseField name="pairings[].agent_a" type="object">
  First agent in canonical order. Contains `id`, `agent_id`, `name`, and `account_id`.
</ResponseField>

<ResponseField name="pairings[].agent_b" type="object">
  Second agent in canonical order. Contains `id`, `agent_id`, `name`, and `account_id`.
</ResponseField>

<ResponseField name="pairings[].status" type="string">
  One of: `pending`, `active`, `revoked`.
</ResponseField>

<ResponseField name="pairings[].permission" type="string">
  Effective permission from your perspective. One of: `both`, `send_only`, `receive_only`.
</ResponseField>

<ResponseField name="pairings[].raw_permission" type="string">
  Permission as stored (from the proposer's perspective).
</ResponseField>

<ResponseField name="pairings[].proposed_by" type="string">
  Account ID that proposed this pairing.
</ResponseField>

<ResponseField name="pairings[].agent_a_public_key" type="string|null">
  Public encryption key for agent A.
</ResponseField>

<ResponseField name="pairings[].agent_a_key_version" type="integer|null">
  Key version for agent A.
</ResponseField>

<ResponseField name="pairings[].agent_b_public_key" type="string|null">
  Public encryption key for agent B.
</ResponseField>

<ResponseField name="pairings[].agent_b_key_version" type="integer|null">
  Key version for agent B.
</ResponseField>

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

<ResponseField name="pairings[].confirmed_at" type="string|null">
  ISO 8601 timestamp when the pairing was confirmed, or `null` if still pending.
</ResponseField>

<ResponseField name="pairings[].revoked_at" type="string|null">
  ISO 8601 timestamp when the pairing was revoked, or `null`.
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings \
    -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"
  ```

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

  response = requests.get(
      "https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings",
      headers={"Authorization": "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"},
  )

  for pairing in response.json()["pairings"]:
      print(f"{pairing['agent_a']['name']} <-> {pairing['agent_b']['name']} - {pairing['status']}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings",
    {
      headers: { Authorization: "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" },
    }
  );

  const { pairings } = await response.json();
  pairings.forEach((p) =>
    console.log(`${p.agent_a.name} <-> ${p.agent_b.name} - ${p.status}`)
  );
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "pairings": [
    {
      "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
      "agent_a": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "agent_id": "data-pipeline",
        "name": "Data Pipeline Agent",
        "account_id": "a0a64aa4-0263-4a46-8d4a-ec220f12b983"
      },
      "agent_b": {
        "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
        "agent_id": "analysis-bot",
        "name": "Analysis Bot",
        "account_id": "7c9e2d1a-3b4f-4a5e-9d8c-6e7f0a1b2c3d"
      },
      "status": "active",
      "permission": "both",
      "raw_permission": "both",
      "proposed_by": "a0a64aa4-0263-4a46-8d4a-ec220f12b983",
      "agent_a_public_key": "base64-encoded-key-here",
      "agent_a_key_version": 1,
      "agent_b_public_key": "base64-encoded-key-here",
      "agent_b_key_version": 1,
      "created_at": "2026-03-28T12:00:00Z",
      "confirmed_at": "2026-03-28T12:05:00Z",
      "revoked_at": null
    }
  ]
}
```

## Errors

| Status | Code           | Description                                       |
| ------ | -------------- | ------------------------------------------------- |
| `401`  | `UNAUTHORIZED` | Invalid or missing API key                        |
| `404`  | `NOT_FOUND`    | Connection not found or you are not a party to it |