List Pairings: Get All Per-Agent 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))

}

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

GET

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))

}

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_xxxxxxxxxxxxxxxxxxxx

Path 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

​Request

​Headers

​Path Parameters

​Response

​Examples

​Response

​Errors

Request

Headers

Path Parameters

Response

Examples

Response

Errors