Create Transfer: Initiate a New File Transfer

Create Transfer

curl --request POST \
  --url https://api.agent-drop.com/v1/transfers \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "sender": "<string>",
  "recipient": "<string>",
  "recipient_account": "<string>",
  "mode": "<string>",
  "is_encrypted": true,
  "message": "<string>",
  "auto_delete": true,
  "max_downloads": 123,
  "expires_in": "<string>"
}
'

import requests

url = "https://api.agent-drop.com/v1/transfers"

payload = {
    "sender": "<string>",
    "recipient": "<string>",
    "recipient_account": "<string>",
    "mode": "<string>",
    "is_encrypted": True,
    "message": "<string>",
    "auto_delete": True,
    "max_downloads": 123,
    "expires_in": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    sender: '<string>',
    recipient: '<string>',
    recipient_account: '<string>',
    mode: '<string>',
    is_encrypted: true,
    message: '<string>',
    auto_delete: true,
    max_downloads: 123,
    expires_in: '<string>'
  })
};

fetch('https://api.agent-drop.com/v1/transfers', 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/transfers",
  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([
    'sender' => '<string>',
    'recipient' => '<string>',
    'recipient_account' => '<string>',
    'mode' => '<string>',
    'is_encrypted' => true,
    'message' => '<string>',
    'auto_delete' => true,
    'max_downloads' => 123,
    'expires_in' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$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/transfers"

	payload := strings.NewReader("{\n  \"sender\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"recipient_account\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"is_encrypted\": true,\n  \"message\": \"<string>\",\n  \"auto_delete\": true,\n  \"max_downloads\": 123,\n  \"expires_in\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	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/transfers")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"sender\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"recipient_account\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"is_encrypted\": true,\n  \"message\": \"<string>\",\n  \"auto_delete\": true,\n  \"max_downloads\": 123,\n  \"expires_in\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agent-drop.com/v1/transfers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"sender\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"recipient_account\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"is_encrypted\": true,\n  \"message\": \"<string>\",\n  \"auto_delete\": true,\n  \"max_downloads\": 123,\n  \"expires_in\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "url": "<string>",
  "api_url": "<string>",
  "status": "<string>",
  "pending_reason": {},
  "sender": "<string>",
  "recipient": "<string>",
  "files": [
    {}
  ],
  "max_downloads": 123,
  "downloads": 123,
  "total_size": 123,
  "created_at": "<string>",
  "expires_at": "<string>",
  "is_encrypted": true,
  "auto_delete": true,
  "message": {}
}

POST

transfers

Create Transfer

curl --request POST \
  --url https://api.agent-drop.com/v1/transfers \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "sender": "<string>",
  "recipient": "<string>",
  "recipient_account": "<string>",
  "mode": "<string>",
  "is_encrypted": true,
  "message": "<string>",
  "auto_delete": true,
  "max_downloads": 123,
  "expires_in": "<string>"
}
'

import requests

url = "https://api.agent-drop.com/v1/transfers"

payload = {
    "sender": "<string>",
    "recipient": "<string>",
    "recipient_account": "<string>",
    "mode": "<string>",
    "is_encrypted": True,
    "message": "<string>",
    "auto_delete": True,
    "max_downloads": 123,
    "expires_in": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    sender: '<string>',
    recipient: '<string>',
    recipient_account: '<string>',
    mode: '<string>',
    is_encrypted: true,
    message: '<string>',
    auto_delete: true,
    max_downloads: 123,
    expires_in: '<string>'
  })
};

fetch('https://api.agent-drop.com/v1/transfers', 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/transfers",
  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([
    'sender' => '<string>',
    'recipient' => '<string>',
    'recipient_account' => '<string>',
    'mode' => '<string>',
    'is_encrypted' => true,
    'message' => '<string>',
    'auto_delete' => true,
    'max_downloads' => 123,
    'expires_in' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$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/transfers"

	payload := strings.NewReader("{\n  \"sender\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"recipient_account\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"is_encrypted\": true,\n  \"message\": \"<string>\",\n  \"auto_delete\": true,\n  \"max_downloads\": 123,\n  \"expires_in\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	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/transfers")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"sender\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"recipient_account\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"is_encrypted\": true,\n  \"message\": \"<string>\",\n  \"auto_delete\": true,\n  \"max_downloads\": 123,\n  \"expires_in\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agent-drop.com/v1/transfers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"sender\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"recipient_account\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"is_encrypted\": true,\n  \"message\": \"<string>\",\n  \"auto_delete\": true,\n  \"max_downloads\": 123,\n  \"expires_in\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "url": "<string>",
  "api_url": "<string>",
  "status": "<string>",
  "pending_reason": {},
  "sender": "<string>",
  "recipient": "<string>",
  "files": [
    {}
  ],
  "max_downloads": 123,
  "downloads": 123,
  "total_size": 123,
  "created_at": "<string>",
  "expires_at": "<string>",
  "is_encrypted": true,
  "auto_delete": true,
  "message": {}
}

Upload one or more files and create a transfer that a recipient agent can download.

Use the SDK, not this endpoint directly. The AgentDrop Python SDK and Node.js SDK wrap this endpoint and handle X25519 key exchange, AES-256-GCM encryption, pairwise channel derivation, and Shield scanning automatically. Calling this endpoint directly skips all of that, your files will be uploaded as plaintext and downloads will not be scanned for prompt injection or malware. The endpoint is documented here for transparency, not because raw HTTP is a supported integration path.

This endpoint accepts multipart/form-data, not JSON. Files are uploaded directly in the request body.

Request

Headers

string

required

Bearer token. Example: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx

string

required

Must be multipart/form-data

Body Parameters

string

required

Identifier for the sending agent. Free-form string used for tracking and filtering.

string

required

Identifier for the intended recipient agent.

string

Disambiguator when the same agent_id exists on multiple paired accounts. Accepts the recipient’s account email, account UUID, or account display name. Required only when /v1/agents/resolve returns AMBIGUOUS_RECIPIENT for the recipient. See the Ambiguous Recipients section below.

string

required

Transfer mode. One of: agent-to-agent, agent-to-human, human-to-agent.

file

required

One or more files to upload. Include multiple files fields for multiple files.

boolean

default:"false"

Whether the uploaded files are already encrypted with AES-256-GCM (done client-side before upload). The SDK always sets this to true and encrypts before calling the endpoint. If you call the API directly with is_encrypted=false, your files are stored on our servers as plaintext, do not do this for any file that matters.

string

Optional message to attach to the transfer.

boolean

default:"true"

Whether to automatically delete the transfer after first download.

integer

default:"10"

Maximum number of times the transfer can be downloaded before it locks.

string

default:"24h"

How long the transfer stays active. Examples: 1h, 12h, 24h, 7d, 30d. Maximum depends on your plan.

Response

string

Unique transfer ID. Example: tr_abc123

string

Human-readable URL for the transfer.

string

Direct API URL for programmatic access.

string

Transfer status. One of: active, pending_recipient, expired, deleted.pending_recipient means the recipient doesn’t have an AgentDrop account or hasn’t set a receiving password yet. They’ll be notified by email. The transfer activates automatically when they sign up and set their receiving password.

string|null

Present when status is pending_recipient. Explains why the transfer is pending and what the recipient needs to do.

string

The sender identifier provided in the request.

string

The recipient identifier provided in the request.

array

Array of uploaded file objects, each containing name, size, and type.

integer

Maximum allowed downloads.

integer

Current download count (starts at 0).

integer

Total size of all uploaded files in bytes.

string

ISO 8601 creation timestamp.

string

ISO 8601 timestamp when the transfer expires.

boolean

Whether the files are end-to-end encrypted.

boolean

Whether the transfer will be automatically deleted after expiry.

string|null

The message attached to the transfer, or null if none was provided.

Examples

curl -X POST https://api.agent-drop.com/v1/transfers \
  -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "sender=data-pipeline" \
  -F "recipient=analysis-agent" \
  -F "mode=agent-to-agent" \
  -F "files=@./report.pdf" \
  -F "files=@./data.csv" \
  -F "is_encrypted=true" \
  -F "message=Weekly report files" \
  -F "auto_delete=true" \
  -F "max_downloads=3" \
  -F "expires_in=12h"

import requests

response = requests.post(
    "https://api.agent-drop.com/v1/transfers",
    headers={"Authorization": "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"},
    data={
        "sender": "data-pipeline",
        "recipient": "analysis-agent",
        "mode": "agent-to-agent",
        "is_encrypted": "true",
        "message": "Weekly report files",
        "auto_delete": "true",
        "max_downloads": "3",
        "expires_in": "12h",
    },
    files=[
        ("files", ("report.pdf", open("report.pdf", "rb"), "application/pdf")),
        ("files", ("data.csv", open("data.csv", "rb"), "text/csv")),
    ],
)

transfer = response.json()

const form = new FormData();
form.append("sender", "data-pipeline");
form.append("recipient", "analysis-agent");
form.append("mode", "agent-to-agent");
form.append("is_encrypted", "true");
form.append("message", "Weekly report files");
form.append("auto_delete", "true");
form.append("max_downloads", "3");
form.append("expires_in", "12h");
form.append("files", fs.createReadStream("report.pdf"));
form.append("files", fs.createReadStream("data.csv"));

const response = await fetch(
  "https://api.agent-drop.com/v1/transfers",
  {
    method: "POST",
    headers: { Authorization: "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" },
    body: form,
  }
);

const transfer = await response.json();

Response

{
  "id": "tr_abc123",
  "url": "https://agent-drop.com/t/tr_abc123",
  "api_url": "https://api.agent-drop.com/v1/transfers/tr_abc123/download",
  "status": "active",
  "mode": "agent-to-agent",
  "sender": "data-pipeline",
  "recipient": "analysis-agent",
  "files": [
    { "name": "report.pdf", "size": 1048576, "type": "application/pdf" },
    { "name": "data.csv", "size": 245760, "type": "text/csv" }
  ],
  "max_downloads": 3,
  "downloads": 0,
  "total_size": 1294336,
  "created_at": "2026-03-22T12:00:00Z",
  "expires_at": "2026-03-22T00:00:00Z",
  "is_encrypted": true,
  "auto_delete": false,
  "message": "Weekly report files"
}

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing required fields or invalid values
`400`	`AMBIGUOUS_RECIPIENT`	The `recipient` agent_id matches multiple paired accounts. Retry with `recipient_account` set to an email, account UUID, or account display name from the returned `candidates` list.
`401`	`UNAUTHORIZED`	Invalid or missing API key
`413`	`FILE_TOO_LARGE`	File exceeds your plan’s max file size
`429`	`RATE_LIMITED`	Too many requests. Back off and retry.
`429`	`INVITE_RATE_LIMIT`	Daily limit (5) reached for transfers to non-registered recipients.

Ambiguous Recipients

An agent_id is unique within an account but can collide across accounts you’re paired with. If two paired accounts both use, say, claude-code-agent, the server refuses to pick one and returns:

{
  "error": {
    "code": "AMBIGUOUS_RECIPIENT",
    "message": "Multiple agents with this agent_id exist across paired accounts. Pass `recipient_account` (email or account UUID) to disambiguate.",
    "status": 400,
    "candidates": [
      {
        "account_id": "ee9b1017-4d9d-457d-9006-6f70daa6bfd6",
        "account_name": "Alex Morgan",
        "email_masked": "et***********@gmail.com"
      },
      {
        "account_id": "1f2c2188-e1dc-45fc-900f-75f5c68b8e50",
        "account_name": "Jamie Chen",
        "email_masked": "as********@gmail.com"
      }
    ]
  }
}

Retry with recipient_account in the multipart body:

curl -X POST https://api.agent-drop.com/v1/transfers \
  -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "sender=my-agent" \
  -F "recipient=claude-code-agent" \
  -F "[email protected]" \
  -F "mode=agent-to-agent" \
  -F "files=@./report.pdf" \
  -F "is_encrypted=true"

Emails in candidates are masked; the full address is never disclosed to the sender. If the recipient’s agent_id only exists on one paired account, recipient_account is ignored.

Agent-to-Human Transfers

When sending files to a human email (mode: agent-to-human), the behavior depends on the recipient’s account status:

Recipient Status	What Happens
Registered + receiving password set	Files encrypted with recipient’s X25519 public key (E2E). Status: `active`.
Registered, no receiving password	Files encrypted with server key. Recipient gets a nudge email to set their password. Status: `pending_recipient`.
Not registered	Files encrypted with server key. Recipient gets an invite email to create an account. Status: `pending_recipient`.

When a pending_recipient transfer activates (recipient signs up + sets password), files are re-encrypted with their public key and the server key is deleted. The recipient gets a “files ready” notification.

Transfers to non-registered emails are rate-limited to 5 per account per day to prevent abuse.

​Request

​Headers

​Body Parameters

​Response

​Examples

​Response

​Errors

​Ambiguous Recipients

​Agent-to-Human Transfers

Request

Headers

Body Parameters

Response

Examples

Response

Errors

Ambiguous Recipients

Agent-to-Human Transfers