Agent Inbox
curl --request GET \
--url https://api.agent-drop.com/v1/agents/{id}/inbox \
--header 'Authorization: <authorization>'import requests
url = "https://api.agent-drop.com/v1/agents/{id}/inbox"
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/agents/{id}/inbox', 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/agents/{id}/inbox",
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/agents/{id}/inbox"
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))
}HttpResponse<String> response = Unirest.get("https://api.agent-drop.com/v1/agents/{id}/inbox")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agent-drop.com/v1/agents/{id}/inbox")
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{
"agent_id": "<string>",
"transfers": [
{}
],
"total": 123,
"limit": 123,
"offset": 123,
"transfers[].id": "<string>",
"transfers[].url": "<string>",
"transfers[].api_url": "<string>",
"transfers[].mode": "<string>",
"transfers[].sender": "<string>",
"transfers[].recipient": "<string>",
"transfers[].status": "<string>",
"transfers[].files": [
{}
],
"transfers[].total_size": 123,
"transfers[].file_count": 123,
"transfers[].downloads": 123,
"transfers[].max_downloads": 123,
"transfers[].message": "<string>",
"transfers[].auto_delete": true,
"transfers[].is_encrypted": true,
"transfers[].expires_at": "<string>",
"transfers[].created_at": "<string>"
}Agents
Agent Inbox API: List Incoming Agent Transfers
List all incoming AgentDrop transfers for a specific agent, sorted newest first. Filter by active, expired, or deleted status. Bearer-auth, paginated.
GET
/
v1
/
agents
/
{id}
/
inbox
Agent Inbox
curl --request GET \
--url https://api.agent-drop.com/v1/agents/{id}/inbox \
--header 'Authorization: <authorization>'import requests
url = "https://api.agent-drop.com/v1/agents/{id}/inbox"
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/agents/{id}/inbox', 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/agents/{id}/inbox",
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/agents/{id}/inbox"
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))
}HttpResponse<String> response = Unirest.get("https://api.agent-drop.com/v1/agents/{id}/inbox")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agent-drop.com/v1/agents/{id}/inbox")
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{
"agent_id": "<string>",
"transfers": [
{}
],
"total": 123,
"limit": 123,
"offset": 123,
"transfers[].id": "<string>",
"transfers[].url": "<string>",
"transfers[].api_url": "<string>",
"transfers[].mode": "<string>",
"transfers[].sender": "<string>",
"transfers[].recipient": "<string>",
"transfers[].status": "<string>",
"transfers[].files": [
{}
],
"transfers[].total_size": 123,
"transfers[].file_count": 123,
"transfers[].downloads": 123,
"transfers[].max_downloads": 123,
"transfers[].message": "<string>",
"transfers[].auto_delete": true,
"transfers[].is_encrypted": true,
"transfers[].expires_at": "<string>",
"transfers[].created_at": "<string>"
}List all incoming transfers for a specific agent, filtered by status. Returns the most recent transfers first.
You must use the agent’s UUID (not the
agent_id slug). Find it in Dashboard → Agents or from the register-agent response.Use the SDK’s
.inbox() method or the MCP server’s check_inbox tool for a simpler experience.Request
Headers
string
required
Bearer token. Example:
Bearer agd_live_xxxxxxxxxxxxxxxxxxxxPath Parameters
string
required
The agent’s UUID. Example:
550e8400-e29b-41d4-a716-446655440000Query Parameters
string
default:"active"
Filter transfers by status. One of:
active, expired, deleted.integer
default:"50"
Number of transfers to return. Maximum: 100.
integer
default:"0"
Number of transfers to skip. Used for offset-based pagination.
Response
string
The agent’s slug identifier.
array
Array of transfer objects.
integer
Total number of transfers matching the filter.
integer
Number of items returned.
integer
Current offset.
Transfer Object
string
Unique transfer ID.
string
Human-readable URL for the transfer.
string
Direct API URL for programmatic access.
string
Transfer mode. One of:
agent-to-agent, agent-to-human, human-to-agent.string
The sender identifier.
string
The recipient identifier.
string
Current status:
active, expired, deleted, or downloaded.array
Array of file objects, each containing
name, size, and content_type.integer
Total size of all files in bytes.
integer
Number of files in the transfer.
integer
Number of times this transfer has been downloaded.
integer
Maximum allowed downloads.
string
Optional message attached to the transfer.
boolean
Whether the transfer will be automatically deleted after expiry.
boolean
Whether the files are end-to-end encrypted.
string
ISO 8601 expiry timestamp.
string
ISO 8601 creation timestamp.
Examples
curl -X GET "https://api.agent-drop.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/inbox?status=active&limit=10" \
-H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"
import requests
response = requests.get(
"https://api.agent-drop.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/inbox",
headers={"Authorization": "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"},
params={"status": "active", "limit": 10},
)
data = response.json()
for transfer in data["transfers"]:
print(f"{transfer['id']} - {transfer['sender']} - {len(transfer['files'])} files")
const response = await fetch(
"https://api.agent-drop.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/inbox?status=active&limit=10",
{
headers: { Authorization: "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" },
}
);
const { transfers, total } = await response.json();
console.log(`${total} transfers in inbox`);
transfers.forEach((t) => console.log(`${t.id} from ${t.sender}`));
Response
{
"agent_id": "analysis-agent",
"transfers": [
{
"id": "tr_9f3a7b2e-1c4d-4e5f-8a6b-0d2e3f4a5b6c",
"url": "https://agent-drop.com/t/tr_9f3a7b2e-1c4d-4e5f-8a6b-0d2e3f4a5b6c",
"api_url": "https://api.agent-drop.com/v1/transfers/tr_9f3a7b2e-1c4d-4e5f-8a6b-0d2e3f4a5b6c/download",
"mode": "agent-to-agent",
"sender": "data-pipeline",
"recipient": "analysis-agent",
"status": "active",
"files": [
{ "name": "report.pdf", "size": 1048576, "content_type": "application/pdf" },
{ "name": "metrics.csv", "size": 245760, "content_type": "text/csv" }
],
"total_size": 1294336,
"file_count": 2,
"downloads": 0,
"max_downloads": 10,
"message": "Weekly metrics report",
"auto_delete": false,
"is_encrypted": true,
"expires_at": "2026-03-29T12:00:00Z",
"created_at": "2026-03-28T12:00:00Z"
}
],
"total": 1,
"limit": 10,
"offset": 0
}
Errors
| Status | Code | Description |
|---|---|---|
401 | UNAUTHORIZED | Invalid or missing API key |
403 | FORBIDDEN | You do not own this agent |
404 | NOT_FOUND | Agent UUID does not exist |
