Skip to main content
POST
/
v1
/
transfers
/
presigned
Presigned Upload
curl --request POST \
  --url https://api.agent-drop.com/v1/transfers/presigned \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "mode": "<string>",
  "sender": "<string>",
  "recipient": "<string>",
  "files": [
    {}
  ],
  "expires_in": "<string>",
  "max_downloads": 123,
  "message": "<string>",
  "metadata": {},
  "is_encrypted": true,
  "encrypted_key": "<string>",
  "encryption_algorithm": "<string>",
  "auto_delete": true
}
'
{
  "id": "<string>",
  "upload_urls": [
    {}
  ],
  "upload_urls[].file_id": "<string>",
  "upload_urls[].file_name": "<string>",
  "upload_urls[].upload_url": "<string>",
  "upload_urls[].method": "<string>",
  "upload_urls[].headers": {},
  "confirm_url": "<string>",
  "expires_at": "<string>"
}
Get presigned URLs for uploading files directly to storage. Use this for browser uploads, large files, or when you want to upload files from the client side without routing them through your backend.
After uploading all files to the presigned URLs, you must call confirm-transfer to activate the transfer. The transfer stays in pending status until confirmed.

​
Request

​
Headers

​
Authorization
string
required
Bearer token. Example: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
mode
string
required
Transfer mode. One of: agent-to-agent, agent-to-human, human-to-agent.
​
sender
string
required
Identifier for the sending agent or human.
​
recipient
string
required
Identifier for the intended recipient agent or human.
​
files
array
required
Array of file descriptor objects. Each object must contain name, size, and content_type. Optionally include encryption_iv if the file is client-side encrypted.
​
expires_in
string
default:"24h"
How long the transfer stays active. Examples: 1h, 12h, 24h, 7d, 30d.
​
max_downloads
integer
default:"10"
Maximum number of times the transfer can be downloaded.
​
message
string
Optional message to attach to the transfer.
​
metadata
object
Optional metadata object for custom key-value pairs.
​
is_encrypted
boolean
default:"false"
Whether the files are client-side encrypted before upload.
​
encrypted_key
string
Base64-encoded encrypted symmetric key. Required when is_encrypted is true.
​
encryption_algorithm
string
default:"AES-256-GCM"
Encryption algorithm used. Currently only AES-256-GCM is supported.
​
auto_delete
boolean
default:"false"
Whether to automatically delete the transfer after it expires.

​
Response

​
id
string
The transfer ID. Use this when calling the confirm endpoint.
​
upload_urls
array
Array of presigned upload objects, one per file.
​
upload_urls[].file_id
string
Unique ID for this file within the transfer.
​
upload_urls[].file_name
string
The file name you specified.
​
upload_urls[].upload_url
string
Presigned URL to upload the file to.
​
upload_urls[].method
string
HTTP method to use. Typically PUT.
​
upload_urls[].headers
object
Headers to include in the upload request.
​
confirm_url
string
URL to call after all files are uploaded.
​
expires_at
string
ISO 8601 timestamp when the presigned URLs expire.

​
Examples

curl -X POST https://api.agent-drop.com/v1/transfers/presigned \
  -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "agent-to-agent",
    "sender": "data-pipeline",
    "recipient": "analysis-agent",
    "files": [
      { "name": "report.pdf", "size": 1048576, "content_type": "application/pdf" },
      { "name": "data.csv", "size": 245760, "content_type": "text/csv" }
    ],
    "expires_in": "12h",
    "max_downloads": 3,
    "message": "Weekly metrics"
  }'

​
Response

{
  "id": "tr_4d2e8f1a-6b3c-4a7e-9d0f-5e8c1b2a3d4e",
  "upload_urls": [
    {
      "file_id": "file_a1b2c3d4",
      "file_name": "report.pdf",
      "upload_url": "https://storage.agent-drop.com/uploads/tr_4d2e8f1a.../report.pdf?X-Amz-Signature=...",
      "method": "PUT",
      "headers": { "Content-Type": "application/pdf" }
    },
    {
      "file_id": "file_e5f6g7h8",
      "file_name": "data.csv",
      "upload_url": "https://storage.agent-drop.com/uploads/tr_4d2e8f1a.../data.csv?X-Amz-Signature=...",
      "method": "PUT",
      "headers": { "Content-Type": "text/csv" }
    }
  ],
  "confirm_url": "https://api.agent-drop.com/v1/transfers/tr_4d2e8f1a-6b3c-4a7e-9d0f-5e8c1b2a3d4e/confirm",
  "expires_at": "2026-03-28T13:00:00Z"
}

​
Errors

StatusCodeDescription
400VALIDATION_ERRORMissing required fields or invalid values
401UNAUTHORIZEDInvalid or missing API key
413FILE_TOO_LARGEFile size exceeds your plan’s limit
429RATE_LIMITEDToo many requests. Back off and retry.