Skip to main content
GET
/
v1
/
agents
/
{id}
/
inbox
Agent Inbox
curl --request GET \
  --url https://api.agent-drop.com/v1/agents/{id}/inbox \
  --header 'Authorization: <authorization>'
{
  "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

​
Authorization
string
required
Bearer token. Example: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx

​
Path Parameters

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

​
Query Parameters

​
status
string
default:"active"
Filter transfers by status. One of: active, expired, deleted.
​
limit
integer
default:"50"
Number of transfers to return. Maximum: 100.
​
offset
integer
default:"0"
Number of transfers to skip. Used for offset-based pagination.

​
Response

​
agent_id
string
The agent’s slug identifier.
​
transfers
array
Array of transfer objects.
​
total
integer
Total number of transfers matching the filter.
​
limit
integer
Number of items returned.
​
offset
integer
Current offset.

​
Transfer Object

​
transfers[].id
string
Unique transfer ID.
​
transfers[].url
string
Human-readable URL for the transfer.
​
transfers[].api_url
string
Direct API URL for programmatic access.
​
transfers[].mode
string
Transfer mode. One of: agent-to-agent, agent-to-human, human-to-agent.
​
transfers[].sender
string
The sender identifier.
​
transfers[].recipient
string
The recipient identifier.
​
transfers[].status
string
Current status: active, expired, deleted, or downloaded.
​
transfers[].files
array
Array of file objects, each containing name, size, and content_type.
​
transfers[].total_size
integer
Total size of all files in bytes.
​
transfers[].file_count
integer
Number of files in the transfer.
​
transfers[].downloads
integer
Number of times this transfer has been downloaded.
​
transfers[].max_downloads
integer
Maximum allowed downloads.
​
transfers[].message
string
Optional message attached to the transfer.
​
transfers[].auto_delete
boolean
Whether the transfer will be automatically deleted after expiry.
​
transfers[].is_encrypted
boolean
Whether the files are end-to-end encrypted.
​
transfers[].expires_at
string
ISO 8601 expiry timestamp.
​
transfers[].created_at
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"

​
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

StatusCodeDescription
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENYou do not own this agent
404NOT_FOUNDAgent UUID does not exist