Drive API Reference: Upload, Download, and Manage Files

Scout Drive exposes a REST API for all file and folder operations. Every endpoint requires authentication and returns consistent JSON responses. This reference covers each endpoint in full — parameters, response shapes, curl examples, and SDK equivalents — so you can integrate Drive into any application or automate file management in your agents and workflows.

Authentication

All Drive API endpoints require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can generate and manage API keys under Settings → API Keys in the Scout dashboard.

Base URL

https://api.scoutos.com

Rate Limits

Endpoint	Limit
`POST /drive/upload`	100 requests per minute
`GET /drive/download`	500 requests per minute
`GET /drive/list`	300 requests per minute
`POST /drive/folders`	100 requests per minute
`DELETE /drive/folders`	50 requests per minute

When you exceed a rate limit, the API returns 429 Too Many Requests. Check the Retry-After response header for the number of seconds to wait before retrying.

Endpoint Summary

Action	Method	Endpoint
Upload files	`POST`	`/drive/upload`
Download a file	`GET`	`/drive/download`
List folder contents	`GET`	`/drive/list`
Create a folder	`POST`	`/drive/folders`
Delete a folder	`DELETE`	`/drive/folders`

POST /drive/upload

Upload one or more files to Drive. Each file can be placed at a specific path using the metadata array.

Request

POST https://api.scoutos.com/drive/upload
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY

Parameters

files

file[]

required

One or more files sent as multipart form data fields. Each file corresponds by index to an entry in the metadata array.

metadata

JSON string

A JSON array of metadata objects, one per file, controlling where each file is stored. If omitted, files are stored at the root using their original filenames.

Metadata Object Fields

path

string

Fully qualified destination path, for example /reports/2024/q1.pdf. Takes the highest priority when resolving the file location.

folder

string

Destination folder path, for example /reports/2024. Combined with name if both are provided.

name

string

Destination filename, for example q1-report.pdf. Combined with folder if provided, otherwise stored at the root.

Path Resolution Priority

For each file at index i, the destination path is resolved in this order:

Priority	Condition	Result
1	`path` is set	Use `path` as the fully qualified location
2	`folder` + `name` both set	`{folder}/{name}`
3	`folder` only	`{folder}/{original_filename}`
4	`name` only	`/{name}` (root)
5	Neither set	`/{original_filename}` (root)

Response

200 OK

{
  "data": [
    {
      "id": "file_abc123",
      "name": "q1-report.pdf",
      "path": "/reports/2024/q1-report.pdf",
      "url": "https://cdn.scoutos.com/files/file_abc123",
      "size": 204800,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

data[].id

string

Unique identifier for the uploaded file.

data[].name

string

Stored filename.

data[].path

string

Full path where the file was stored in Drive.

data[].url

string

Direct URL to access the file content.

data[].size

integer

File size in bytes.

data[].created_at

string

ISO 8601 timestamp of when the file was created.

Examples

# Simple upload — stored at root with original filename
curl -X POST https://api.scoutos.com/drive/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@report.pdf"

# Upload to a specific folder
curl -X POST https://api.scoutos.com/drive/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@report.pdf" \
  -F 'metadata=[{"folder": "/reports/2024"}]'

# Upload to a specific path
curl -X POST https://api.scoutos.com/drive/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@report.pdf" \
  -F 'metadata=[{"path": "/reports/2024/q1-summary.pdf"}]'

# Upload multiple files to different locations
curl -X POST https://api.scoutos.com/drive/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@report.pdf" \
  -F "files=@data.csv" \
  -F 'metadata=[{"path": "/reports/2024/q1-report.pdf"}, {"folder": "/data/exports", "name": "sales-data.csv"}]'

GET /drive/download

Download a single file from Drive. Returns the raw file content as a binary stream.

Request

GET https://api.scoutos.com/drive/download
Authorization: Bearer YOUR_API_KEY

Query Parameters

path

string

Fully qualified file path, for example /reports/report.pdf. Use this or name + folder — not both.

name

string

Filename to retrieve, for example report.pdf. Must be used together with folder.

folder

string

Folder to search within, for example /reports. Must be used together with name.

Provide either path alone, or both name and folder together. The request returns 400 Bad Request if neither combination is supplied.

Response

200 OK — Returns the file content as a binary stream. Response headers include:

Content-Type: application/pdf
Content-Disposition: attachment; filename="report.pdf"

Examples

# Download by full path
curl -X GET "https://api.scoutos.com/drive/download?path=/reports/2024/q1-report.pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output q1-report.pdf

# Download by folder + name
curl -X GET "https://api.scoutos.com/drive/download?name=q1-report.pdf&folder=/reports/2024" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output q1-report.pdf

GET /drive/list

List the files and subfolders within a Drive folder. Defaults to the root folder if no folder is specified.

Request

GET https://api.scoutos.com/drive/list
Authorization: Bearer YOUR_API_KEY

Query Parameters

folder

string

default:"/"

Folder path to list, for example /reports. Defaults to root (/) if omitted.

recursive

boolean

default:"false"

When true, returns all nested files and folders at every depth within the target folder.

Response

200 OK

{
  "data": {
    "folder": "/reports",
    "files": [
      {
        "id": "file_abc123",
        "name": "q1-report.pdf",
        "path": "/reports/q1-report.pdf",
        "size": 102400,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "folders": [
      {
        "id": "folder_xyz789",
        "name": "2024",
        "path": "/reports/2024"
      }
    ]
  }
}

data.folder

string

The folder path that was listed.

data.files

array

Files directly inside the folder. Includes all nested files when recursive: true.

data.files[].id

string

Unique file identifier.

data.files[].name

string

Filename.

data.files[].path

string

Full path to the file in Drive.

data.files[].size

integer

File size in bytes.

data.files[].created_at

string

ISO 8601 creation timestamp.

data.folders

array

Immediate subfolders within the listed folder.

data.folders[].id

string

Unique folder identifier.

data.folders[].name

string

Folder name.

data.folders[].path

string

Full folder path in Drive.

Examples

# List root folder
curl -X GET "https://api.scoutos.com/drive/list" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List a specific folder
curl -X GET "https://api.scoutos.com/drive/list?folder=/reports" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List recursively
curl -X GET "https://api.scoutos.com/drive/list?folder=/reports&recursive=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /drive/folders

Create a new folder in Drive. Intermediate parent folders are created automatically if they do not already exist.

Request

POST https://api.scoutos.com/drive/folders
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body

path

string

required

Full path for the new folder, for example /reports/2024/q1. Intermediate folders are created automatically.

Response

200 OK

{
  "data": {
    "id": "folder_abc123",
    "path": "/reports/2024",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

data.id

string

Unique identifier for the created folder.

data.path

string

Full path of the created folder.

data.created_at

string

ISO 8601 creation timestamp.

Examples

# Create a folder
curl -X POST https://api.scoutos.com/drive/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/reports/2024"}'

# Create nested folders — intermediate paths are created automatically
curl -X POST https://api.scoutos.com/drive/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/projects/research/analysis"}'

DELETE /drive/folders

Delete a folder from Drive. By default, deletion fails if the folder contains files or subfolders. Set recursive: true to force deletion of all contents.

Deletion is permanent. Files and folders removed with this endpoint cannot be recovered. Use the archive pattern — move files to /archive/... — if you want to preserve history.

Request

DELETE https://api.scoutos.com/drive/folders
Authorization: Bearer YOUR_API_KEY

Query Parameters

path

string

required

Full path of the folder to delete, for example /reports/archived.

recursive

boolean

default:"false"

When true, deletes all files and subfolders within the target folder. When false and the folder is non-empty, the request returns 409 Conflict.

Response

200 OK

{
  "data": {
    "deleted": true,
    "path": "/reports/archived",
    "files_deleted": 5
  }
}

data.deleted

boolean

true if deletion succeeded.

data.path

string

Path of the deleted folder.

data.files_deleted

integer

Number of files deleted, including files in subfolders when recursive: true.

Examples

# Delete an empty folder
curl -X DELETE "https://api.scoutos.com/drive/folders?path=/reports/archived" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete a folder and all its contents
curl -X DELETE "https://api.scoutos.com/drive/folders?path=/reports/old&recursive=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

All Drive API errors follow a consistent JSON structure:

{
  "error": {
    "code": "not_found",
    "message": "No file found at path /reports/missing.pdf"
  }
}

HTTP Status Codes

Status	Code	Description
`200`	—	Request succeeded
`400`	`bad_request`	Malformed request — missing required fields or invalid JSON
`401`	`unauthorized`	Missing or invalid API key
`404`	`not_found`	The specified file or folder does not exist
`409`	`conflict`	Attempted to delete a non-empty folder without `recursive: true`
`422`	`validation_error`	Request parameters failed validation; `message` describes the invalid parameter
`429`	`rate_limited`	Too many requests; check `Retry-After` header
`500`	`internal_error`	Unexpected server error; contact Scout support if it persists

Common Error Scenarios

Missing required parameter (422)

{
  "error": {
    "code": "validation_error",
    "message": "Parameter 'path' is required for folder deletion"
  }
}

File not found (404)

{
  "error": {
    "code": "not_found",
    "message": "No file found at path /reports/missing.pdf"
  }
}

Non-empty folder without recursive flag (409)

{
  "error": {
    "code": "conflict",
    "message": "Folder /reports/2024 is not empty. Set recursive=true to delete its contents."
  }
}

Rate limit exceeded (429)

{
  "error": {
    "code": "rate_limited",
    "message": "Upload rate limit exceeded. Retry after 15 seconds."
  }
}

Next Steps

Drive Overview

Learn how Drive works, common use cases, and how to give agents file access.

Databases Overview

Use Databases for structured data and semantic search across your agent’s knowledge base.

​Authentication

​Base URL

​Rate Limits

​Endpoint Summary

​POST /drive/upload

​Request

​Parameters

​Metadata Object Fields

​Path Resolution Priority

​Response

​Examples

​GET /drive/download

​Request

​Query Parameters

​Response

​Examples

​GET /drive/list

​Request

​Query Parameters

​Response

​Examples

​POST /drive/folders

​Request

​Request Body

​Response

​Examples

​DELETE /drive/folders

​Request

​Query Parameters

​Response

​Examples

​Error Handling

​HTTP Status Codes

​Common Error Scenarios

​Next Steps

Drive Overview

Databases Overview

Authentication

Base URL

Rate Limits

Endpoint Summary

POST /drive/upload

Request

Parameters

Metadata Object Fields

Path Resolution Priority

Response

Examples

GET /drive/download

Request

Query Parameters

Response

Examples

GET /drive/list

Request

Query Parameters

Response

Examples

POST /drive/folders

Request

Request Body

Response

Examples

DELETE /drive/folders

Request

Query Parameters

Response

Examples

Error Handling

HTTP Status Codes

Common Error Scenarios

Next Steps