The API is available to every registered account. Features marked Customers require a Premium, Premium Light or Premium GOLD subscription.
3 requests per second maximum. Beyond that, the API returns a 429 status code.
Repeated failing requests (401, 403, 404, 410) lead to a temporary ban of the IP address and of the account.
We display in this section common and general information.
The access to the API or to the service will be blocked to you in case of requests too frequent or abusive (repetition of requests returning an error 401,403,404,410, ...)
Requests to the API are limited to 3 per second maximum. A 429 error code will be returned in case of abuse.
Multiple incorrect or unauthorized requests result in a temporary ban on IP service and / or account
Set "pretty" to 1 in order to have a more readable JSON return.
Do not use in production for performance reasons.
The download links are of the form https://domain/?id.
The identifier consists of a sequence of 5 to 20 alphanumeric characters (0 to 9, a to z - lowercase -).
Any other URL will be rejected
Groupwares shares are not possible on the private "incoming" folder tree.
Groupwares shares do not require a password (if set) and are not subject to access restrictions
Domain list :
Domain ID
Domain
0
1fichier.com
1
alterupload.com
2
cjoint.net
3
desfichiers.com
4
dfichiers.com
5
megadl.fr
6
mesfichiers.org
7
piecejointe.net
8
pjointe.com
9
tenvoi.com
10
dl4free.com
Dates are on the french time zone (CET or CEST)
We provide you several methods of identification.
Each method will be detailed and explained on the API.
Web browser : uses a cookie issued after the establishment of a session using the couple email/password and possibly an additional security code.
This method is strongly deprecated for use in a program.
Some parts of the site accept a specific identification (email/password, basic authentication, ...)
Private API key
Reminder Your ID, passwords, API key are strictly private and confidential. The API key and password are case sensitive.
In no case, you must not communicate your identifiers.
Access restriction methods exist, use them !
Warning Some old features of the service are marked as obsolete.
Privilege the use of our API for your developments.
The web upload is synchronous. That is to say that all operations are performed during his call (unlike our FTP pool or Remote Upload).
The storage process on our Cloud is performed in real time by a subprocess, which can cause a delay when displaying links and the actual availability of files.
This depends mainly on the amount of data to be processed and the load on the servers.
Sending files is always in POST "multipart/form-data".
Requests must be made in HTTP/1.1. In other words, "Host:" is mandatory
SSL reminder The SSL encrypted upload will always be slower and use more resources than the unencrypted upload.
SSL encryption is performed in real time and necessarily leads to network and processor overhead.
Our services are provided by default in SSL.
You can disable this feature according to your needs.
The upload server can vary to distribute the load and provide you with a service of irreproachable quality.
GET https://api.1fichier.com/v1/upload/get_upload_server.cgi HTTP/1.1
url: Host name of the server (alphanumeric) id: Unique identifier of emission. Composed of 10 random alphanumeric characters.
It tracks the progress of the send asynchronously and displays the send report at the end.
POST /upload.cgi?id=UploadId HTTP/1.1
Content-Length: // (required) full size of the upload - limited to 500GB
Cookie: // (optional) Cookie identification issued by the site. Link files sent to an account.
Authorization: Basic: // (optional, not requested by the server - to force -) to link the files to an account. Password in clear
Authorization: Bearer "API Key" // Using the API Key to authenticate (IP/Country restrictions not applied)
POST parameters :
"mail" : "example@example.com" // (optional) to receive an email notification - registered users only.
"did" : 0 // (only valid if identified) Numeric identifier of the file destination folder. If invalid, the file will be deposited at the root of the account.
"user" : "example@example.com" // (only valid if unidentified) email address of the registered user receiving the files. The files will be placed in the "incoming" folder and will only be accessible by the owner of the account. The parameter can also be used for identification (coupled to the "pass" parameter)
"pass" : "password" // (optional) Account password (login "user" / "pass")
"domain" : 0 // (optional) The numerical identifier of the destination domain. Default 1fichier.com/"0" (see table)
"dpass" : "password" // (optional) Password to access files. Access to the files will be protected by password.
"mails" : "example@example.com" // (optional) Notification to your contacts, 250 characters max by email, 20 emails maximum - registered users only.
"message" : "Mon message..." // (optional) Message for notification to contacts, up to 2000 characters - registered users only.
"file[]" : ... // (required) The files to be sent (maximum 500 per upload)
// Beta: If the filename contains a path separated by slashes (/), this will be taken into account (the folders will be created if necessary). Limited to 30 different paths per upload.
GET parameter :
"id" : "UploadID" // Temporary unique identifier of issue. Composed of 10 random alphanumeric characters.
Return
Code
Meaning
Details
200
Return program OK
The program has completed successfully. If there was an error, it was handled.
The return may consist of:
Html page with a clear error message
"Internal Error": Should not occur.
302
Redirection (Location: /end.pl?xid=UploadID )
Most common return: Redirection to the program report display (download and removal links)
500
Internal Server Error
Fatal / unmanaged error
The complete upload process is limited to 4 hours.
500GB maximum per upload.
300GB maximum per file.
The upload status is deleted 2 hours after the end of the program.
We strongly discourage the use of the identification cookie for uploading: By default, any new identification on the site purges the previous sessions.
The storage process on our Cloud starts when you receive the redirection to "end.pl".
The files will probably not be available yet.
Other errors can still occur in rare cases (data corruption, virus detected, ...)
If you want to ensure the effective storage of your files, we recommend that you download them after upload, or use FTP.
cURL example (simplified)
This example must be adapted to your case / needs and contains invalid data !
By default, the program displays the result on a formatted HTML web page.
You can, however, obtain program-readable exports (CSV, JSON).
The request must be made on the sending server previously determined.
GET /end.pl?xid=UploadID HTTP/1.1
Export: 1 // (optional) displays a basic CSV export instead of a web page.
JSON: 1 // (optional) displays a formatted JSON export instead of a web page. If Json = 2, display readable output for debugging.
CSV return (complete example):
GET /end.pl?xid=1234567890 HTTP/1.1
Export: 1
HTTP/1.1 200 OK
Content-Type: text/csv
Filename;Size;Objet;Remove;DomainID;WhirlpoolChecksum
Filename : File name Size : size in bytes Objet : Unique identifier of the file (download) Remove : File removal code (not filled if the upload is linked to an account) DomaineID : Unique domain identifier WhirlpoolChecksum: CheckSum (whirlpool)
JSON return (pretty):
incoming : If the files are placed in the "incoming" folder (accessible only to the identified user) download : Complete download link filename : Filename remove : Complete removal link (not filled if the upload is linked to an account) size : File size in bytes whirlpool : Checksum (whirlpool)
Files
This feature is limited to our customers (Premium, Premium Light, Premium GOLD, Access, CDN)
When you want to download a file, a single access token is issued to you.
The access token allows limited and time-limited access to the resource to which it points.
Tokens and their characteristics (limitations, resuming, network, ...) depend on the linked offer.
Generate an access token
POST https://api.1fichier.com/v1/download/get_token.cgi HTTP/1.1
Authorization: Bearer "API Key"
url : Download link inline : (optional) 0 or 1, if "inline" option enabled. You can always add "&inline=1" to the supplied url cdn : (optional) 0 or 1, if using your CDN credits (forced if Premium / Premium Light / Premium GOLD / Access and identified server) restrict_ip : (optional - for CDN only). 0 (default): No restriction, 1: Prohibits IP changes, 2: Prohibits any sub-requests single : (optional). 0 (default) : Child requests allowed. 1: Prohibits any sub-requests pass : (optional) Access password to the file, if restricted by password. no_ssl : (optional) Disable SSL on the download link folder_id : Folder ID (if groupware sharing with hidden download link option) filename : Filename (if groupware sharing with hidden download link option) sharing_user : Email of the user who shares his resource (essential if folder_id = 0 - if the file is at the root)
JSON return (pretty):
url : URL for direct access to the requested resource (CDN Offer: can be used by your Customers to maintain full control over your data)
status : Status of the request
Reminder By default the access URL is provided in SSL.
Depending on your needs, you can access it without SSL
The access token is valid for 5 minutes.
The recovery in case of errors is allowed for 30 minutes depending on the case.
Our servers support range requests.
You can resume a failed download by restarting this step and requesting the portion of data you want.
Groupware sharing is private and does not consider passwords or access restrictions on files.
folder_id : (optional) Folder identifier. Root if unspecified or 0. -1 allow to list all files of the account sharing_user : (optional) Email of the user sharing his folder - used if folder_id = 0 / root folder
sent_before/sent_after : (optional) Allow to limit the return by date (can be used separately or not)
Warning (can be changed in case of abuses) : List all files of the account is limited to 1 request per hour.
List folders is limited to 5 000 results and 1 request per folder per 30s.
url : Not specified for groupwares with hidden links feature checksum : Checksum (whirlpool) pass : If the file is password protected acl : If the file is protected by an access list restriction (IP, country, user, customer) cdn : If the file is CDN flagged
pass : (optional) Access password to the file, if restricted by password.
Options, if it's a groupware shared folder file with the hidden download link feature : folder_id : Folder ID filename : Filename (exact/case sensitive) sharing_user : Email of the account that shares the folder (useful if root folder / folder_id=0)
JSON return (pretty):
url : Download link. Not specified if groupware share with the hidden link feature date : Upload date content_type : File type (MIME, e.g. image/jpeg) description : File description (if set - optional) pass : If the file is password protected no_ssl : The download link will be offered without SSL default inline : The server will not force the download (inline + positioning the content_type) cdn : File proposed in CDN acl : File protected by an advanced access control (detailed display if identified owner)
If identified owner : folder_id : Folder ID path : File path checksum : Checksum (whirlpool - also filled on groupware share -)
Reminder Access identification or password is required to obtain information from certain files as well as additional data (private or protected).
In case of error, you will have a code 404 (Not found)
Access will be blocked if requests are too frequent or abusive.
To protect you from infection, all files stored on our servers are regularly scanned for viruses and malwares.
We offer this option to force an immediate scan.
POST https://api.1fichier.com/v1/file/scan.cgi HTTP/1.1
Authorization: Bearer "API Key"
status : Scan status
If 'KO' and a virus was detected, the file will be removed.
message : Further information if KO. date : Date of the scan (if the information comes from our cache)
Reminder Access will be blocked if requests are too frequent or abusive.
The service is limited to files of less than 5GB.
The results are cached for 6 hours.
status : Request status removed : Removed files counter urls : List (array) of the removed filed (download links).
Warning Files are not removed. Files are moved to "Trash" folder and could be restored from the panel for 30 days.
Will not work if your account or the owner of the files has the option "Confirm Deletion of Multiple Files" enabled.
Files may have been deleted if status = 'KO'. See the "urls" parameter.
This request allows you to move one or more files.
Access to the destination files and folder must be allowed: your own files or shared folders in write mode.
POST https://api.1fichier.com/v1/file/mv.cgi HTTP/1.1
Authorization: Bearer "API Key"
urls : List (array) of files (download links) to move.
Allows you to move only your own files or files to which you have write access (groupware shares). destination_folder_id : Identifier of the target folder (Root of your account if "0." Must be defined.). destination_user : Email of the user sharing his destination resource (used if destination_folder_id = 0 or empty) rename : (optional) Rename the file (works with 1 URL only)
JSON return (pretty):
status : Request status moved : Number of moved files urls : List (array) of files (download links) moved. filename : New filename, only if renamed.
Warning Will not work if your account or the owner of the files has the option "Confirm Deletion of Multiple Files" enabled.
Files may have been moved if status = 'KO'. See the "urls" parameter.
status : Request status renamed : Number of renamed files urls : List (hash) of files (download links) renamed.
Warning Some errors may have occurred even if some files could be renamed.
See the differences between the "urls" parameters of the request and response.
POST https://api.1fichier.com/v1/file/cp.cgi HTTP/1.1
Authorization: Bearer "API Key"
urls : List (array) of files (download links) to copy.
Copy all the files whose access is not restricted to you. folder_id : Identifier of target folder / destination (0 or not specified if root). pass : Access password (optional) sharing_user : Email of the user sharing his destination resource (used if folder_id = 0 or empty) rename : (optional) Rename the file (works with 1 URL only)
JSON return (pretty):
status : Request status copied : Number of copied files urls : List (hash) of files (download links) copied. filename : New filename, only if renamed.
Warning Some errors may have occurred even if some files could be copied.
See the differences between the "urls" parameters of the request and response.
urls : List (array) files (download links) to edit.
You can act on your files as well as the files to which you are authorized in write mode filename : Change the file name. Only works with a single file description : Modify the description of the file(s) (may be empty) pass : Change the access password. 6 characters minimum. (may be empty to remove) no_ssl : Force default access without SSL encryption inline : Forces "inline" access, informs the browser of the content-type and does not force the opening of a download box. cdn : Flag the files in "CDN". acl : Advanced access controls. Can be empty to remove acl/ip : List of IPs to allow. CIDR format. acl/country : List of countries to allow acl/email : List of registered users emails to allow acl/premium : Only allow our customers (Premium / Premium Light / Premium GOLD / Access)
JSON return (pretty):
status : Request status
Files may have been changed if 'KO'. See the "updated" parameter. updated : Number of updated URLs urls : List (array) of updated files (download links).
Warning Access will be blocked if requests are too frequent or abusive.
Only the "urls" parameter is mandatory. The others are optional depending on what you want to change.
Folders
Displays the information of a folder, as well as all child folders.
POST https://api.1fichier.com/v1/folder/ls.cgi HTTP/1.1
Authorization: Bearer "API Key"
folder_id : Identifier of the folder. Root if unspecified or 0. sharing_user : Email of the user who shares the folder (mandatory if sharing the root folder - ignored otherwise) files : (optional) : Add files list of the folder
JSON return (pretty):
shared : Public share using URL like https://1fichier.com/dir/abcdef pass : If access password shares : Groupware sharing shares/email : Registered email shares/rw : If the share is in write mode shares/hide_links : If the share is in hide_links mode. Issue only temporary download tokens.
Implies that the recipient is in Premium / Premium Light / Premium GOLD / Access status.
Inactive for shares in write mode user : Owner's email (only if groupware share) rw : If allowed in write mode (only if groupware share) hide_links : If in hide_links mode (only if groupware share and if rw = 0) files : Number of files in the folder (not recurisve) size : Total size of files in the folder (not recursive) items : See files/ls
Warning The "shares" part is displayed only for your own folders.
An empty JSON hash is always required (request from your root folder)
Create a folder
POST https://api.1fichier.com/v1/folder/mkdir.cgi HTTP/1.1
Authorization: Bearer "API Key"
name : Folder name
folder_id : (optional) Identifier of the parent folder. Root if unspecified or 0.
sharing_user : (optional) Email of the user sharing a folder (required if groupware sharing the root folder)
JSON return (pretty):
status : Request status
If 'KO': failure, "message" will be filled folder_id : Identifier of the created folder. Not specified if fail. name : Name of the folder. Not specified if fail.
Warning The folder name is limited to 250 characters maximum.
In case of misuse, the account and / or IP may be blocked.
POST https://api.1fichier.com/v1/folder/share.cgi HTTP/1.1
Authorization: Bearer "API Key"
folder_id : Folder ID share : If public sharing accessible via URL like https://1fichier.com/dir/abdef pass : If "share", possibility to set an access password (6 characters minimum) shares : Groupware shares with other registered users (0 or empty array to remove any groupware share) shares/email : Registerd user email address shares/rw : If allow in write mode shares/hide_links : Hide download links (implies shares/rw = 0)
JSON return (pretty):
status : Request status url : Folder access URL, if public share accessible via URL like https://1fichier.com/dir/abdef
Warning The root folder can not be shared publicly (URL https://1fichier.com/dir/abcdef)
You can not set a public and groupware share on the same request (either "folder_id" + "share" + "pass" or "folder_id" + "shares")
Any request will clear the previous settings (groupware shares).
POST https://api.1fichier.com/v1/folder/mv.cgi HTTP/1.1
Authorization: Bearer "API Key"
folder_id : Folder ID to move (source) destination_folder_id : Destination folder ID (root if "0") destination_user : User email (used in the case of a groupware share with destination_folder_id = 0) rename : New name for the folder (ignore destination_*)
JSON parameters (pretty):
ftp_mode : Mode of treatment of files uploaded by FTP. 0/automatic - 1/manual ftp_did : Destination folder ID of files uploaded by FTP (default root/0) ftp_report : Send a notification email after processing files uploaded by FTP. ru_report : Sending a notification email after processing a Remote Upload request. default_domain : Default file hosting domain (see table). page_limit : Limit the number of files show on a page (web interface) default_port : Default download port. 0/HTTP SSL - 1/HTTP default_port_files : Default download port for your files. 0/HTTP SSL - 1/HTTP use_cdn : Use your CDN credits for your own dowloads. download_menu : Display the download menu
JSON return (pretty):
status : Request status (only if request for modifications), offer : If customer. 0/No - 1/Premium - 2/Access - 3/Premium GOLD - 4/Premium Light 500G - 5/Premium Light 1000G 2fa : If the account is set for 2 authentication factors. 0/No - 1/Email code - 2/Google Authenticator cdn : CDN credits in GB (decimal number) subscription_end : Date when your current subscription finish default_quota : Default global account quota (deprecated - set to 0) default_cold_storage_quota : Default cold storage quota (meaningless on free and Access accounts - set to 0 -, and 500GB/1000GB/4TB/10TB for Premium Light/Premium/Premium GOLD accounts) hot/cold_storage : Account usage, in bytes, updated daily stats_date : Statistics last update date (storage usage total/hot/cold) allowed_cold_storage : Cold Storage allowed quota (default_cold_storage_quota+extended_quota - in TB) available_storage : Available (or excess) quota... In bytes. (default_quota-(hot_storage+cold_storage). available_cold_storage : Available (or excess) cold storage quota... In bytes. (default_cold_storage_quota+extended_quota) extended_quota : Extended cold storage capacities (in TB) extended_quota_end : Extended cold storage subscription end overquota : If the account exceeds its authorized quota (0 or 1), valid for all registered users (free, Access, Premium, Premium Light, Premium GOLD). upload_forbidden : If the file upload is forbidden (quota reached, abuse, ...)
Warning !
This request is limited to 1/mn per IP address and 1/5mn per user.
FTP
POST https://api.1fichier.com/v1/ftp/process.cgi HTTP/1.1
Authorization: Bearer "API Key"
JSON return (pretty):
{
"status" : "OK/KO",
"message" : "Message..."
}
status : Request status message : Information message
This feature is limited to our customers (Premium, Premium Light, Premium GOLD, Access)
POST https://api.1fichier.com/v1/ftp/users/ls.cgi HTTP/1.1
Authorization: Bearer "API Key"
headers/name : Alphanumeric characters accepted, including '-'. Insensitive to the box according to the RFC. We will normalize the variable in lowercase except for the first letter of words (eg Content-Type) headers/value : Accepted alphanumeric characters, including space, tab (excluding the first and last characters) [-_+=%?,'"/]
JSON return (pretty):
voucher : The voucher to use user_email : the account under which to use the voucher (optional, by default under the account linked to the current request)
JSON return (pretty):
{
"status" : "OK",
"message" : "XXX"
}
message : Error message if status = KO
Sample programs
Warning.
This is samples.
You have to add your own API key, the local folder you want to keep synchronized, and the destination remote folder ID (on your 1fichier.com account)
Theses softwares are not recurisive and are very basic.
About Windows : UTF8 is badly displayed, but the programs should be OK.
PS: UTF8 is correctly displayed on the Powershell ISE console
1234567890 // Timestamp of the end of the subscription, if Premium, Premium Light, Premium GOLD or Access (0 if no subscription)
12345.1234 // CDN credits of the account (if > 0 and if the account have the option to use them)
Warning.
This feature is deprecated and can be remove.
Display the folders list of the account
POST https://1fichier.com/console/get_dirs_for_upload.pl HTTP/1.1
POST parameters
"user" : "email@example.com" // Email
"pass" : "password" // Password (clear / plain text)
"pretty" : 0/1 // To have a human readable JSON output
Return (JSON) or redirect to the login page in case of error
type : Object type ('f' for a file, 'd' for a directory) name : Name... url : If file, the download link, if a folder, the URL to the associated get_folder_content size : Only for a file, size in bytes date : Object create data
Warning.
This feature is deprecated and can be remove.
Make (or complete) a path
POST https://1fichier.com/console/mkpath.pl HTTP/1.1