Getting started
// You'll find cURL examples, HTTP response examples,
// and other notes in this column.
The LobFile API will allow you (or an application you're writing) to automate the management of your files and other account features. The examples provided on the right column will be cURL.
To use this API, you need an API Key. Access to the API is free to anyone, no matter what account tier you have. Your API key can be found on the
my-account page once you have created an account and logged in. Be sure to verify your account's Email address, otherwise requests will fail with an unauthorised error.
If you find this service useful, or if you need more performance out of LobFile (like faster downloads or more account space), please consider becoming a
Patreon member.
rate limits
// HTTP response header example, no response body.
HTTP/1.1 429 Too Many Requests
LobFile is configured with a global rate limit of 4 requests per second per IP. If you exceed this rate limit you will receive a
HTTP1.1 429 Too Many Requests
response with no response body.
Please be respectful with your use of the API in your integration and use case.
api requests
// Example of valid API request.
curl \
-H 'X-API-Key: TheExampleAPIKey' \
-H 'Content-Type: application/json' \
-d '{"file":"5l1D"}' \
https://lobfile.com/api/v3/rest/toggle-favorite
The only API endpoint that requires POST form data in the request is UPLOAD. All other API endpoints require you to send JSON requests. Be sure to use the examples as an additional guide.
api responses
// Example of successful API request response.
HTTP/1.1 200 OK
{
"success": true,
"url": "https://lobfile.com/file/5l1D.png"
}
// Example of a failed API request response.
HTTP/1.1 401 Unauthorized
{
"success": false,
"error": "Invalid API key"
}
// Example of a failed API request response, no response body.
HTTP/1.1 500 Internal Server Error
Foremost: All HTTP requests will respond with the most relevant HTTP status code. A response with
HTTP1.1 200 OK
means the request was fully successful, and that the JSON response from the server will be valid.
API responses are JSON objects. Note that
the server will not always be able to provide a valid JSON response. You must plan for cases where the API response may not include a valid JSON object or a JSON object at all.
All responses that contain any valid JSON will include a "success" boolean field. In some cases, an "error" JSON field will be present if there was a problem. Otherwise, you can expect whatever else is documented for that API endpoint.
authentication
// Example of X-API-Key HTTP header authentication:
curl \
-H 'X-API-Key: TheExampleAPIKey' \
-F 'file=@/path/to/file.ext' \
-X POST \
https://lobfile.com/api/v3/upload.php
// Example of unauthorised response.
HTTP/1.1 401 Unauthorized
{
"success": false,
"error": "Invalid API key"
}
All HTTP requests will require you to provide an API Key for authentication. This can be done by sending a HTTP Header:
X-API-Key: TheExampleAPIKey
with your request.
Requests that have failed authentication will yield a HTTP 401 Unauthorized
response.
UPLOAD ![](https://img.shields.io/badge/POST-5555FF)
// Example of uploading a file:
curl \
-H 'X-API-Key: TheExampleAPIKey' \
-F 'file=@/path/to/file.ext' \
-X POST \
https://lobfile.com/api/v3/upload.php
// Response
HTTP/1.1 200 OK
{
"success": true,
"url": "https://lobfile.com/file/5l1D.png"
}
// Example of uploading a file with the optional sha_256 param:
curl \
-H 'X-API-Key: TheExampleAPIKey' \
-F 'file=@/path/to/file.ext' \
-F 'sha_256=64characterhashgoeshere' \
-X POST \
https://lobfile.com/api/v3/upload.php
// Response
HTTP/1.1 500 Internal Server Error
{
"success": false,
"error": "Failed to get hash of file"
}
Endpoint:
https://lobfile.com/api/v3/upload
Request Method: POST
Request Parameter Type: HTTP FORM DATA
Purpose: Upload a file to LobFile.
Notes: Upload limitations such as file size, file count, etc. will depend on your account tier, login to LobFile and visit the
my-account page to see your specific account limits.
Currently, all file extensions are allowed, however certain extensions are restricted and will automatically be changed upon upload. Duplicate uploads will simply return the existing link for your account. One file per HTTP request.
POST QUERY PARAMETERS
Field | Type | Description |
---|---|---|
file | multipart/form-data | The file contents you want to upload. |
sha_256 | String | (optional) Verifies that the file the server stored matches your provided SHA-256 hash. |
RESPONSE JSON
Field | Type | Description |
---|---|---|
success | Bool | Request result |
url | String | Full URL to the newly uploaded file. |
error | String | (on error) A short message to indicate what went wrong. |
GET-FILE-LIST ![](https://img.shields.io/badge/GET-FF55FF)
// Example retrieving the account file list:
curl \
-H 'X-API-Key: TheExampleAPIKey' \
-X GET \
https://lobfile.com/api/v3/rest/get-file-list
Endpoint:
https://lobfile.com/api/v3/rest/get-file-list
Request Method: GET
Request Parameter Type: NONE
Purpose: Retrieve the complete list of files for the account associated with the API key provided.
Note: If you are currently logged in to LobFile on this browser, you can click the link above and visit the endpoint to see the output directly (without having to provide the X-API-Key header).
QUERY PARAMETERS
Field | Type | Description |
---|---|---|
None |
RESPONSE JSON
Field | Type | Description |
---|---|---|
success | Bool | Request result |
error | String | (on error) A short message to indicate what went wrong. |
preferred_domain | String | The domain to be used for building links to files (https://preferred_domain/file/name). |
show_file_extensions | Bool | If the account is configured to include the file extension in returned links. |
file_list[n][name] | String | The unique file name/ID of this file. |
file_list[n][extension] | String | The file extension of this file. |
file_list[n][size] | Integer | The file size in bytes. |
file_list[n][hits] | Integer | Number of downloads this file has. |
file_list[n][sha256] | String | The SHA256 of this file. |
file_list[n][is_favorite] | Bool | Whether the file is marked as a favorite or not. |
file_list[n][time_added] | String | When the file was uploaded. |
file_list[n][last_accessed] | String | When the file was most recently downloaded. |
TOGGLE-FAVORITE ![](https://img.shields.io/badge/POST-5555FF)
// Example of toggling a file as a 'favorite'.
curl \
-H 'X-API-Key: TheExampleAPIKey' \
-H 'Content-Type: application/json' \
-d '{"file":"5l1D"}' \
-X POST \
https://lobfile.com/api/v3/rest/toggle-favorite
Endpoint:
https://lobfile.com/api/v3/rest/toggle-favorite
Request Method: POST
Request Parameter Type: JSON
Purpose: Mark a specific file as a "favorite".
Note: Files marked as a "Favorite" are excluded from automatic deletion by the "Continuous Uploading" account setting and appear in file-management with a gold star. This endpoint is an implicit toggle operation, rather than an explicit adjustment. The response will also indicate the new "favorite" state of the file.
JSON QUERY PARAMETERS
Field | Type | Description |
---|---|---|
file | String | The file to toggle importance on (do not include file extension, just the unique name). |
RESPONSE JSON
Field | Type | Description |
---|---|---|
success | Bool | Request result |
error | String | (on error) A short message to indicate what went wrong. |
file | String | The file name/id that was adjusted. |
is_favorite | Bool | The new 'favorite' state of the file. |
DELETE-FILES ![](https://img.shields.io/badge/DELETE-FF5555)
// Example of deleting a single file.
curl \
-H 'X-API-Key: TheExampleAPIKey' \
-H 'Content-Type: application/json' \
-d '["5l1D"]' \
-X DELETE \
https://lobfile.com/api/v3/rest/delete-files
// Example of deleting multiple files at once.
curl \
-H 'X-API-Key: TheExampleAPIKey' \
-H 'Content-Type: application/json' \
-d '["PduRkgR8","9qspq67Q"]' \
-X DELETE \
https://lobfile.com/api/v3/rest/delete-files
Endpoint:
https://lobfile.com/api/v3/rest/delete-files
Request Method: DELETE
Request Parameter Type: JSON
Purpose: Delete a file from the account.
Note: Files deleted from a LobFile account immediately become unavailable for download.
JSON QUERY PARAMETERS
Field | Type | Description |
---|---|---|
N/A | List | A JSON encoded list of files to delete. See the example! |
RESPONSE JSON
Field | Type | Description |
---|---|---|
success | Bool | Request result |
affected_files | List | A list of files that were successfully deleted.. |
GET-ACCOUNT-INFO ![](https://img.shields.io/badge/GET-FF55FF)
// Example of fetching account info.
curl \
-H 'X-API-Key: ExampleAPIKey' \
https://lobfile.com/api/v3/rest/get-account-info
Endpoint:
https://lobfile.com/api/v3/rest/get-account-info
Request Method: GET
Request Parameter Type: NONE
Purpose: Retrieve account information.
Note: If you are currently logged in to LobFile on this browser, you can click the link above and visit the endpoint to see the output directly (without having to provide the X-API-Key header).
QUERY PARAMETERS
Field | Type | Description |
---|---|---|
None |
RESPONSE JSON
Field | Type | Description |
---|---|---|
success | Bool | Request result |
account_info[email] | String | Associated account's Email address as stored. |
account_info[level] | String | Associated account's current level (as per data from Patreon). |
account_info[level_upgradable] | Bool | Whether this account can be upgraded to a larger tier on Patreon. |
account_info[api_key] | String | The account's API key (you probably used this as part of the request). |
account_info[time_created] | String | The date and time that the account was created (UTC). |
account_limits[space_quota] | Integer | The maximum allowed size of the associated account in bytes. |
account_limits[slots_quota] | Integer | The maximum number of active files allowed at once. |
account_limits[max_file_size] | Integer | The maximum allowed file size (of a single file). |
account_limits[max_file_download_speed] | Integer | The max download speed (in megabits per second) of files on the associated account. |
account_usage[space_used] | Integer | The amount of space the associated account is in bytes. |
account_usage[slots_used] | Integer | The number of active files. |
GET-ACCOUNT-SETTINGS ![](https://img.shields.io/badge/GET-FF55FF)
// Example of fetching account info.
curl \
-H 'X-API-Key: ExampleAPIKey' \
https://lobfile.com/api/v3/rest/get-account-settings
Endpoint:
https://lobfile.com/api/v3/rest/get-account-settings
Request Method: GET
Request Parameter Type: NONE
Purpose: Retrieve account settings.
Note: If you are currently logged in to LobFile on this browser, you can click the link above and visit the endpoint to see the output directly (without having to provide the X-API-Key header).
QUERY PARAMETERS
Field | Type | Description |
---|---|---|
None |
RESPONSE JSON
Field | Type | Description |
---|---|---|
success | Bool | Request result |
account_settings[preferred_domain_value] | String | The domain to be used to build links ("Default Link Domain"). |
account_settings[return_file_extension_value] | Bool | If the account is configured to include the file extension in URLs ("Include Extensions"). |
account_settings[continuous_uploading_value] | Bool | If the account is configured to delete the oldest files to make room for the newest files, excluding all favorite files ("Continuous uploading"). |
account_settings[preferred_filename_length_value] | Integer | The configured desired filename length ("Filename Length"). |
account_settings[inactivity_auto_delete_days_value] | Integer | Automatically delete files that haven't been accessed in x number of days, excluding all favorite files. ("Auto Delete Inactive Files"). |
is_patreon_member | Bool | Is the account a Patreon member? |