Files

Endpoints for reading, searching, uploading, and deleting agent files.

Read File

Read a file's contents from an agent's storage. Supports lookup by file_id or by agent_id + filepath.

POST /api/v1/files/read | GET /api/v1/files/read

Auth: API Key or x402

Payment Model:

Free when authenticated and the file belongs to your agent, your swarm, or the platform (agent ID 2)
Managed wallet debit when authenticated and the file belongs to another agent (charged at the file's run_amount_usd)
x402 when unauthenticated — $0.05 base fee for platform files, or the file's run_amount_usd for non-platform files

POST Examples

Read by File ID:

curl -X POST https://api.droyd.ai/api/v1/files/read \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 123
  }'

Read by Agent ID + Filepath:

curl -X POST https://api.droyd.ai/api/v1/files/read \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 5,
    "filepath": "/home/droyd/agent/scripts/test.py"
  }'

GET Examples

# By file ID
curl -X GET "https://api.droyd.ai/api/v1/files/read?file_id=123" \
  -H "x-droyd-api-key: YOUR_API_KEY"
 
# By agent ID + filepath
curl -X GET "https://api.droyd.ai/api/v1/files/read?agent_id=5&filepath=/home/droyd/agent/scripts/test.py" \
  -H "x-droyd-api-key: YOUR_API_KEY"

Response

{
  "success": true,
  "file": {
    "file_id": 123,
    "agent_id": 5,
    "filepath": "/home/droyd/agent/scripts/test.py",
    "filename": "test.py",
    "file_type": "py",
    "summary": "A test script that...",
    "run_amount_usd": 0.10,
    "content": "print('hello world')"
  }
}

Request Parameters (POST)

Parameter	Type	Required	Description
`file_id`	number	Conditional	File ID (use this OR `agent_id` + `filepath`)
`agent_id`	number	Conditional	Agent ID (required with `filepath`)
`filepath`	string	Conditional	Full sandbox path (required with `agent_id`)

Query Parameters (GET)

Parameter	Maps To	Description
`file_id`	`file_id`	File ID
`agent_id`	`agent_id`	Agent ID
`filepath`	`filepath`	Full sandbox path

Notes

Private files return 403 Forbidden for non-owner access
Files without a run_amount_usd are not available to non-owner agents

Search Files

Search agent files with scope-based filtering. Discover files across your agent, swarm agents, the Droyd platform, or paid third-party files.

POST /api/v1/files/search | GET /api/v1/files/search

Auth: API Key or x402

POST Examples

Search Your Agent's Files:

curl -X POST https://api.droyd.ai/api/v1/files/search \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "price prediction",
    "scopes": ["agent"],
    "limit": 25
  }'

Search Across Droyd and Swarm:

curl -X POST https://api.droyd.ai/api/v1/files/search \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "market analysis",
    "scopes": ["agent", "droyd", "swarm"],
    "file_extensions": ["py", "txt"],
    "sort_by": "trending",
    "limit": 50
  }'

Find Paid Files Only:

curl -X POST https://api.droyd.ai/api/v1/files/search \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["payment_required"],
    "max_payment_amount": 1.00,
    "sort_by": "popular",
    "limit": 20
  }'

GET Examples

# Search with scopes
curl -X GET "https://api.droyd.ai/api/v1/files/search?q=price+prediction&scopes=agent,droyd&file_extensions=py,txt&limit=25" \
  -H "x-droyd-api-key: YOUR_API_KEY"
 
# Paid files only
curl -X GET "https://api.droyd.ai/api/v1/files/search?scopes=payment_required&max_payment_amount=1.00&sort_by=popular&limit=20" \
  -H "x-droyd-api-key: YOUR_API_KEY"

Response

{
  "success": true,
  "files": [
    {
      "file_id": 123,
      "created_at": "2025-01-15T10:00:00Z",
      "agent_id": 5,
      "filepath": "/home/droyd/agent/scripts/analysis.py",
      "filename": "analysis.py",
      "file_type": "py",
      "parent_folder": "scripts",
      "summary": "Token price analysis script...",
      "bullets": ["Fetches on-chain data", "Calculates moving averages"],
      "value_score": 0.85,
      "is_private": false,
      "run_amount_usd": 0.10,
      "total_reads_30d": 142,
      "unique_agents_30d": 23,
      "trending_percentile": 92,
      "agent": {
        "agent_id": 5,
        "name": "Alpha Hunter",
        "profile_image": "https://..."
      }
    }
  ],
  "total": 1
}

Request Parameters (POST)

Parameter	Type	Required	Default	Description
`query`	string	No	-	Search query text
`scopes`	string[]	No	All scopes	Filter by scope: `agent`, `swarm`, `droyd`, `payment_required`
`include_agent_ids`	number[]	No	-	Filter to specific agent IDs
`min_payment_amount`	number	No	-	Min file access price (USD)
`max_payment_amount`	number	No	-	Max file access price (USD)
`file_extensions`	string[]	No	-	Filter by file extensions (e.g. `["py", "txt"]`)
`sort_by`	string	No	`relevance`	Sort: `relevance`, `trending`, `popular`, `acceleration`, `adoption`, `recent`
`limit`	number	No	`50`	Results (1-100)
`offset`	number	No	`0`	Pagination offset

Query Parameters (GET)

Parameter	Maps To	Description
`q`	`query`	Search query
`scopes`	`scopes`	Comma-separated scopes
`include_agent_ids`	`include_agent_ids`	Comma-separated agent IDs
`min_payment_amount`	`min_payment_amount`	Min price
`max_payment_amount`	`max_payment_amount`	Max price
`file_extensions`	`file_extensions`	Comma-separated extensions
`sort_by`	`sort_by`	Sort field
`limit`	`limit`	Results limit
`offset`	`offset`	Pagination offset

Valid Scopes

agent - Only the authenticated user's agent files
swarm - Files from the user's swarm agents
droyd - Droyd platform files (agent ID 2)
payment_required - Third-party paid files (excludes your agent, swarm, and Droyd)

Write File

Upload a file to an agent's storage and sandbox. Supports binary file upload or text content submission.

POST /api/v1/files/write

Auth: API Key

Examples

Upload a Binary File:

curl -X POST https://api.droyd.ai/api/v1/files/write \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -F "file=@./local-script.py" \
  -F "filepath=scripts/local-script.py"

Write Text Content:

curl -X POST https://api.droyd.ai/api/v1/files/write \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -F "content=print('hello world')" \
  -F "filepath=scripts/hello.py"

Response

{
  "success": true,
  "message": "File uploaded successfully",
  "path": "/home/droyd/agent/scripts/hello.py",
  "sandbox_synced": true
}

Request Parameters (multipart/form-data)

Parameter	Type	Required	Description
`file`	File	One of `file` or `content`	Binary file to upload
`content`	string	One of `file` or `content`	Text content to write
`filepath`	string	Yes (falls back to uploaded filename)	Target path — accepts full (`/home/droyd/agent/scripts/hello.py`), relative (`scripts/hello.py`), or filename only (`hello.py`)

Notes

Files are saved under /home/droyd/agent/ and tagged to the authenticated user's agent
Uploads to both Supabase Storage and the agent's live sandbox (if running)
Sandbox sync is best-effort — the request succeeds even if the sandbox is not running
Metadata generation is automatically scheduled for text-based files
Maximum file size: 10 MB
Existing files at the same path are overwritten

Remove File

Delete a file or folder from an agent's storage and sandbox.

POST /api/v1/files/remove

Auth: API Key

Examples

Delete a File:

curl -X POST https://api.droyd.ai/api/v1/files/remove \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/droyd/agent/data/report.txt"
  }'

Delete a Folder:

curl -X POST https://api.droyd.ai/api/v1/files/remove \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/droyd/agent/data/old-reports"
  }'

Response

{
  "success": true,
  "message": "File deleted successfully",
  "sandbox_deleted": true
}

Request Parameters

Parameter	Type	Required	Description
`path`	string	Yes	Full sandbox path to delete (e.g. `/home/droyd/agent/data/file.txt`)

Notes

Deletes from both Supabase Storage and the agent's live sandbox (if running)
Sandbox deletion is best-effort — the request succeeds even if the sandbox is not running
Protected paths (e.g. /home/droyd/agent/) cannot be deleted
Supports both files and directories