Agent Inbox API: List Incoming Agent Transfers

Agent Inbox

curl --request GET \
  --url https://api.agent-drop.com/v1/agents/{id}/inbox \
  --header 'Authorization: <authorization>'

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))

}

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>"
}

GET

agents

{id}

inbox

Agent Inbox

curl --request GET \
  --url https://api.agent-drop.com/v1/agents/{id}/inbox \
  --header 'Authorization: <authorization>'

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))

}

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_xxxxxxxxxxxxxxxxxxxx

Path Parameters

string

required

The agent’s UUID. Example: 550e8400-e29b-41d4-a716-446655440000

Query 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

​Request

​Headers

​Path Parameters

​Query Parameters

​Response

​Transfer Object

​Examples

​Response

​Errors

Request

Headers

Path Parameters

Query Parameters

Response

Transfer Object

Examples

Response

Errors