API & MCP

Platphorm Files exposes the same storage to humans, scripts, and agents. Use the REST API from any language, or connect an MCP client to drive it from an AI assistant. Both surfaces are protected by your PLATPHORM_API_KEY.

Authentication

Send your key as a Bearer token or the X-PlatPhorm-API-Key header. The browser UI uses an unlock cookie after verification.

curl

curl -s "https://files.platphormnews.com/api/v1/stats" \
  -H "X-PlatPhorm-API-Key: $PLATPHORM_API_KEY"

Trace Headers

Every route accepts W3C traceparent and emits a child span with Platphorm request headers. Safe Vercel metadata is exposed only as bounded response headers; raw IPs, cookies, auth headers, and bodies are not emitted.

headers

traceparent: 00-<trace-id>-<span-id>-01
X-PlatPhorm-Trace-Id: <trace-id>
X-PlatPhorm-Span-Id: <span-id>
X-PlatPhorm-Parent-Span-Id: <incoming-span-id>
X-PlatPhorm-Request-Id: <request-id>

REST API

GET/api/v1/list?prefix=docs/

List folders and files at a prefix. Omit prefix for the root.

GET/api/v1/list?search=report&prefix=docs/

Search files by substring on their path, optionally scoped to a prefix.

POST/api/v1/upload

Upload a file with SHA-256 hashing, duplicate blocking, and history. Send multipart/form-data or raw body with `?path=`.

POST/api/v1/ingest-url

Fetch an allowlisted URL and store it as a hashed file with SSRF protections.

POST/api/v1/bulk-ingest

Bounded URL batch ingest. Maximum 25 URLs per request with per-item results.

POST/api/v1/folder

Create an empty folder. JSON body: { path: 'projects/alpha/' }.

POST/api/v1/move

Move or rename a file. JSON body: { from, to }.

DELETE/api/v1/delete?path=notes/todo.md

Delete a file. Use ?folder= to recursively delete a folder.

GET/api/v1/stats

Totals: file count, folder count, and bytes stored.

GET/api/v1/metadata?path=img/logo.png

Read indexed metadata: hash, kind, source, version, and duplicate state.

GET/api/v1/history?path=img/logo.png

Read recorded change history for a file path.

GET/api/files/raw?path=img/logo.png

Stream raw file bytes. Append &download=1 to force download.

Upload a file

curl

curl -s -X POST "https://files.platphormnews.com/api/v1/upload" \
  -H "Authorization: Bearer $PLATPHORM_API_KEY" \
  -F "prefix=docs/2026/" \
  -F "file=@./report.pdf"

Import from URL

curl

curl -s -X POST "https://files.platphormnews.com/api/v1/ingest-url" \
  -H "Authorization: Bearer $PLATPHORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://docs.platphormnews.com/example.pdf","prefix":"imports/"}'

List & search (JSON via fetch)

javascript

const res = await fetch("https://files.platphormnews.com/api/v1/list?prefix=docs/", {
  headers: { Authorization: `Bearer ${process.env.PLATPHORM_API_KEY}` },
})
const { folders, files } = await res.json()

MCP Server

Connect any Model Context Protocol client (Claude Desktop, Cursor, the AI SDK, or your own agent) to the endpoint below. Tools are auth-gated with the same key.

MCP endpoint

https://files.platphormnews.com/api/mcp

Claude Desktop / Cursor config

mcp.json

{
  "mcpServers": {
    "platphorm-files": {
      "url": "https://files.platphormnews.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PLATPHORM_API_KEY"
      }
    }
  }
}

Available tools

list_files

List folders and files at a prefix.

search_files

Search all files by substring on their path.

read_file

Read a text file's contents as a string.

write_file

Create or overwrite a text file.

ingest_url

Fetch an allowlisted URL and store it as a hashed file.

file_metadata

Read indexed metadata for a file.

file_history

Read change history for a file.

create_folder

Create an empty folder.

delete_file

Delete a single file.

delete_folder

Recursively delete a folder.

move_file

Move or rename a file.

storage_stats

Get store totals and a sample of paths.