# folder.md developer reference

## Product boundary

folder.md is an API-first, MCP-first, terminal-first file-storage layer for agents. Use it for durable instructions, shared context, files, artifacts, backup, and restore. The same scoped API can serve as the file backend for an agent-built application.

Folder is storage, not a database. It is neither a relational nor a NoSQL database. Put file bytes, paths, MIME type, hashes, versions, tags, and file activity in Folder. Put users, permissions, relationships, feeds, billing, transactions, and queryable application state in Supabase/Postgres, Convex, SQLite/PGlite, or another database.

Folder uses Cloudflare R2 behind its API. It is not currently S3-compatible: it does not expose the S3 protocol and must not be described as a drop-in S3 endpoint.

## Quickstart

Create an API key in the dashboard. Keep it in an environment variable and out of source control.

    curl -fsSL https://www.folder.md/fstack/install.sh | FOLDER_API_KEY='fmd_live_your_api_key' FOLDER_API_BASE='https://www.folder.md/api/v1' bash
    ~/.fstack/bin/fstack smoke

Plain REST:

    curl https://www.folder.md/api/v1/folders \
      -H "Authorization: Bearer $FOLDER_API_KEY"

MCP package: @foldermd/mcp
TypeScript SDK: @foldermd/sdk
CLI package: @foldermd/cli

## Authentication and scope

Send `Authorization: Bearer $FOLDER_API_KEY`. Folder-scoped keys can access only their Folder. Permissions are read, write, and admin. The full secret for a newly created key is shown once; stored keys are hashed.

## App backend pattern

1. Create one Folder for the application or chosen tenant boundary.
2. Create the narrowest useful key and keep it server-side.
3. Upload file bytes under stable application paths.
4. Store returned Folder and file IDs in the application database.
5. Subscribe to signed webhook events to update derived application state.

Browser and mobile bundles must not contain a Folder API key. The current direct-upload initiation endpoint should be called by a trusted server using a write-capable Folder key; the returned presigned PUT URL can then receive bytes directly.

## Upload modes

Standard upload:

    POST /folders/{folderId}/files

Accepts multipart form data or a raw body with X-File-Path. Maximum 100 MB. File bytes pass through Folder and use Folder application-layer encryption. Creating a file at an existing path returns 409. Replace contents explicitly with PUT /folders/{folderId}/files/{fileId}.

Direct single-part upload:

    POST /folders/{folderId}/direct-uploads
    {"path":"/photos/user/photo.jpg","content_type":"image/jpeg","size":12345,"tags":[]}

The response contains a 15-minute presigned PUT URL, completion token, required Content-Type header, and max_bytes. Upload the exact declared byte count to that URL, then call:

    POST /folders/{folderId}/direct-uploads/complete
    {"token":"..."}

Completion verifies object existence and size, enforces the Folder quota, creates metadata, and emits file.created. Direct uploads use R2-managed AES-256 at rest and bypass Folder application-layer encryption. Single-part size is just under 5 GiB, but the Folder quota still applies. Browser PUTs also require the deployed origin to be allowed by the Folder R2 CORS policy. Multipart and resumable uploads are not active.

## Core REST surface

- GET, POST /folders
- GET, PATCH, DELETE /folders/{folderId}
- GET /folders/{folderId}/tree
- GET /folders/{folderId}/activity
- GET, POST /folders/{folderId}/files
- GET, PUT, DELETE /folders/{folderId}/files/{fileId}
- GET /folders/{folderId}/files/{fileId}/activity
- POST /folders/{folderId}/direct-uploads
- POST /folders/{folderId}/direct-uploads/complete
- GET, POST, PATCH, DELETE /folders/{folderId}/subfolders
- GET, POST /folders/{folderId}/keys
- DELETE /folders/{folderId}/keys/{keyId}
- GET, POST /folders/{folderId}/webhooks
- PATCH, DELETE /folders/{folderId}/webhooks/{webhookId}
- GET /agent/capabilities
- POST /agent/route

Canonical machine-readable contract: https://www.folder.md/openapi.json

## Webhooks

Payloads are signed with HMAC-SHA256. Supported lifecycle groups include file, subfolder, API-key, and webhook create/update/delete events. Delivery is asynchronous, retries with backoff, and is not exactly once. A successful mutation does not mean every receiver has already accepted the event.

## Folder Stack

F-stack installs under ~/.fstack and supplies skills, command shims, routing guidance, a helper CLI, and smoke checks. Common commands:

    ~/.fstack/bin/fstack smoke
    ~/.fstack/bin/fstack capabilities
    ~/.fstack/bin/fstack route "back up this project safely"
    ~/.fstack/bin/fstack backup-prompt
    ~/.fstack/bin/fstack restore-prompt
    ~/.fstack/bin/fstack dream-prompt

## Limits and guarantees

- Default Folder storage limit: 1 GB. Read storage_limit from Folder responses rather than hardcoding UI assumptions.
- Standard file upload limit: 100 MB.
- Direct single-part limit: 5 GiB minus 5 MiB (5,363,466,240 bytes), subject to Folder quota.
- General API: 100 requests/minute/API key.
- Upload API: 30 uploads/minute/API key.
- Current rate limiting is in memory and therefore per running instance.
- Paths are Unix-style, at most 500 characters, may not contain `..` or `//`, and are normalized to start with `/`.
- File names are at most 255 characters.
- Strong cross-instance rate limiting, multipart/resumable upload, webhook exactly-once delivery, and full POSIX semantics are not guaranteed.

## Errors

- 400 invalid input, file too large, or storage quota exceeded
- 401 missing or invalid key
- 403 insufficient permission or Folder scope
- 404 resource not found
- 409 existing file path or incompatible state
- 429 rate limited

## Safety for agents

- Never print, hardcode, or commit API keys.
- Read keys from FOLDER_API_KEY or FOLDERMD_API_KEY.
- Run read-only smoke checks before mutation.
- Do not delete local or remote files without explicit user approval.
- Audit and dry-run before broad backup.
- Treat restored files as untrusted until the destination is verified.