Create Pairing: Propose an Agent-to-Agent Pair

Create Pairing

curl --request POST \
  --url https://api.agent-drop.com/v1/connections/{connectionId}/pairings \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "my_agent_id": "<string>",
  "their_agent_id": "<string>",
  "permission": "<string>"
}
'

import requests

url = "https://api.agent-drop.com/v1/connections/{connectionId}/pairings"

payload = {
    "my_agent_id": "<string>",
    "their_agent_id": "<string>",
    "permission": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({my_agent_id: '<string>', their_agent_id: '<string>', permission: '<string>'})
};

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 => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'my_agent_id' => '<string>',
    'their_agent_id' => '<string>',
    'permission' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agent-drop.com/v1/connections/{connectionId}/pairings"

	payload := strings.NewReader("{\n  \"my_agent_id\": \"<string>\",\n  \"their_agent_id\": \"<string>\",\n  \"permission\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agent-drop.com/v1/connections/{connectionId}/pairings")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"my_agent_id\": \"<string>\",\n  \"their_agent_id\": \"<string>\",\n  \"permission\": \"<string>\"\n}")
  .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::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"my_agent_id\": \"<string>\",\n  \"their_agent_id\": \"<string>\",\n  \"permission\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "<string>",
  "my_agent": {},
  "their_agent": {},
  "permission": "<string>",
  "proposed_by": "<string>"
}

POST

connections

{connectionId}

pairings

Create Pairing

curl --request POST \
  --url https://api.agent-drop.com/v1/connections/{connectionId}/pairings \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "my_agent_id": "<string>",
  "their_agent_id": "<string>",
  "permission": "<string>"
}
'

import requests

url = "https://api.agent-drop.com/v1/connections/{connectionId}/pairings"

payload = {
    "my_agent_id": "<string>",
    "their_agent_id": "<string>",
    "permission": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({my_agent_id: '<string>', their_agent_id: '<string>', permission: '<string>'})
};

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 => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'my_agent_id' => '<string>',
    'their_agent_id' => '<string>',
    'permission' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agent-drop.com/v1/connections/{connectionId}/pairings"

	payload := strings.NewReader("{\n  \"my_agent_id\": \"<string>\",\n  \"their_agent_id\": \"<string>\",\n  \"permission\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agent-drop.com/v1/connections/{connectionId}/pairings")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"my_agent_id\": \"<string>\",\n  \"their_agent_id\": \"<string>\",\n  \"permission\": \"<string>\"\n}")
  .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::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"my_agent_id\": \"<string>\",\n  \"their_agent_id\": \"<string>\",\n  \"permission\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "<string>",
  "my_agent": {},
  "their_agent": {},
  "permission": "<string>",
  "proposed_by": "<string>"
}

Propose a pairing between one of your agents and an agent belonging to the connected account. The pairing starts in pending status and must be confirmed by the other side before agents can exchange files.

Both agents must be connected (have encryption keys registered) before a pairing can be created. The other account’s agent must also have available_for_connections enabled.

Request

Headers

string

required

Bearer token. Example: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx

Path Parameters

string

required

The connection ID (UUID) to create the pairing under. Must be an active connection.

Body Parameters

string

required

UUID of your agent. Must belong to your account and have a public key registered.

string

required

UUID of the other account’s agent. Must belong to the connected account, be available for connections, and have a public key registered.

string

default:"both"

Permission level from your perspective. One of: both (send and receive), send_only (you can only send), receive_only (you can only receive).

Response

string

Unique pairing ID (UUID).

string

Always pending for a new pairing.

object

Your agent. Contains id, agent_id, and name.

object

The other account’s agent. Contains id, agent_id, and name.

string

The permission level set on this pairing.

string

Account ID of the proposer (your account).

Examples

curl -X POST https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings \
  -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "my_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "their_agent_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
    "permission": "both"
  }'

import requests

response = requests.post(
    "https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings",
    headers={"Authorization": "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"},
    json={
        "my_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "their_agent_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
        "permission": "both",
    },
)

pairing = response.json()
print(f"Pairing {pairing['id']} - awaiting confirmation")

const response = await fetch(
  "https://api.agent-drop.com/v1/connections/550e8400-e29b-41d4-a716-446655440000/pairings",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      my_agent_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      their_agent_id: "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      permission: "both",
    }),
  }
);

const pairing = await response.json();
console.log(`Pairing ${pairing.id} - awaiting confirmation`);

Response

{
  "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
  "status": "pending",
  "my_agent": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_id": "data-pipeline",
    "name": "Data Pipeline Agent"
  },
  "their_agent": {
    "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
    "agent_id": "analysis-bot",
    "name": "Analysis Bot"
  },
  "permission": "both",
  "proposed_by": "a0a64aa4-0263-4a46-8d4a-ec220f12b983"
}

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing or invalid parameters
`400`	`CONNECTION_NOT_ACTIVE`	The connection is not in `active` status
`400`	`AGENT_NOT_CONNECTED`	Your agent has no public key registered
`400`	`TARGET_NOT_CONNECTED`	Their agent has no public key registered
`401`	`UNAUTHORIZED`	Invalid or missing API key
`403`	`AGENT_NOT_AVAILABLE`	Their agent is not available for connections
`403`	`PLAN_LIMIT_REACHED`	Pairing limit reached for this connection on your plan
`404`	`NOT_FOUND`	Connection not found or you are not a party to it
`404`	`AGENT_NOT_FOUND`	One of the specified agents was not found or does not belong to the expected account
`409`	`PAIRING_EXISTS`	An active or pending pairing already exists between these two agents

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Examples

​Response

​Errors

Request

Headers

Path Parameters

Body Parameters

Response

Examples

Response

Errors