API documentation

Description

Returns the full file associated with the ID. Supports byte range requests.

You can also download multiple files at once by separating the IDs with commas in the URL. The files will then be served as a zip archive.

When ‘?download’ is added to the URL the server will send an attachment header instead of inline rendering, which causes the browser to show a ‘Save File’ dialog.

Warning: If a file is using too much bandwidth it can be rate limited. The rate limit will be enabled if a file has three times more downloads than views. The owner of a file can always download it. When a file is rate limited the user will need to fill out a captcha in order to continue downloading the file. The captcha will only appear on the file viewer page (pixeldrain.com/u/{id}). Rate limiting has been added to prevent the spread of viruses and to stop hotlinking. Hotlinking is only allowed when either the uploader or the downloader has a premium subscription.

Free downloads are also subject to limits on the number of downloads, the amount of data transferred and the number of simultaneous connections per IP address. When one of these limits is hit the download fails with one of the errors listed below. Most of these restrictions can be lifted by completing a captcha on the download page, or by getting a premium subscription.

Parameters

Returns

HTTP 200: OK

Requested file data

Example error:

HTTP 403: Forbidden

{
	"success": false,
	"value": "file_rate_limited_captcha_required",
	"message": "We have detected the use of hotlinking for this file. Hotlinking is only supported when either the uploader or the downloader has a paid subscription"
}

Possible errors

Description

Returns information about one or more files. You can also put a comma separated list of file IDs in the URL and it will return an array of file info, instead of a single object. There’s a limit of 100 files per request. Files which do not exist are left out of the array, the request only fails with not_found if none of the requested files exist.

Parameters

Returns

HTTP 200: OK

{
	"success": true,
	"id": "1234abcd",
	"name": "screenshot.png",
	// Size of the file in bytes
	"size": 5694837,
	// Number of unique file views, views are counted once per IP address
	"views": 1234,
	// Total bandwidth usage of the file
	"bandwidth_used": 1234567890,
	// Premium bandwidth usage, from users with a Pro subscription or bandwidth sharing
	"bandwidth_used_paid": 1234567890,
	// Unique downloads per IP address
	"downloads": 1234,
	"date_upload": "2020-02-04T18:34:05.706801Z",
	"date_last_view": "2020-02-04T18:34:05.706801Z",
	"mime_type": "image/png",
	// Link to a thumbnail of this file
	"thumbnail_href": "/file/1234abcd/thumbnail",
	// SHA256 sum of the file, encoded in hexadecimal
	"hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
	// When the delete_after_date or delete_after_downloads options are used
	// these fields show when the file will be deleted
	"delete_after_date": "0001-01-01T00:00:00Z",
	"delete_after_downloads": 0,
	// Availability indicates whether downloading is restricted. It's empty if
	// the file can be downloaded normally, else it contains one of the file
	// download error codes and availability_message contains an explanation
	"availability": "",
	"availability_message": "",
	// If the file received an abuse report these fields contain the type of
	// report and the name of the reporting organization
	"abuse_type": "",
	"abuse_reporter_name": "",
	// If the current logged in user can edit or download the file
	"can_edit": true,
	"can_download": true,
	// Whether advertisements are shown on the download page of this file
	"show_ads": false,
	// Whether the video player is available for this file
	"allow_video_player": true,
	// Download speed limit in bytes per second, 0 means no limit
	"download_speed_limit": 0
}

Possible errors

Description

Returns a PNG thumbnail image representing the file. The thumbnail image will be 256x256 px by default. You can specify the width and height with parameters in the URL. The width and height parameters need to be a multiple of 16 between 16 and 256. So the allowed values are 16, 32, 48, 64, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240 and 256. If a thumbnail cannot be generated for the file you will get an image representing the type of the file instead.

Parameters

Returns

A PNG image if a thumbnail can be generated. If a thumbnail cannot be generated you will get an icon representing the mime type of the file instead.

Possible errors

Description

Returns information about a file list and the files in it.

Parameters

Returns

The API will return some basic information about every file. Every file also has a “detail_href” field which contains a URL to the info API of the file. Follow that link to get more information about the file like size, checksum, mime type, etc. The address is relative to the API URL and should be appended to the end.

HTTP 200: OK

{
	"success": true,
	"id": "L8bhwx",
	"title": "Rust in Peace",
	"date_created": "2020-02-04T18:34:13.466276Z",
	"file_count": 3,
	// If the current logged in user can edit the list
	"can_edit": false,
	"files": [
		// These structures are the same as the file info response, except for
		// the detail_href and description fields
		{
			"detail_href": "/file/_SqVWi/info",
			"description": "",
			"success": true,
			"id": "_SqVWi",
			"name": "01 Holy Wars... The Punishment Due.mp3",
			"size": 123456,
			"date_upload": "2020-02-04T18:34:13.466276Z",
			"date_last_view": "2020-02-04T18:34:13.466276Z",
			"mime_type": "audio/mp3",
			"views": 1,
			"bandwidth_used": 1234567890,
			"thumbnail_href": "/file/_SqVWi/thumbnail"
		},
		{
			"detail_href": "/file/RKwgZb/info",
			"description": "",
			"success": true,
			"id": "RKwgZb",
			"name": "02 Hangar 18.mp3",
			"size": 123456,
			"date_upload": "2020-02-04T18:34:13.466276Z",
			"date_last_view": "2020-02-04T18:34:13.466276Z",
			"mime_type": "audio/mp3",
			"views": 2,
			"bandwidth_used": 1234567890,
			"thumbnail_href": "/file/RKwgZb/thumbnail"
		},
		{
			"detail_href": "/file/DRaL_e/info",
			"description": "",
			"success": true,
			"id": "DRaL_e",
			"name": "03 Take No Prisoners.mp3",
			"size": 123456,
			"date_upload": "2020-02-04T18:34:13.466276Z",
			"date_last_view": "2020-02-04T18:34:13.466276Z",
			"mime_type": "audio/mp3",
			"views": 3,
			"bandwidth_used": 1234567890,
			"thumbnail_href": "/file/DRaL_e/thumbnail"
		}
	]
}

HTTP 404: Not Found

{
	"success": false,
	"value": "not_found",
	"message": "The entity you requested could not be found"
}

Description

Reads a file or directory. If the path is a file the file contents are returned, byte range requests are supported. If the path is a directory a stat response is returned, see below.

This endpoint also has a collection of sub-APIs which can be accessed by adding query parameters to the URL:

Returns

When the path is a file and no query parameters are used the raw file contents are returned.

When the path is a directory, or the stat parameter is used, a stat object is returned. The path array contains a node object (described at the top of this chapter) for every path component, so you can show a breadcrumb navigation bar with it. base_index is the index of the requested node in the path array. children contains the nodes inside the directory:

HTTP 200: OK

{
	"path": [
		{
			"type": "dir",
			"path": "/",
			"name": "some_dir",
			... // Remaining node fields
		}
	],
	"base_index": 0,
	"children": [
		{
			"type": "file",
			"path": "/todo.txt",
			"name": "todo.txt",
			... // Remaining node fields
		}
	],
	// The permissions you have on this path
	"permissions": {
		"owner": false,
		"read": true,
		"write": false,
		"delete": false
	},
	"context": {
		// Whether downloads from this filesystem use premium transfer
		"premium_transfer": true
	}
}

Possible errors

Description

Returns information about the logged in user account.

Returns

HTTP 200: OK

{
	"id": "8e08a626-040e-417e-8713-a0f43737a235",
	"username": "some_user",
	"email": "user@example.com",
	"email_verified": true,
	// Whether two-factor authentication is enabled
	"otp_enabled": false,
	// The subscription plan of this account
	"subscription": {
		"id": "prepaid",
		"name": "Prepaid",
		"type": "prepaid",
		"file_size_limit": 107374182400,
		"file_expiry_days": 0,
		"storage_space": -1,
		"price_per_tb_storage": 4000000,
		"price_per_tb_bandwidth": 1000000,
		"monthly_transfer_cap": -1,
		"file_viewer_branding": true,
		"filesystem_access": true,
		"filesystem_storage_limit": -1
	},
	"storage_space_used": 1234567890,
	"filesystem_storage_used": 1234567890,
	"file_count": 420,
	"filesystem_node_count": 1337,
	"is_admin": false,
	// Prepaid balance in micro euros, 1000000 = €1
	"balance_micro_eur": 12500000,
	"hotlinking_enabled": true,
	// Monthly transfer cap in bytes, 0 means no custom cap is configured
	"monthly_transfer_cap": 0,
	"monthly_transfer_used": 1234567890,
	// File viewer customizations, see PUT /user/file_customization
	"file_viewer_branding": null,
	// Space separated list of domains which can embed your files
	"file_embed_domains": "",
	// Whether direct file links skip the file viewer page
	"skip_file_viewer": false,
	"affiliate_user_name": "",
	"checkout_country": "NLD",
	"checkout_name": "",
	"checkout_provider": ""
}

Description

Returns a list of all the files on the account, up to a maximum of 50000. The file objects have the same structure as the GET /file/{id}/info response.

Parameters

Returns

HTTP 200: OK

{
	"files": [
		{
			"id": "1234abcd",
			"name": "screenshot.png",
			"size": 5694837,
			... // Remaining file info fields, see GET /file/{id}/info
		}
	]
}

Description

Returns all the lists on the account. The list objects have the same structure as the GET /list/{id} response, except that the files array is not included.

Parameters

Returns

HTTP 200: OK

{
	"lists": [
		{
			"id": "L8bhwx",
			"title": "Rust in Peace",
			"date_created": "2020-02-04T18:34:13.466276Z",
			"file_count": 3,
			"can_edit": true
		}
	]
}

Description

Returns historic usage statistics of the account.

Parameters

Returns

HTTP 200: OK

{
	"timestamps": [
		"2024-02-04T18:00:00Z",
		"2024-02-04T19:00:00Z"
	],
	"amounts": [
		123456,
		654321
	]
}

Possible errors

Description

Returns the activity log of the account for one month. The activity log shows files which were removed from the account. The event field can be ‘file_instance_expired’, ‘file_instance_blocked’, ‘file_instance_lost’, ‘filesystem_node_blocked’ or ‘filesystem_node_lost’.

Parameters

Returns

HTTP 200: OK

[
	{
		"time": "2024-02-04T18:34:13.466276Z",
		"event": "file_instance_expired",
		"file_id": "1234abcd",
		"file_name": "screenshot.png",
		"file_removal_reason": "file_expired"
	}
]

Possible errors

Description

Returns the prepaid transaction log of the account for one month. All amounts are in micro euros, 1000000 = €1.

Parameters

Returns

HTTP 200: OK

[
	{
		"time": "2024-02-04T18:34:13.466276Z",
		"new_balance": 12500000,
		"deposit_amount": 0,
		"subscription_charge": -50000,
		"storage_charge": -25000,
		"storage_used": 1234567890,
		"bandwidth_charge": -10000,
		"bandwidth_used": 123456789,
		"affiliate_amount": 0,
		"affiliate_count": 0
	}
]

Possible errors

Description

Returns all the invoices of the account. Amounts are in micro euros, 1000000 = €1.

Returns

HTTP 200: OK

[
	{
		"id": "abc123",
		"time": "2024-02-04T18:34:13.466276Z",
		"amount": 10000000,
		"vat": 2100000,
		"country": "NL",
		"payment_gateway": "mollie",
		"payment_method": "ideal",
		"status": "paid"
	}
]

Description

Redirects the browser to the checkout page of an open invoice. If the payment does not exist anymore the invoice is cancelled and the browser is redirected back to the website.

Parameters

Returns

HTTP 302: Found, with a Location header pointing to the checkout page.

Possible errors

Description

Returns all the active sessions of the account. Use this to check for sessions which should not be there.

Returns

HTTP 200: OK

[
	{
		"auth_key": "550e8400-e29b-41d4-a716-446655440000",
		"creation_ip_address": "192.0.2.1",
		"user_agent": "Mozilla/5.0 ...",
		"app_name": "",
		"creation_time": "2024-02-04T18:34:13.466276Z",
		"last_used_time": "2024-02-04T18:34:13.466276Z"
	}
]

Description

Saves an API key as a login cookie in the browser. This is used by the website to transfer a login session from one pixeldrain domain to another. This endpoint does not use the regular API key authentication, instead the key is passed as a URL parameter. As a security measure this only works from the same IP address which created the API key.

Parameters

Returns

HTTP 200: OK, with a Set-Cookie header containing the API key.

{
	"success": true,
	"value": "ok",
	"message": "The requested action was successfully performed"
}

Possible errors