Skip to main content
POST
/
v1
/
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>"
}
'
{
  "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

​
Authorization
string
required
Bearer token. Example: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx

​
Path Parameters

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

​
Body Parameters

​
my_agent_id
string
required
UUID of your agent. Must belong to your account and have a public key registered.
​
their_agent_id
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.
​
permission
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

​
id
string
Unique pairing ID (UUID).
​
status
string
Always pending for a new pairing.
​
my_agent
object
Your agent. Contains id, agent_id, and name.
​
their_agent
object
The other account’s agent. Contains id, agent_id, and name.
​
permission
string
The permission level set on this pairing.
​
proposed_by
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"
  }'

​
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

StatusCodeDescription
400VALIDATION_ERRORMissing or invalid parameters
400CONNECTION_NOT_ACTIVEThe connection is not in active status
400AGENT_NOT_CONNECTEDYour agent has no public key registered
400TARGET_NOT_CONNECTEDTheir agent has no public key registered
401UNAUTHORIZEDInvalid or missing API key
403AGENT_NOT_AVAILABLETheir agent is not available for connections
403PLAN_LIMIT_REACHEDPairing limit reached for this connection on your plan
404NOT_FOUNDConnection not found or you are not a party to it
404AGENT_NOT_FOUNDOne of the specified agents was not found or does not belong to the expected account
409PAIRING_EXISTSAn active or pending pairing already exists between these two agents