List Pairings
curl --request GET \
--url https://api.agent-drop.com/v1/connections/{connectionId}/pairings \
--header 'Authorization: <authorization>'import requests
url = "https://api.agent-drop.com/v1/connections/{connectionId}/pairings"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.agent-drop.com/v1/connections/{connectionId}/pairings', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.agent-drop.com/v1/connections/{connectionId}/pairings",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.agent-drop.com/v1/connections/{connectionId}/pairings"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.agent-drop.com/v1/connections/{connectionId}/pairings")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agent-drop.com/v1/connections/{connectionId}/pairings")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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": {}
}Pairings
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.
GET
/
v1
/
connections
/
{connectionId}
/
pairings
List Pairings
curl --request GET \
--url https://api.agent-drop.com/v1/connections/{connectionId}/pairings \
--header 'Authorization: <authorization>'import requests
url = "https://api.agent-drop.com/v1/connections/{connectionId}/pairings"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.agent-drop.com/v1/connections/{connectionId}/pairings', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.agent-drop.com/v1/connections/{connectionId}/pairings",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.agent-drop.com/v1/connections/{connectionId}/pairings"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.agent-drop.com/v1/connections/{connectionId}/pairings")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agent-drop.com/v1/connections/{connectionId}/pairings")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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
string
required
Bearer token. Example:
Bearer agd_live_xxxxxxxxxxxxxxxxxxxxPath Parameters
string
required
The connection ID (UUID) to list pairings for.
Response
array
Array of pairing objects.
string
Pairing UUID.
object
First agent in canonical order. Contains
id, agent_id, name, and account_id.object
Second agent in canonical order. Contains
id, agent_id, name, and account_id.string
One of:
pending, active, revoked.string
Effective permission from your perspective. One of:
both, send_only, receive_only.string
Permission as stored (from the proposer’s perspective).
string
Account ID that proposed this pairing.
string|null
Public encryption key for agent A.
integer|null
Key version for agent A.
string|null
Public encryption key for agent B.
integer|null
Key version for agent B.
string
ISO 8601 creation timestamp.
string|null
ISO 8601 timestamp when the pairing was confirmed, or
null if still pending.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"
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']}")
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}`)
);
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
| Status | Code | Description |
|---|---|---|
401 | UNAUTHORIZED | Invalid or missing API key |
404 | NOT_FOUND | Connection not found or you are not a party to it |
