PixelDrain API Documentation

Welcome to the Pixeldrain API documentation.
The methods for uploading and retrieving files don't require an API key. The methods for creating and retrieving lists also don't require an API key. All methods which delete or modify a resource do require an API key.

Though API keys have not been implemented yet.

File Methods

POST/file

Description

Upload a file.

Parameters

Param Required Maximum Size Default Description
file true 5 000 000 000 Bytes none Multipart file to upload
name false 300 Characters Name of file param Name of the file to upload
description false 5000 Characters Pixeldrain File Description of the file

Returns

HTTP 200: OK
{
	"success": true,
	"id": "abc123" // ID of the newly uploaded file
}
HTTP 422: Unprocessable Entity
{
	"success": false,
	"value": "no_file",
	"message": "The file does not exist or is empty."
}
HTTP 500: Internal Server Error
{
	"success": false,
	"value": "internal",
	"message": "An internal server error occurred."
}
HTTP 413: Payload Too Large
{
	"success": false,
	"value": "file_too_large",
	"message": "The file you tried to upload is too large. Max 5000 MB allowed."
}
HTTP 500: Internal Server Error
{
	"success": false,
	"value": "writing",
	"message": "Something went wrong while writing the file to disk, the server may be out of storage space."
}
HTTP 413: Payload Too Large
{
	"success": false,
	"value": "name_too_long",
	"message": "File Name is too long, Max 300 characters allowed."
}
HTTP 413: Payload Too Large
{
	"success": false,
	"value": "description_too_long",
	"message": "File Description is too long, Max 5000 characters allowed."
}
GET/file/{id}

Description

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

Parameters

Param Required Location Description
id true URL ID of the file to request

Returns

A file output stream.
GET/file/{id}/download

Description

Same as GET /file/{id}, but with File Transfer HTTP headers. Will trigger a save file dialog when opened in a web browser. Also supports byte range requests.

GET/file/{id}/info

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.

Parameters

Param Required Location Description
id true URL ID(s) of the file

Returns

HTTP 200: OK
{
	"success": true,
	"id": "123abc",
	"file_name": "screenshot.png",
	"date_upload": 1485894987, // Timestamp
	"date_last_view": 1485894987, // Timestamp
	"file_size": 5694837, // Bytes
	"views" 1234, // Amount of unique file views
	"mime_type" "image/png",
	"description": "File description",
	"mime_image": "http://pixeldra.in/res/img/mime/image-png.png", // Image associated with the mime type
	"thumbnail": "http://pixeldra.in/api/thumbnail/123abc" // Link to a thumbnail of this file
}
HTTP 404: Not Found
{
	"success": false,
	"value": "file_not_found"
}
GET/file/{id}/thumbnail

Description

Returns a PNG thumbnail image representing the file. The thumbnail is always 100*100 px. If the source file is parsable by imagemagick the thumbnail will be generated from the file, if not it will be a generic mime type icon.

Parameters

Param Required Location Description
id true URL ID of the file to get a thumbnail for

Returns

A PNG image of 100*100 px.

DELETE/file/{id}

Description

Deletes a file. Only works when the users owns the file.

Parameters

Param Required Location Description
id true URL ID of the file to delete

Returns

HTTP 200: OK
{
	"success": true,
	"value": "file_deleted",
	"message": "The file has been deleted."
}
HTTP 404: Not Found
{
	"success": false,
	"value": "file_not_found",
	"message": "File ID was not found in the database."
}
HTTP 401: Unauthorized
{
	"success": false,
	"value": "unauthorized",
	"message": "You are not logged in."
}
HTTP 403: Forbidden
{
	"success": false,
	"value": "forbidden",
	"message": "This is not your file."
}

List Methods

POST/list

Description

Creates a list of files that can be viewed together on the file viewer page.

Parameters

POST body should be a JSON object, example below. A list can contain maximally 5000 files. If you try to add more the request will fail.

Example

{
	"title": "My beautiful photos",
	"description": "An album of photos from my vacation in Austria",
	"files": [ // Ordered array of files to add to the list
		{
			"id": "abc123",
			"description": "First photo of the week, such a beautiful valley"
		},
		{
			"id": "123abc",
			"description": "The week went by so quickly, here's a photo from the plane back"
		}
	]
}

Returns

HTTP 200: OK
{
	"success": true,
	"id": "yay137" // ID of the newly created list
}
HTTP 422: Unprocessable Entity
{
	"success": false,
	"value": "file_not_found",
	"id": "Oh42No", // The file you tried to add with this ID does not exist
	"message": "File Oh42No was not found in the database."
}
HTTP 413: Payload too large
{
	"success": false,
	"value": "too_many_files",
	"message": "This list contains too many files, max 5000 allowed."
}
HTTP 422: Unprocessable Entity
{
	"success": false,
	"value": "json_parse_failed",
	"message": "The JSON object in the request body could not be read."
}
HTTP 413: Payload too large
{
	"success": false,
	"value": "title_too_long",
	"message": "The title of this list is too long, max 300 characters allowed."
}
HTTP 413: Payload too large
{
	"success": false,
	"value": "description_too_long",
	"message": "The description of this list or one of the files in the list is too long, max 3000 characters allowed."
}
HTTP 422: Unprocessable Entity
{
	"success": false,
	"value": "cannot_create_empty_list",
	"message": "You cannot make a list with no files."
}
GET/list/{id}

Description

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

Parameters

Param Required Location Description
id true URL ID of the list

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": 1513033315,
	"files": [
		{
			"detail_href": "/file/_SqVWi/info",
			"id": "_SqVWi",
			"file_name": "01 Holy Wars... The Punishment Due.mp3",
			"description": "",
			"date_created": 1513033304,
			"date_last_view": 1513033304,
			"list_description": ""
		},
		{
			"detail_href": "/file/RKwgZb/info",
			"id": "RKwgZb",
			"file_name": "02 Hangar 18.mp3",
			"description": "",
			"date_created": 1513033304,
			"date_last_view": 1513033304,
			"list_description": ""
		},
		{
			"detail_href": "/file/DRaL_e/info",
			"id": "DRaL_e",
			"file_name": "03 Take No Prisoners.mp3",
			"description": "",
			"date_created": 1513033304,
			"date_last_view": 1513033304,
			"list_description": ""
		}
	]
}
HTTP 404: Not Found
{
	"success": false,
	"value": "list_not_found",
}

Pixeldrain is a product by Fornaxian Technologies.