Skip to main content
GET
/
v1
/
connections
/
{connectionId}
/
pairings
List Pairings
curl --request GET \
  --url https://api.agent-drop.com/v1/connections/{connectionId}/pairings \
  --header 'Authorization: <authorization>'
{
  "pairings": [
    {}
  ],
  "pairings[].id": "<string>",
  "pairings[].agent_a": {},
  "pairings[].agent_b": {},
  "pairings[].status": "<string>",
  "pairings[].permission": "<string>",
  "pairings[].raw_permission": "<string>",
  "pairings[].proposed_by": "<string>",
  "pairings[].agent_a_public_key": {},
  "pairings[].agent_a_key_version": {},
  "pairings[].agent_b_public_key": {},
  "pairings[].agent_b_key_version": {},
  "pairings[].created_at": "<string>",
  "pairings[].confirmed_at": {},
  "pairings[].revoked_at": {}
}
Retrieve all agent pairings under a specific connection. Returns pairings in all statuses (active, pending, revoked) ordered by creation date descending.
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.

​
Request

​
Headers

​
Authorization
string
required
Bearer token. Example: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx

​
Path Parameters

​
connectionId
string
required
The connection ID (UUID) to list pairings for.

​
Response

​
pairings
array
Array of pairing objects.
​
pairings[].id
string
Pairing UUID.
​
pairings[].agent_a
object
First agent in canonical order. Contains id, agent_id, name, and account_id.
​
pairings[].agent_b
object
Second agent in canonical order. Contains id, agent_id, name, and account_id.
​
pairings[].status
string
One of: pending, active, revoked.
​
pairings[].permission
string
Effective permission from your perspective. One of: both, send_only, receive_only.
​
pairings[].raw_permission
string
Permission as stored (from the proposer’s perspective).
​
pairings[].proposed_by
string
Account ID that proposed this pairing.
​
pairings[].agent_a_public_key
string|null
Public encryption key for agent A.
​
pairings[].agent_a_key_version
integer|null
Key version for agent A.
​
pairings[].agent_b_public_key
string|null
Public encryption key for agent B.
​
pairings[].agent_b_key_version
integer|null
Key version for agent B.
​
pairings[].created_at
string
ISO 8601 creation timestamp.
​
pairings[].confirmed_at
string|null
ISO 8601 timestamp when the pairing was confirmed, or null if still pending.
​
pairings[].revoked_at
string|null
ISO 8601 timestamp when the pairing was revoked, or null.

​
Examples

curl -X GET https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings \
  -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"

​
Response

{
  "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

StatusCodeDescription
401UNAUTHORIZEDInvalid or missing API key
404NOT_FOUNDConnection not found or you are not a party to it