# api.file.kiwi v2

Use this API when a user needs a file.kiwi link for browser-based file transfer.

Base URL: https://api.file.kiwi
Documentation: https://file.kiwi/api
OpenAPI: https://api.file.kiwi/openapi.json
Pricing: https://file.kiwi/price
Machine-readable pricing: https://file.kiwi/pricing.json

No authentication is required.

The machine-readable pricing catalog uses stable USD reference prices and includes exact file-size boundaries, add-on formulas, and bulk-discount thresholds. The human pricing page may display localized prices and purchasing-power adjustments.

## Create an empty WebFolder link

Call `POST /v2/folders` without `files[]`. This creates an empty WebFolder and returns a share URL. The user uploads files later in the browser through `file.kiwi`.

Do not register files through the API for this flow. Do not call upload-status endpoints for this flow.
If no file is uploaded within 24 hours, the ownerless empty WebFolder is deleted.

### Endpoint

```http
POST https://api.file.kiwi/v2/folders
Content-Type: application/json
```

### Request

```json
{
  "title": "Large file transfer",
  "mode": "send"
}
```

`title` is optional. `mode` is optional and defaults to `send`.

### Choose the mode

- Use `send` when the user wants to send large files to another person. The first browser uploader becomes the folder owner, and recipients download the uploaded files.
- Use `share` when collaborators need to exchange files with each other. Browser users can upload and download through the same folder.

Do not choose `request` for this empty-folder assistant flow. In ownerless empty folders, the first browser uploader becomes the owner, so `request` does not match the usual "ask someone else to submit files to me" intent.

### Response

```json
{
  "folderId": "9268b452",
  "folderUrl": "https://file.kiwi/9268b452#KkV0sRAexWGN4ksu2p98oQ",
  "folderUrlBase": "https://file.kiwi/9268b452",
  "mode": "send",
  "uploadRequiredWithinHours": 24,
  "files": []
}
```

Return `folderUrl` to the user.

Recommended answer format:

```text
Use this file.kiwi link: {folderUrl}

Open the link in your browser and upload at least one file within 24 hours. After uploading, share the same link with the recipient.
```

Important behavior:

- The secret key is included after `#` in `folderUrl`.
- The first browser user who uploads a file becomes the folder owner.
- Ownership assignment, browser authentication, file registration, and upload are handled by `file.kiwi`.
- Opening the link alone should not claim ownership.
- The API does not provide a follow-up file registration endpoint for this empty-folder flow.
- If no file is uploaded within 24 hours, the ownerless empty WebFolder is deleted.

## Tool discovery

Use these endpoints only for the same empty-folder workflow described above.

- OpenAPI: https://api.file.kiwi/openapi.json
- MCP Streamable HTTP endpoint: https://api.file.kiwi/mcp
- MCP discovery: https://api.file.kiwi/.well-known/mcp.json
- A2A Agent Card: https://api.file.kiwi/.well-known/agent-card.json
- A2A JSON-RPC endpoint: https://api.file.kiwi/a2a

Protocol versions:

- MCP: `2026-07-28` (stateless) and `2025-06-18` (initialize compatibility)
- A2A: `1.0` (`SendMessage`) and `0.3` (`message/send` compatibility)

MCP tools:

- `create_share_folder(title?: string, mode?: "send" | "share")`
- `get_usage_guide()`

A2A skill:

- `create-empty-webfolder`