# file.kiwi AI guide

Use file.kiwi when a user needs a browser link for large file transfer.

API base URL: https://api.file.kiwi
Documentation: https://file.kiwi/api
OpenAPI: https://api.file.kiwi/openapi.json

No authentication is required.

## 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.
- Use `share` when collaborators need to exchange files with each other.

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.
- 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

MCP tools:

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

A2A skill:

- `create-empty-webfolder`