⚙️ API Documentation

The Openfiles API enables you to programmatically manage your files and folders on TON Storage, facilitating integration with your applications and workflows.

🛠️ API Base Information

• Base URL: https://app.openfiles.xyz
• Dashboard: Openfiles Dashboard (opens in a new tab)
• Python SDK: Python SDK Documentation

🔑 Authentication

The API uses Bearer token authentication. You must include your API token in the request headers:

Authorization: Bearer YOUR_API_TOKEN

Obtain your API token from the Openfiles Dashboard (opens in a new tab).

⬆️ Upload Endpoint

Upload File

• Endpoint: POST /api/files/upload
• Description: Upload a single file to TON Storage.

Request: Multipart Form Data

• file: Binary file data
• description: Description of the file

Response:

{
    "bag_id": "string"
}

Upload Folder

• Endpoint: POST /api/folders/upload
• Description: Upload an entire folder (zipped) to TON Storage as a single entity.

Request: Multipart Form Data

• file: Binary data of zipped folder
• description: Description of the folder

Response:

{
    "bag_id": "string"
}

Add Bag by ID

• Endpoint: POST /api/bag/add_by_id
• Description: Import an existing bag from TON Storage using its ID.

Request: Form Data

• bag_id: The unique bag ID in TON Storage

Response:

{
    "message": "Bag added"
}

⬇️ Download Endpoint

Download File or Folder

• Endpoint: GET /api/bag/download/{bag_id}
• Description: Download a file or folder using its unique bag ID.

Parameters:

• bag_id: ID of the file or folder to download

Response:

• Binary file content or zipped folder data.

❌ Delete Endpoint

Delete File or Folder

• Endpoint: DELETE /api/bag
• Description: Delete a file or folder from TON Storage.

Request: JSON or Form Data

• bag_id: ID of the file or folder to delete

Response:

{
    "success": true
}

📁 List User Files

Get User Files List

• Endpoint: GET /api/user/files_list
• Description: Retrieve a list of all files you've uploaded.

Response:

[
    {
        "filename": "example.txt",
        "size": 1024,
        "uploaded_at": 1672531200.0,
        "description": "My text file",
        "bag_id": "bag123"
    }
]

👤 User Information

Get User Info

• Endpoint: GET /api/user
• Description: Retrieve your account's storage usage and total capacity.

Response:

{
    "uid": "user123",
    "space_left": 500000000.0,
    "capacity": 1000000000.0
}

🚨 Error Handling

API errors return a consistent format:

{
    "detail": [
        {
            "loc": ["field"],
            "msg": "Error message explaining the issue",
            "type": "validation_error"
        }
    ]
}

Common HTTP Status Codes:

⏳ Rate Limits & Best Practices

Currently, the Openfiles API does not enforce any rate limits during the beta period. However, we plan to introduce rate limits to maintain service stability and fairness among users. We recommend designing your integrations to:

• Make API calls efficiently, avoiding unnecessary requests.
• Implement retry mechanisms with exponential backoff for robustness.
• Monitor your API usage regularly to ensure compliance with future rate limits.

We'll announce and document any changes regarding rate limits clearly before implementation.

For further questions or feedback, please reach out through our support channels.

Happy integrating! 🚀