NAV
sh php JS python

Introduction

Publitio offers advanced APIs for Media (Video, Image, Audio and Document) Management in the cloud.

You can use our API endpoints to get information on various files, versions, players, adtags, and watermarks created and/or stored with us.

Here you will find documentation and reference to our REST and URL-based APIs.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Getting started

  1. Create an account
  2. Get API and Secret Keys at your Dashboard
  3. Choose SDK or Framework for integration
  4. Start testing

Authentication

The Publitio API uses signature-based authentication to verify the identity of an API user. In order to make API calls, you will need the API Key and API Secret, which can both be found at the Dashboard. You can also generate a full API Signature at the Dashboard for testing purposes.

Authentication parameters

In order to authenticate an API call the following parameters are required:

Parameter Description
api_key API Key identifies the user to the API. It can be found in the Publitio Dashboard.
api_timestamp API timestamp is the current UNIX timestamp (32-bit signed integer). It is used to protect against replay-attacks.
api_nonce API nonce is an 8-digit random number. It is used to make sure that the API signature is always unique, even if the same call has been made twice within one second.
api_signature SHA-1 digest of the api_nonce, api_timestamp and api_secret.

API signature generation

The API signature is a SHA-1 digest and is generated similar to the OAuth Core 1.0 specification.

  1. Parameters (api_timestamp, api_nonce and api_secret) are concatenated together into a single string:

<api_timestamp><api_nonce><api_secret>

  1. SHA-1 digest is calculated. The calculated SHA-1 HEX digest for the above string will be:

4591350417a53c4656572ab14bd4f1759a48019b

An authenticated API call will look like this:

https://api.publit.io/v1/files/list?api_key=a73eda4c9cd05a757e05ac1557f62be7&api_nonce=35367098&api_signature=4591350417a53c4656572ab14bd4f1759a48019b&api_timestamp=1515580186

Protection against replay-attacks

When a signature-based method is used it is possible that the call can be captured by a malicious party and “replayed” later. To protect against this type of attack, the Publitio API implements the following measures:

Testing the API

For convenience of testing the Publitio API, you can generate a full API Signature at the Dashboard and use it via browser, Postman or curl for testing. Each API signature is valid for 1h and 1 API call. For multiple API calls and 24h TTL please append &api_test=true to the end of the API Signature.

An authenticated API call for testing will look like this:

https://api.publit.io/v1/files/list?api_key=a73eda4c9cd05a757e05ac1557f62be7&api_nonce=35367098&api_signature=4591350417a53c4656572ab14bd4f1759a48019b&api_timestamp=1515580186&api_test=true

Download SDK's

Here is a list of SDK's for the Publitio API that you can download and integrate with frameworks of your choice. We're working on adding more supported languages soon.

URL-Based Transformations

Publitio offers a URL-based form of API through which you can do all file transformations on the fly, just over the browser, by changing parameters in the file URL. You can use it to transcode your files between formats, for resizing, cropping, trimming, watermarking and/or quality adjustment.

The idea is identical to the Create Version method: you pass options and extension to the file URL and a new file version will be created on the fly.

https://media.publit.io/file/<options>/<file_id>.<extension>

List of supported file formats (extensions)

List of options for transformations

For options, you can use the following: w and h for resizing, c for cropping, wm for watermarking and q for quality adjustment. For trimming of videos, use t (time), so (start offset) and eo (end offset) parameters.

Sample files

This is our sample Butterflies image: https://media.publit.io/file/butterflies.jpg

alt text

our sample video Tummy: https://media.publit.io/file/tummy.mp4

our sample audio Railgun: https://media.publit.io/file/railgun.wav

and our sample document: https://media.publit.io/file/doc.pdf

Let's see on a few examples how to use options and extensions parameters to do various transformations:

Resizing

To resize an image or video to 600 pixels in width append w_600 to the URL, as in:

https://media.publit.io/file/w_600/butterflies.jpg

alt text

To resize an image or video to 400x400 pixels in size append w_400,h_400 to the URL, as in:

https://media.publit.io/file/w_400,h_400/butterflies.jpg

alt text

Cropping

For cropping, please use the c parameter in combination with w (width) and h (height) parameters. Supported values are c_fit (fit), c_fill (fill) and c_limit (limit).

c_fill will resize the image or video to exact given width and height while retaining the original aspect ratio, using only a part of the original file that fills the given dimensions if necessary.

To create a 300x300 pixel thumbnail out of an image with c_fill, append w_300,h_300,c_fill to the URL as in:

https://media.publit.io/file/w_300,h_300,c_fill/butterflies.jpg

alt text

c_fit will resize the file so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. Original aspect ratio is retained and all of the original file is visible. To create 300x300 pixel thumbnail out of our sample image with c_fit, append w_300,h_300,c_fit to the URL as in:

https://media.publit.io/file/w_300,h_300,c_fit/butterflies.jpg

alt text

c_limit is same as the c_fit mode but only if the original file is larger than the given limit (width and height), in which case the image or video is scaled down so that it takes up as much space as possible within a bounding box defined by the given width and height parameters.

Watermarking

For watermarking of images and videos use the wm option. To watermark our sample image using a watermark with ID publitio append wm_publitio to the URL:

https://media.publit.io/file/wm_publitio,w_800/butterflies.jpg

alt text

You can use wm in combination with the rest of the options, for example w_800,h_600,c_fill,wm_publitio.

Trimming

For trimming (video and audio option) please use the so (start offset) and eo (end offset) parameters.

Option t (time) can be used for video to image transformation. For example, to get an image from the 3rd second of video, use t_3 as an option and set the extension to jpg in the URL:

https://media.publit.io/file/t_3,w_800/tummy.jpg

alt text

To create a 2 second long trimmed video out of the original video starting from 2nd second, use so_2,eo_2 in the URL. so_2 indicates from which second (2) to start trimming and eo_2 is making the trimmed video 2 seconds long:

https://media.publit.io/file/so_2,eo_2,h_480/tummy.mp4


To create a 2 second long trimmed audio from original audio starting at 1st second, use so_1,eo_2 in the URL. so_1 indicates at which second (1) to start trimming and eo_2 makes the trimmed audio 2 seconds long:

https://media.publit.io/file/so_1,eo_2/railgun.mp3

Transcoding

Here we will show how you can easily do image to image, image to video, video to video, video to image, video to audio, audio to audio, audio to video, audio to image (waveform) and document to image transformations with the URL-Based API.

Image to image

To transcode our sample image to png format, we just need to change the extension in the URL like this:

https://media.publit.io/file/butterflies.png

alt text

We can combine different extensions with all the options, so for example to create and image 500 pixels wide, with a watermark and in gif format, we can use w_500,wm_publitio as the options and gif as the extension:

https://media.publit.io/file/w_500,wm_publitio/butterflies.gif

alt text

Image to video

To create an mp4 video out of an image (useful for gif files and player integration), change the extension to mp4:

https://media.publit.io/file/w_800/butterflies.mp4

Video to video

Any video you upload can be transcoded to mp4, webm and ogv formats.

To create a 360p mp4 video out of our original sample Tummy video, format the URL as in:

https://media.publit.io/file/h_360/tummy.mp4

Transcoding can be done in combination with other available options, so for example to create a 480p mp4 watermarked video out of the original, we can add h_480,wm_publitio to the URL and set the extension to mp4:

https://media.publit.io/file/h_480,wm_publitio/tummy.mp4

Video to image

You can extract an image from any part of the video. To create a png image from the 2nd second of video, add t_2 (time = 2 seconds) to the URL as follows:

https://media.publit.io/file/t_2/tummy.png

alt text

This can be useful for generating thumbnails from the video, just by adding the right w (width) and different t (time) options to the URL:

https://media.publit.io/file/t_1,w_200/tummy.png

alt text

https://media.publit.io/file/t_2,w_200/tummy.png

alt text

https://media.publit.io/file/t_3,w_200/tummy.png

alt text

Video to audio

Any video you upload can be transcoded to mp3, wav and ogg audio formats.

To create mp3 audio out of our original sample Tummy video, format the URL as in:

https://media.publit.io/file/tummy.mp3


Video to audio transformations support so and eo parameters for trimming the audio. To create 2 seconds of mp3 audio, starting from the 2nd second of video, format the URL as:

https://media.publit.io/file/so_2,eo_2/tummy.mp3


Audio to audio

Any audio you upload can be transcoded to following audio formats: mp3, wav and ogg.

To create mp3 audio out of our original sample Railgun wav audio, format the URL as in:

https://media.publit.io/file/railgun.mp3


Audio to audio transformations support so and eo parameters for audio trimming. To create 2 seconds of mp3 audio, starting from the 2nd second of audio, format the URL as:

https://media.publit.io/file/so_2,eo_2/railgun.mp3


Audio to image

You can transcode uploaded audio files to images (waveforms) in following formats: jpg, png, gif and webp. This is useful if you need to have some visual representation of an audio file.

To create a png out of our original sample Railgun wav audio, format the URL as in:

https://media.publit.io/file/railgun.png

alt text

To control the waveform and background color, please use fc (foreground color) and bc (background color) parameters. Both fc and bc will accept any HEX color value (for example fc_66A8CC,bc_000000) or pre-defined color values like grey, blue, green, orange, pink, red, yellow, black and white. For example to generate a jpg waveform image from a wav audio file, with blue waveform and black background, use option fc_blue,bc_black and format the URL as in:

https://media.publit.io/file/fc_blue,bc_black/railgun.jpg

alt text

Audio to video

You can create videos out of audio files. Supported video from audio formats are: mp4, webm and ogv. This basically creates a video by combining the waveform and audio of our file, and is useful if you want to play audio within a video player and wish to monetize audio files through video ads.

To create an mp4 video out of our original sample Railgun wav audio, format the URL as in:

https://media.publit.io/file/railgun.mp4


Document to image

You may use the t option on documents to get a specific page. For example, imagine we have a file called doc.pdf. To get the second page of this document in png format, we could use t_2:

https://media.publit.io/file/t_2/doc.png

alt text

In this case, all options for images also apply. To get the second page in png format with 300x300 dimensions and cropped to fit, we could use:

https://media.publit.io/file/t_2,w_300,h_300,c_fit/doc.png

alt text

Quality

Quality adjustment of your images, videos and audio files can be controlled through the q parameter. This parameter represents the compression level to apply to a media file between 1 (smallest file size possible) and 100 (best quality). For example, to reduce the quality of our sample image to 50, please use q_50:

https://media.publit.io/file/q_50/butterflies.jpg

alt text

Files

The Files Class allows easy creation (uploading) and management of your images, videos, audio files and documents. With it you can use the Publitio API to upload, host, download and deliver your media files. Publitio goes a few steps further and allows transformations and transcoding of your files via the Versions Class, publishing via the HTML5 Media Player through the Players Class, monetization with ads thanks to the Adtags Class, and even copyright protection via the Watermarks Class.

Create File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

$response = $publitio_api->upload_file(
    fopen('file.jpg'), 'file',
    array(
        'public_id' => 'mytestwm',
        'description' => 'some nice desc',
        'tags' => 'one, two, three'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/files/create?{{api_signature}}" \
-H "Accept: application/json" \
--form public_id=mytestfile \
--form file=@/localpathtoimage/file.png
import PublitioAPI from 'publitio_js_sdk'
import { readFileSync } from 'fs'

// This could also be a ReadableStream in Node, a File in the browser or a string
const file = readFileSync('image.png')

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.uploadFile(file, 'file')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.create_file(file=open('path/to/file', 'rb'),
                         title='My title',
                         description='My description')

# Note that the file must be opened for binary reading.
# The publitio_api.create_file function will not close the file.
# Therefore, what you will probably want to do most of the time is:

with open('path/to/file.png', 'rb') as f:
    publitio_api.create_file(file=open('path/to/file', 'rb'),
                             title='My title',
                             description='My description')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "File uploaded",
  "id": "qAfRRgxx",
  "public_id": null,
  "folder": "Y2K/",
  "folder_id": "4vZsZBGa",
  "title": "sample file",
  "description": "",
  "tags": "",
  "type": "image",
  "extension": "jpg",
  "size": 26846,
  "width": 373,
  "height": 373,
  "privacy": "public",
  "option_download": "enabled",
  "option_ad": "enabled",
  "option_transform": "enabled",
  "wm_id": null,
  "url_preview": "https://media.publit.io/file/Y2K/qAfRRgxx.jpg",
  "url_thumbnail": "https://media.publit.io/file/w_300,h_200,c_fill/qAfRRgxx.jpg",
  "url_download": "https://media.publit.io/download/qAfRRgxx.jpg?at=eyJpdiI6Inc5NGg2TG1IZDB4bDJTUXpaUmRUd1E9PSIsInZhbHVlIjoiaVlIRmd3SFo5YTdOR1hMdENLZmErdGEyR3pWbk1IYmtoTHdwT0VsU25BWT0iLCJtYWMiOiI0MzlmMmYwM2IxY2YxNDE1ZmZmNjgxMGI1M2JmMjQ5NTgyZDk3N2JkN2M4ZDA1NzZhMzU1MjRiMGE2NDkwN2YyIn0=",
  "versions": 0,
  "hits": 0,
  "created_at": "2018-01-15 08:37:15",
  "updated_at": "2018-01-15 08:37:15"
}

This endpoint creates (uploads) a new file. You can upload the following file types:

HTTP Request

POST https://api.publit.io/v1/files/create

Query Parameters

Parameter Required Type Description
file yes file Image or video to upload.
file_url no URL Remote image or video URL if no file is present.
public_id no string Unique alphanumeric public ID of the file. Default is null (random public ID).
folder no string Folder ID to place the file in. Default is null (root folder).
title no string File title. Default is taken from the file name.
description no string File description.
tags no string File tags separated by spaces or commas. Used for search.
privacy no bool File privacy. Supported values are 0 (private) and 1 (public). Default is 0 (private).
option_download no bool Enable file download. Supported values are 0 (disabled) and 1 (enabled). Default is 1 (enabled).
option_transform no bool Enable URL-based transformations. Supported values are 0 (disabled) and 1 (enabled). Default is 1 (enabled).
option_ad no bool Enable ads on this file. Supported values are 0 (disabled), 1 (enabled) and 2 (new). Default is 1 (enabled).
option_hls no bool Enables HLS video encryption for this file (in use with videos only). Supported values are 0 (disabled), 1 (enabled). Default is 0 (disabled).
wm no string Watermark ID. Default is null (no watermark).
cname no string Cname ID. Default is null.

List Files

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');
$response = $publitio_api->call('/files/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/files/list', 'GET', { offset: '0', limit: '10' })
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
response = publitio_api.list_files(offset=1)

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "limit": 100,
  "offset": 0,
  "files_total": 2,
  "files_count": 2,
  "files": [
    {
      "id": "RVsbVdyp",
      "public_id": null,
      "folder": null,
      "folder_id": null,
      "title": "rasa1",
      "description": "",
      "tags": "",
      "type": "image",
      "extension": "jpg",
      "size": 77008,
      "width": 1000,
      "height": 667,
      "privacy": "public",
      "option_download": "enabled",
      "option_ad": "enabled",
      "option_transform": "enabled",
      "wm_id": null,
      "url_preview": "https://media.publit.io/file/RVsbVdyp.jpg",
      "url_thumbnail": "https://media.publit.io/file/w_300,h_200,c_fill/RVsbVdyp.jpg",
      "url_download": "https://media.publit.io/download/RVsbVdyp.jpg?at=eyJpdiI6Ik5XT2t2QkRkeHNiUmxJZDR6QTBGcEE9PSIsInZhbHVlIjoiN01CXC9WYWxGdGRBZ29wak1jXC80d1B0TlVIWko0OCtIbjB3VXZIM0J2ZHlNPSIsIm1hYyI6IjA2MGFjYzI1Y2U0MTFkMzZmMGQyNjdmNTM0Mjk1MzI1NjQzZjk1ZmY2ODE4N2NhODRmYjE1MTZmZTgwY2VlOTgifQ==",
      "versions": 1,
      "hits": 13,
      "created_at": "2017-11-22 15:48:13",
      "updated_at": "2017-12-20 11:26:59"
    },
    {
      "id": "oZTuvJmJ",
      "public_id": null,
      "title": "rasa2",
      "folder": null,
      "folder_id": null,
      "description": "",
      "tags": "",
      "type": "image",
      "extension": "jpg",
      "size": 77785,
      "width": 1000,
      "height": 665,
      "privacy": "public",
      "option_download": "enabled",
      "option_ad": "enabled",
      "option_transform": "enabled",
      "wm_id": null,
      "url_preview": "https://media.publit.io/file/oZTuvJmJ.jpg",
      "url_thumbnail": "https://media.publit.io/file/w_300,h_200,c_fill/oZTuvJmJ.jpg",
      "url_download": "https://media.publit.io/download/oZTuvJmJ.jpg?at=eyJpdiI6IkZBU0VzSDZFZkFuYzdOcmZ0a213MVE9PSIsInZhbHVlIjoiT0R3K2FRZ2cxU1huUlpiNzFURDJkN3pBeTVxMzJMZTRRWjV3U3dEc21ncz0iLCJtYWMiOiJiZjQwODk0NmZkZThjYTQ0MzQ4MzU4NmFiNzgxNzRhYzE5ZWFhZTA4YWM5Mzg3MTYyOGFhYjlhMWMyOWU5NmUxIn0=",
      "versions": 1,
      "hits": 5,
      "created_at": "2017-11-22 15:48:14",
      "updated_at": "2017-12-20 11:27:30"
    }
  ]
}

This endpoint returns a list of all uploaded files.

HTTP Request

GET https://api.publit.io/v1/files/list

Query Parameters

Parameter Required Type Description
limit no int Maximum number of files to return. Default is 100. Maximum limit is 1000.
offset no int How many files should be skipped at the beginning of the result set. Default is 0.
order no string How the files should be ordered. Supported values are date, name, size and hits. You may also append :asc for an ascending sort order or :desc for a descending order (for example name:desc). By default, the files are sorted by date in ascending order.
filter_privacy no string Specifies which files should be returned based on their privacy. Supported values are all, private and public. Default is all.
filter_extension no string Specifies which files should be returned based on their extension. For a full list of extensions see supported extensions. Default is all.
filter_type no string Specifies which files should be returned based on their type. Supported values are all, image, video and audio. Default is all.
filter_ad no string Specifies which files should be returned based on their option_ad status. Supported values are all, enabled, disabled and new. Default is all.
tags no string Search query tags separated by + signs. You can append :any to list files which have any of the tags, or :all to list only files which have all of the tags. Default mode is all. For example, use dogs+cats:any to select all files which either have the dogs or the cats tag.
folder no string Folder ID or Path to list files from. Default is null (lists all files). Use / to list top (root) folder files.

Show File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show file with id MvHX8Zx5
$response = $publitio_api->call('/files/show/MvHX8Zx5', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/show/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show file with id MvHX8Zx5
publitio.call('/files/show/MvHX8Zx5', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show file with ID MvHX8Zx5
publitio_api.show_file('MvHX8Zx5')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "MvHX8Zx5",
  "public_id": null,
  "title": "rasa1",
  "description": "",
  "tags": "",
  "type": "image",
  "extension": "jpg",
  "size": 77008,
  "width": 1000,
  "height": 667,
  "privacy": "public",
  "option_download": "enabled",
  "option_ad": "enabled",
  "option_transform": "enabled",
  "wm_id": null,
  "url_preview": "https://media.publit.io/file/MvHX8Zx5.jpg",
  "url_thumbnail": "https://media.publit.io/file/w_300,h_200,c_fill/MvHX8Zx5.jpg",
  "url_download": "https://media.publit.io/download/MvHX8Zx5.jpg?at=eyJpdiI6IkhHK0o2SUp0Rmw0Ynh6WVU2T1diV2c9PSIsInZhbHVlIjoidlFcL3RERUZRaWRmbWVsTG9BQWdyTXozQWprR1VhSGVLN3RMR3RxUVVSd1k9IiwibWFjIjoiY2ZjNGQ2YmUzM2JiYzQ2YzRhZjkzMDRhMDY3NjBjNzNmMmM3YzZkMTlkN2ZkMDA4NGZkOTI1ZGJhZWQzMzI2YyJ9",
  "versions": 2,
  "hits": 14,
  "created_at": "2017-11-22 15:48:13",
  "updated_at": "2018-01-10 16:00:22"
}

This endpoint shows specific file info based on its ID.

HTTP Request

GET https://api.publit.io/v1/files/show/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.
cname no string Cname ID. Default is null.

Update File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
// Update file with id MvHX8Zx5
$response = $publitio_api->call(
    '/files/update/MvHX8Zx5',
    'PUT',
    array(
        'position' => 'top-left',
        'padding' => '10'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/files/update/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json" \
--data title="New File Title" \
--data description="This id file description..."
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// update file with id MvHX8Zx5
publitio.call('/files/update/MvHX8Zx5', 'PUT', {
    title: 'some title',
    description: 'dome desc',
    tags: 'tag1 tag2',
    privacy: '1',
    option_download: '1',
    option_ad: '1'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update file with id MvHX8Zx5
publitio_api.update_file('MvHX8Zx5', title='A better title')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file with with id 'MvHX8Zx5' has been updated"
}

This endpoint updates file info.

HTTP Request

PUT https://api.publit.io/v1/files/update/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.
public_id no string Unique alphanumeric public ID of the file.
folder no string Folder ID to place the file in.
title no string File title.
description no string Optional file description.
tags no string Optional file tags separated by spaces or commas. Used for search.
privacy no bool File privacy. Supported values are 0 (private) and 1 (public).
option_download no bool Enable file download. Supported values are 0 (disabled) and 1 (enabled).
option_transform no bool Enable URL-based transformations. Supported values are 0 (disabled) and 1 (enabled).
option_ad no bool Enable ads on the file. Supported values are 0 (disabled), 1 (enabled) and 2 (new).
option_hls no bool Enables HLS video encryption for this file (in use with videos only). Supported values are 0 (disabled), 1 (enabled). Default is 0 (disabled).
thumb_id no string Unique alphanumeric name (ID) of an image file to be used as the player thumbnail. To disable an existing thumbnail, use none. This option is only valid for video and audio files.
wm no string Watermark ID. Default is null.
cname no string Cname ID. Default is null.

Delete File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete file with id MvHX8Zx5
$response = $publitio_api->call('/files/delete/MvHX8Zx5', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/files/delete/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete file with id MvHX8Zx5
publitio.call('/files/delete/MvHX8Zx5', 'DELETE')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete file with id MvHX8Zx5
publitio_api.delete_file('MvHX8Zx5')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file with id 'MvHX8Zx5' has been deleted!"
}

This endpoint deletes a file based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/files/delete/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.

Player File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Get player for file with id mytestfile
$response = $publitio_api->call('/files/player/mytestfile', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/player/mytestfile?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Get player for file with id mytestfile
publitio.call('/files/player/mytestfile', 'GET', {
    player: 'myplayer',
    adtag: 'myadtag'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Get player for file with id mytestfile
publitio_api.get_file_player('mytestfile', player='myplayer')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "embed_url": "//media.publit.io/file/RVsbVdyp.html",
  "player_html": "<div id=\"publitio_RVsbVdyp\" class=\"publitioPlayer\" ><div id=\"publitio_ph_RVsbVdyp\" class=\"publitioPlaceHolder\" ><div id=\"publitio_phb_RVsbVdyp\" class=\"publitioPlaceHolderBtn\" ></div><img class=\"publitioPlaceHolderImg\" src=\"https://media.publit.io/file/RVsbVdyp.jpg\" ></div></div><link href=\"http://static.publit.io/css/publitio_player.min.css\" rel=\"stylesheet\" /><script src=\"http://static.publit.io/js/publitio_player.min.js\"></script><script src=\"//imasdk.googleapis.com/js/sdkloader/ima3.js\"></script><script type=\"text/javascript\">var publitio_RVsbVdyp = new Publitio({id: \"RVsbVdyp\", width: \"1000\", height: \"667\", fileSources: {mp4:\"https://media.publit.io/file/RVsbVdyp.mp4\", webm:\"https://media.publit.io/file/RVsbVdyp.webm\", ogv:\"https://media.publit.io/file/RVsbVdyp.ogv\", jpg:\"https://media.publit.io/file/RVsbVdyp.jpg\"}, adTag: \"\", autoPlay: 0, controlBar: \"false\", playerSkin: \"grey\"});</script>",
  "source_html": "<img src=\"https://media.publit.io/file/w_640/RVsbVdyp.jpg\" srcset=\"https://media.publit.io/file/w_320/RVsbVdyp.jpg 320w, https://media.publit.io/file/w_640/RVsbVdyp.jpg 640w\" sizes=\"100vw\" alt=\"xoxoxo\" />",
  "iframe_html": "<div><div  style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 62.5%;\"><iframe src=\"https://media.publit.io/file/RVsbVdyp.html?player=&adtag=\" scrolling=\"no\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute; overflow:hidden;\" allowfullscreen=\"\" ></iframe></div></div>"
}

This endpoint shows the HTML5 Media Player containing the specified file. It returns source_html that you can insert directly into your HTML code.

HTTP Request

GET https://api.publit.io/v1/files/player/<file_id>

Query Parameters

Parameter Required Type Description
player yes string Target player ID.
adtag no string ID of adtag to load with the player.
adtag_url no string URL of VAST/IMA adtag to load with the player (overwrites the adtag parameter).
auto_play no int Auto-play content (overwrites player auto_play setting). Supported values are 0 (off), 1 (on) and 2 (onmouseover).
cname no string Cname ID. Default is null.

Embed URL

File Player call response will have an embed_url field. This is a direct URL that you can use to preview your files within the Publitio Player. To access it, just change the extension to html on any Preview URL you get for you files:

https://media.publit.io/file/<file_id>.html

For example, to preview our sample Tummy video, you can go to: https://media.publit.io/file/tummy.html.

You can pass the player query parameter to preview files with a different player setup, for example: https://media.publit.io/file/tummy.html?player=publitio.

Source Html

File Player call response will have a source_html field. In case of an image, this will be a <img src="..."> or <img srcset="..."> formatted tag you can insert directly into your HTML code. For videos, this will be a <video ... > tag with predefined sources (paths to video streams), and in case of audio files this will be a <audio ... > HTML5 tag.

For example, source_html for our sample image Butterflies behaves as:

Iframe HTML

File Player call response will have an iframe_html field. This is formatted HTML with responsive iframe code and embed URL - the easiest way to embed videos, images and audio into your webpage. For example, iframe from our sample Tummy video is embedded as:

Player HTML

File Player call response will have a player_html field. This code is the same as iframe_html, except it doesn't use iframe and embed URL, but instead provides formatted HTML code that crates/inserts a player directly into your webpage.

Versions

Versions Class (a sub-class of Files) allows easy creation and management of derived versions of your uploaded files. With it you can do transformations, transcoding between formats, cropping, resizing, watermarking, quality adjustment, and more.

Create Version

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Create a new version from file with ID mytestfile, with options width=320, height=240, crop=fill
$response = $publitio_api->call(
    '/files/versions/create/mytestfile',
    'POST',
    array(
        'extension' => 'mp4',
        'options' => 'w_320,h_240,c_fill'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/files/versions/create/mytestfile?{{api_signature}}" \
-H "Accept: application/json" \
--data extension="mp4" \
--data options="w_320,h_240,c_fill"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Create a new version from file with ID mytestfile, with options width=320, height=240, crop=fit
publitio.call('/files/versions/create/mytestfile', 'POST', {
    extension: 'mp4',
    options: 'w_320,h_240,c_fit'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Create a new version from file with ID mytestfile, transcoded to webm
publitio_api.create_version('mytestfile', extension='.webm', ...)

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "File version created",
  "id": "JR78dfTh",
  "file_id": "RVsbVdyp",
  "extension": "png",
  "options": "h_250,w_250",
  "size": 90711,
  "status": "ready",
  "url": "https://media.publit.io/file/h_250,w_250/RVsbVdyp.png",
  "hits": 0,
  "created_at": "2018-01-10 16:00:19",
  "updated_at": "2018-01-10 16:00:21"
}

This endpoint creates a new file version from the original file. You can use it to transcode your files between formats, for resizing, cropping, watermarking and quality adjustment.

HTTP Request

POST https://api.publit.io/v1/files/versions/create/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Original file ID.
extension yes string File extension (output format) for this version. For the list of supported formats, see below.
options yes string List of options you want to apply to this transformation. For the list of supported options, see below.
cname no string Cname ID. Default is null.

List of extensions (output formats)

With the Publitio API you can easily transcode your files between formats. Supported extensions (output formats) are:

List of options for transformations

Publitio API supports the following image, video and audio manipulations/transformations: resizing, cropping, watermarking, quality adjustment and trimming (video and audio files only). Here is a guide on how to use each of these options:

For resizing, please use w (width) and h (height) parameters. Both w and h accept integer values. For example, w_250 sets the width to exactly 250 pixels. You can resize the file by using both the width and height parameters or with only one of them: the other dimension is automatically updated to maintain the aspect ratio. For example, to resize an image or video to 800x600 pixels, use w_800,h_600

For cropping, please use the c (crop) parameter in combination with w (width) and h (height) parameters. Supported values are c_fit (fit), c_fill (fill) and c_limit (limit).

For watermarking of images and videos, use the wm parameter. For example, to protect your file using a watermark with ID publitio, format your option as wm_publitio. You can also use wm in combination with w, h and c parameters, for example w_800,h_600,c_fill,wm_publitio.

For quality adjustment of images and videos, use the q parameter. This parameter represents the compression level to apply to images or videos as a value between 1 (smallest file size possible) and 100 (best visual quality). For example, to reduce the quality of the file version to 60, use q_60. You can use q in combination with w, h, c and wm as well, for example w_800,h_600,c_fill,wm_publitio,q_60.

To trim videos, use t (time), so (start offset) and eo (end offset) parameters.

For waveform generation of audio files, use the fc (foreground color) and bc (background color) parameters.

List Versions

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// List versions of file with id mytestfile
$response = $publitio_api->call('/files/versions/list/mytestfile', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/versions/list/mytestfile?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// List versions of file with id mytestfile
publitio.call('/files/versions/list/mytestfile', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_versions(file_id, limit=3)

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "limit": 100,
  "offset": 0,
  "versions_total": 2,
  "versions_count": 2,
  "versions": [
    {
      "id": "zoq6qNQy",
      "file_id": "RVsbVdyp",
      "extension": "mp4",
      "options": "",
      "size": 193136,
      "status": "ready",
      "url": "https://media.publit.io/file/RVsbVdyp.mp4",
      "hits": 14,
      "created_at": "2017-11-22 15:48:19",
      "updated_at": "2018-01-08 11:25:54"
    },
    {
      "id": "JR78dfTh",
      "file_id": "RVsbVdyp",
      "extension": "png",
      "options": "h_250,w_250",
      "size": 90711,
      "status": "ready",
      "url": "https://media.publit.io/file/h_250,w_250/RVsbVdyp.png",
      "hits": 0,
      "created_at": "2018-01-10 16:00:19",
      "updated_at": "2018-01-10 16:00:21"
    }
  ]
}

This endpoint lists all versions of a file.

HTTP Request

GET https://api.publit.io/v1/files/versions/list/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.
limit no int Maximum number of versions to return. Default is 100. Maximum limit is 1000.
offset no int How many files should be skipped at the beginning of the result set. Default is 0.
order no string How the versions should be ordered. Supported values are date, name, size and hits. You may also append :asc for an ascending sort order or :desc for a descending order (for example name:desc). By default, the versions are sorted by date in ascending order.
filter_status no string Specifies which versions should be returned based on their transformation status. Supported values are all, creating, ready and failed. Default is all.
filter_extension no string Specifies which versions should be returned based on their extension (output format). For the full list see supported extensions. Default is all.
cname no string Cname ID. Default is null.

Show Version

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Show file version with id zoq6qNQy
$response = $publitio_api->call("/files/versions/show/zoq6qNQy", "GET");
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/versions/show/zoq6qNQy?{{api_signature}}" \
-H "Accept: application/json"
// Download JavaScript SDK from https://github.com/ob1y2k/publitio_js_sdk

// Include SDK
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// show file version with id zoq6qNQy
publitio.call('/files/versions/show/zoq6qNQy', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show file version with id zoq6qNQy
publitio_api.show_version('zoq6qNQy')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "zoq6qNQy",
  "file_id": "RVsbVdyp",
  "extension": "mp4",
  "options": "",
  "size": 193136,
  "status": "ready",
  "url": "https://media.publit.io/file/RVsbVdyp.mp4",
  "hits": 14,
  "created_at": "2017-11-22 15:48:19",
  "updated_at": "2018-01-08 11:25:54"
}

This endpoint shows version info based on its ID.

HTTP Request

GET https://api.publit.io/v1/files/versions/show/<version_id>

Query Parameters

Parameter Required Type Description
id yes string Target version ID.
cname no string Cname ID. Default is null.

Update Version

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update file version with ID zoq6qNQy
$response = $publitio_api->call('/files/versions/update/zoq6qNQy', 'PUT');
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/files/versions/update/zoq6qNQy?{{api_signature}}" \
-H "Accept: application/json" 
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update file version with ID zoq6qNQy
publitio.call('/files/versions/update/zoq6qNQy', 'PUT')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update file version with ID zoq6qNQy
publitio_api.update_version('zoq6qNQy')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file version with id 'zoq6qNQy' has been updated"
}

This endpoint updates file version info based on its ID.

HTTP Request

PUT https://api.publit.io/v1/files/versions/update/<version_id>

Query Parameters

This call does not support any parameters at this moment.

Reconvert Version

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update file version with ID zoq6qNQy
$response = $publitio_api->call('/files/versions/reconvert/zoq6qNQy', 'PUT');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/versions/reconvert/zoq6qNQy?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update version with ID zoq6qNQy
publitio.call('/files/versions/reconvert/zoq6qNQy', 'PUT')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.reconvert_version('zoq6qNQy')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file version with id 'zoq6qNQy' has been re-converted"
}

This endpoint re-converts a file version based on its ID. Useful for re-creating failed versions.

HTTP Request

PUT https://api.publit.io/v1/files/versions/reconvert/<version_id>

Query Parameters

This call does not support any parameters at this moment.

Delete Version

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete file version with ID zoq6qNQy
$response = $publitio_api->call('/files/versions/delete/zoq6qNQy', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/files/versions/delete/zoq6qNQy?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')

// Delete file version with id zoq6qNQy
publitio.call('/files/versions/delete/zoq6qNQy', 'DELETE')
  .then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
rom publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete file version with id zoq6qNQy
publitio_api.delete_version('zoq6qNQy')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file version with id 'zoq6qNQy' has been deleted!"
}

This endpoint deletes a file version based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/files/versions/delete/<version_id>

Query Parameters

Parameter Required Type Description
id yes string Target version ID.

Folders

The Folders Class allows easy creation and management of a virtual folder structure. Folders are really optional, but you can benefit from their use, as they will become a part of your file URLs and allow you to use unique public_id's for your files.

Create Folder

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Create a new folder, with options name=MyFolder, parent_id=4vZsZBGa
$response = $publitio_api->call(
    '/folders/create', 'POST',
    array(
        'parent_id' => '4vZsZBGa',
        'name' => 'MyFolder'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/folders/create?{{api_signature}}" \
-H "Accept: application/json" \
--data parent_id="4vZsZBGa" \
--data name="MyFolder"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Create a new folder, with options name=MyFolder, parent_id=4vZsZBGa
publitio.call('/folders/create', 'POST', {
    parent_id: '4vZsZBGa',
    name: 'MyFolder'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.create_folder(name='MyFolder', parent_id='4vZsZBGa')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Folder 'Y2K/MyFolder' created",
  "id": "aLLov3Dr",
  "name": "MyFolder",
  "path": "Y2K/MyFolder",
  "parent_id": "4vZsZBGa",
  "created_at": "2019-01-23 10:24:18",
  "updated_at": "2019-01-23 10:24:18"
}

This endpoint creates a new folder.

HTTP Request

POST https://api.publit.io/v1/folders/create

Query Parameters

Parameter Required Type Description
name yes string Unique alphanumeric folder name.
parent_id no string Parent folder ID. Default is null (root folder).

List Folders

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
$response = $publitio_api->call('/folders/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/folders/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/folders/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_folders(order='name')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "parent_id": null,
  "parent_path": "/",
  "folders_count": 2,
  "folders": [
    {
      "id": "4vZsZBGa",
      "name": "Y2K",
      "path": "Y2K",
      "parent_id": null,
      "created_at": "2018-11-27 17:21:23",
      "updated_at": "2018-11-27 17:21:23"
    },
    {
      "id": "kMtns78W",
      "name": "Publitio",
      "path": "Publitio",
      "parent_id": null,
      "created_at": "2018-11-28 21:30:29",
      "updated_at": "2018-11-28 21:30:29"
    }
  ]
}

This endpoint lists folders.

HTTP Request

GET https://api.publit.io/v1/folders/list

Query Parameters

Parameter Required Type Description
parent_id no string Folder ID you wish to retrieve (sub) folders for. Default us null (root folder).
order no string How the folders should be ordered. Supported values are date and name. You may also append :asc for an ascending sort order or :desc for a descending order (for example name:desc). By default, the files are sorted by date in ascending order.
tags no string Search query tags separated by + signs. You can append :any to list folders which have any of the tags, or :all to list only folders which have all of the tags. Default mode is :all. For example, use dogs+cats:any to select files which either have the dogs or the cats tag.

Show Folder

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show folder with id zoq6qNQy
$response = $publitio_api->call('/folders/show/4vZsZBGa', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/folders/show/4vZsZBGa?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show folder with id 4vZsZBGa
publitio.call('/folders/show/4vZsZBGa', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show folder with id 4vZsZBGa
publitio_api.show_folder('4vZsZBGa')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "4vZsZBGa",
  "name": "Y2K",
  "path": "Y2K",
  "parent_id": null,
  "created_at": "2018-11-27 17:21:23",
  "updated_at": "2018-11-27 17:21:23"
}

This endpoint shows folder info based on its ID.

HTTP Request

GET https://api.publit.io/v1/folders/show/<folder_id>

Query Parameters

Parameter Required Type Description
id yes string Target folder ID.

Update Folder

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Update folder with id 4vZsZBGa
$response = $publitio_api->call('/folders/update/4vZsZBGa', 'PUT');
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/folders/update/4vZsZBGa?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update folder with id 4vZsZBGa
publitio.call('/folders/update/4vZsZBGa', 'PUT')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update folder with id 4vZsZBGa
publitio_api.update_folder('4vZsZBGa')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The folder with id '4vZsZBGa' has been updated"
}

This endpoint updates folder info based on its ID.

HTTP Request

PUT https://api.publit.io/v1/folders/update/<folder_id>

Query Parameters

Parameter Required Type Description
id yes string Target folder ID.
name no string Folder name. This name will become part of contained file paths (case-sensitive).

Delete Folder

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Delete folder with id 4vZsZBGa
$response = $publitio_api->call('/folders/delete/4vZsZBGa', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/folders/delete/4vZsZBGa?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete folder with id 4vZsZBGa
publitio.call('/folders/delete/4vZsZBGa', 'DELETE')
  .then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete folder with id 4vZsZBGa
publitio_api.delete_folder('4vZsZBGa')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The folder with id '4vZsZBGa' has been deleted!"
}

This endpoint deletes a folder based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/folders/delete/<folder_id>

Query Parameters

Parameter Required Type Description
id yes string Target folder ID.

Tree Folder

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');
$response = $publitio_api->call("/folders/tree", "GET");
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/folders/tree?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/folders/tree', 'GET')
  .then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.folders_tree()

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "folders_count": 2,
  "folders": [
    {
      "id": "4vZsZBGa",
      "name": "Y2K",
      "path": "Y2K"
    },
    {
      "id": "Xdx2p8ix",
      "name": "yo",
      "path": "Y2K/yo"
    }
  ]
}

This endpoint lists the entire folder tree.

HTTP Request

GET https://api.publit.io/v1/folders/tree

Query Parameters

This call does not support any parameters at this moment.

Players

Players Class allows easy creation and management of HTML5 Media Players that you can use to play/preview your files and versions.

Create Player

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Create player with id myplayer
$response = $publitio_api->call(
    '/players/create', 'POST',
    array(
        'name' => 'myplayer',
        'auto_play' => '0',
        'skin' => 'blue'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/players/create?{{api_signature}}" \
-H "Accept: application/json" \
--data name="myplayer" \
--data auto_play="0" \
--data skin="blue"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Create player with id myplayer
publitio.call('/players/create', 'POST', {
    name: 'myplayer',
    auto_play: '0',
    skin: 'blue'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Create player with id myplayer
publitio_api.create_player(name='myplayer')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Player with name (id) 'myplayer' created",
  "id": "myplayer",
  "auto_play": 0,
  "skin": "blue",
  "controls": "on",
  "quality": "480p",
  "thumbnails": "on",
  "muted": "off",
  "adtag_id": "",
  "created_at": "2018-01-10 14:56:52",
  "updated_at": "2018-01-10 14:56:52"
}

This endpoint creates a new HTML5 Media Player.

Player setup will affect both embed_url, source_html, iframe_html and player_html once passed to the File Player call.

HTTP Request

POST https://api.publit.io/v1/players/create

Query Parameters

Parameter Required Type Description
name yes string Unique alphanumeric player name (ID).
auto_play no int Auto-play content. Supported values are 0 (off), 1 (on) and 2 (onmouseover).
skin no string Player skin color. Valid values are blue, pink, green, grey, orange and inverted. Default is grey.
controls no boolean Controlbar visibility. Valid values are 0, 1, true and false. Default is 1 (true).
quality no int Default video quality. Valid values are 0 (360p), 1 (480p), 2 (720p) and 3 (1080p). Default is 0 (480p).
thumbnails no boolean Thumbnails preview on seekbar. Valid values are: 0, 1, true and false. Default is 1 (true).
muted no boolean Player is initially muted. This can be useful with auto-play videos. Valid values are: 0, 1, true and false. Default is 0 (false).
adtag_id no string ID of adtag to use with this player.

List Players

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');
$response = $publitio_api->call('/players/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/players/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/players/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_players()

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "players_count": 2,
  "players": [
    {
      "id": "myplayer",
      "auto_play": 0,
      "skin": "blue",
      "controls": "on",
      "quality": "480p",
      "thumbnails": "on",
      "muted": "off",
      "adtag_id": "",
      "created_at": "2017-11-29 17:50:36",
      "updated_at": "2017-11-29 17:50:36"
    },
    {
      "id": "publitio",
      "auto_play": 1,
      "skin": "grey",
      "controls": "on",
      "quality": "720p",
      "thumbnails": "on",
      "muted": "off",
      "adtag_id": "preroll",
      "created_at": "2017-12-19 10:26:15",
      "updated_at": "2017-12-19 10:26:15"
    }
  ]
}

This endpoint returns a list of all created players.

HTTP Request

GET https://api.publit.io/v1/players/list

Query Parameters

This call does not support any parameters at this moment.

Show Player

$publitio_api = \Publitio\API('<API Key>', '<API Secret>')
// Show player with id myplayer
$response = $publitio_api->call('/players/show/myplayer', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/players/show/myplayer?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show player with id myplayer
publitio.call('/players/show/myplayer', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show player with id myplayer
publitio_api.show_player('myplayer')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "myplayer",
  "auto_play": 0,
  "skin": "blue",
  "controls": "on",
  "quality": "720p",
  "thumbnails": "on",
  "muted": "off",            
  "adtag_id": "",
  "created_at": "2018-01-10 14:56:52",
  "updated_at": "2018-01-10 14:56:52"
}

This endpoint shows player info based on its ID.

HTTP Request

GET https://api.publit.io/v1/players/show/<player_id>

Query Parameters

Parameter Required Type Description
id yes string Target player ID.

Update Player

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update player with id mytestwm
$response = $publitio_api->call(
    '/players/update/myplayer',
    'PUT',
    array(
        'auto_play' => '2',
        'skin' => 'orange',
        'adtag_id' => 'myadtag'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/players/update/myplayer?{{api_signature}}" \
-H "Accept: application/json" \
--data auto_play="2" \
--data skin="orange" \
--data adtag_id="myadtag"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update player with id myplayer
publitio.call('/players/update/myplayer', 'PUT', {
    adtag_id: 'mypreroll',
    auto_play: '1'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
# Update player with id myplayer
publitio_api.update_player('myplayer', skin='green')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The player with name (id) 'myplayer' has been updated"
}

This endpoint updates player info based on its ID.

Player setup will affect both embed_url, source_html, iframe_html and player_html once passed to the File Player call.

HTTP Request

PUT https://api.publit.io/v1/players/update/<player_id>

Query Parameters

Parameter Required Type Description
id yes string Target player ID.
auto_play no int Auto-play content. Supported values are 0 (off), 1 (on) and 2 (onmouseover).
skin no string Player skin color. Valid values are blue, pink, green, grey, orange and inverted. Default is grey.
controls no boolean Controlbar visibility. Valid values are 0, 1, true and false. Default is 1 (true).
quality no int Default video quality. Valid values are 0 (360p), 1 (480p), 2 (720p) and 3 (1080p). Default is 0 (480p).
thumbnails no boolean Thumbnails preview on seekbar. Valid values are 0, 1, true and false. Default is 1 (true).
muted no boolean Player is initially muted. This can be useful with auto-play videos. Valid values are: 0, 1, true and false. Default is 0 (false).
adtag_id no string ID of adtag to use with this player.

Delete Player

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Delete player with id myplayer
$response = $publitio_api->call('/players/delete/myplayer', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/players/delete/myplayer?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete player with id myplayer
publitio.call('/players/delete/myplayer', 'DELETE')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete player with id myplayer
publitio_api.delete_player('myplayer')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The player with name (id) 'myplayer' has been deleted!"
}

This endpoint deletes a player based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/players/delete/<player_id>

Query Parameters

Parameter Required Type Description
id yes string Target player ID.

Adtags

Adtags Class (Sub-class of Players) allows easy creation and management of VAST/IMA ad tags that you can use with your players to monetize your files and versions with ads.

Create Adtag

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Create adtag with name (id) myadtag
$response = $publitio_api->call(
    '/players/adtag/create',
    'POST',
    array(
        'name' => 'myadtag',
        'tag' => 'https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator='
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/players/create?{{api_signature}}" \
-H "Accept: application/json" \
--data name="myadtag" \
--data tag="https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator="
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Create adtag with id myadtag
publitio.call(
    '/players/adtags/create',
    'POST', {
        name: 'myadtag',
        tag: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator='
    }
).then((data) => { console.log(data) })
 .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Create adtag with id myadtag
publitio_api.create_adtag(name='myadtag', tag='https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Adtag with name (id) 'myadtag' created",
  "id": "myadtag",
  "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator=",
  "created_at": "2018-01-10 15:26:01",
  "updated_at": "2018-01-10 15:26:01"
}

This endpoint creates a new VAST/IMA ad tag that you can later use with your players to monetize your files and versions with ads. You can get sample tags for testing at Google IMA Sample Tags.

HTTP Request

POST https://api.publit.io/v1/players/adtags/create

Query Parameters

Parameter Required Type Description
name yes string Unique alphanumeric adtag name (ID).
tag yes string Tag URL you wish to use. The Publitio Player supports VAST & Google IMA ad tags at the moment.

List Adtags

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
$response = $publitio_api->call('/players/adtags/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/players/adtags/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/players/adtags/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_adtags()

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "adtags_count": 2,
  "adtags": [
    {
      "id": "preroll",
      "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=",
      "created_at": "2017-12-19 10:23:51",
      "updated_at": "2017-12-19 10:23:51"
    },
    {
      "id": "myadtag",
      "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator=",
      "created_at": "2018-01-10 15:26:01",
      "updated_at": "2018-01-10 15:26:01"
    }
  ]
}

This endpoint returns a list of all created adtags.

HTTP Request

GET https://api.publit.io/v1/players/adtags/list

Query Parameters

This call does not support any parameters at this moment.

Show Adtag

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show adtag with id myadtag
$response = $publitio_api->call('/players/adtags/show/myadtag', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/players/adtags/show/myadtag?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show adtag with id myadtag
publitio.call('/players/adtags/show/myadtag', 'GET')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show adtag with id myadtag
publitio_api.show_adtag('myadtag')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "myadtag",
  "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator=",
  "created_at": "2018-01-10 15:26:01",
  "updated_at": "2018-01-10 15:26:01"
}

This endpoint shows adtag info based on its ID.

HTTP Request

GET https://api.publit.io/v1/players/adtags/show/<adtag_id>

Query Parameters

Parameter Required Type Description
id yes string Target adtag ID.

Update Adtag

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update adtag with id myadtag
$response = $publitio_api->call(
    '/players/adtags/update/myadtag',
    'PUT',
    array(
        'tag' => 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator='
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/players/adtags/update/myadtag?{{api_signature}}" \
-H "Accept: application/json" \
--data tag="https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator="
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update adtag with id myadtag
publitio.call('/players/adtags/update/myadtag', 'PUT', {
    tag: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator='
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update adtag with id myadtag
publitio_api.update_adtag(adtag_id, tag='myadtag')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The adtag with name (id) 'myadtag' has been updated"
}

This endpoint updates adtag info based on its ID.

HTTP Request

PUT https://api.publit.io/v1/players/adtags/update/<adtag_id>

Query Parameters

Parameter Required Type Description
id yes string Unique alphanumeric adtag name (ID).
tag no string Tag URL you wish to use. The Publitio Player supports VAST and Google IMA ad tags at the moment.

Delete Adtag

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete adtag with id myadtag
$response = $publitio_api->call('/players/adtags/delete/myadtag', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/players/adtags/delete/myadtag?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete adtag with id myadtag
publitio.call('/players/adtags/delete/myadtag', 'DELETE')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete adtag with id myadtag
publitio_api.delete_adtag('myadtag')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The adtag with name (id) 'myadtag' has been deleted!"
}

This endpoint deletes an adtag based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/players/adtags/delete/<adtag_id>

Query Parameters

Parameter Required Type Description
id yes string Target adtag id (name).

Watermarks

The Watermarks Class allows easy creation and management of watermarks that you can use to protect/copyright your uploaded files and versions.

Watermarks are used via URL-based transformations. To watermark a file or version, pass the wm option:

https://media.publit.io/file/wm_publitio/butterflies.jpg

You can learn more about applying watermarks here.

Create Watermark

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Create watermark from local file
$response = $publitio_api->upload_file(
    fopen('samples/smile.png'),
    'watermark',
    array(
        'name' => 'mytestwm',
        'position' => 'top-right',
        'padding' => '20'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/watermarks/create?{{api_signature}}" \
-H "Accept: application/json" \
--form name=mytestwm \
--form position=top-right \
--form padding=20 \
--form file=@/localpathtoimage/watermark.png
import PublitioAPI from 'publitio_js_sdk'
import { readFileSync } from 'fs'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// This could also be a ReadableStream in Node, a File in the browser or a string
const file = readFileSync('watermark.png')

// Create watermark from local file
publitio.uploadFile(file, 'watermark', {
    name: 'mytestwm',
    position: 'top-right',
    padding: '20'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.create_watermark(self, file=open('path/to/file', rb), title='whatever')
# The file needs to be opened for binary reading. This function will not close the file.

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Watermark created",
  "id": "mytestwm",
  "extension": "png",
  "width": 100,
  "height": 100,
  "size": 3198,
  "position": "top-right",
  "padding": 20,
  "url": "https://media.publit.io/watermark/c74i.png",
  "created_at": "2018-01-10 12:21:32",
  "updated_at": "2018-01-10 12:21:32"
}

This endpoint creates a new watermark that you can later use on files and versions in order to protect your images and videos. Right now you can upload png or jpg images as your watermarks and Publitio will securely store them for future use.

HTTP Request

POST https://api.publit.io/v1/watermarks/create

Query Parameters

Parameter Required Type Description
file yes file Image to upload as watermark (png and jpg images currently supported).
name yes string Unique alphanumeric name (ID) of watermark.
position no string Position of watermark, valid values are center, top-left, top, top-right, left, right, bottom-left, bottom, bottom-right. Default is bottom-right.
padding no int Padding in pixels (ignored when position is center). Default is 0.

List Watermarks

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
$response = $publitio_api->call("/watermarks/list", "GET");
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/watermarks/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/watermarks/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_watermarks()

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "watermarks_count": 2,
  "watermarks": [
    {
      "id": "publitio",
      "extension": "png",
      "width": 150,
      "height": 49,
      "size": 3388,
      "position": "top-right",
      "padding": 10,
      "url": "https://media.publit.io/watermark/69ty.png",
      "created_at": "2017-11-29 16:49:26",
      "updated_at": "2017-11-29 16:49:26"
    },
    {
      "id": "mytestwm",
      "extension": "png",
      "width": 100,
      "height": 100,
      "size": 3198,
      "position": "top-right",
      "padding": 20,
      "url": "https://media.publit.io/watermark/c74i.png",
      "created_at": "2018-01-10 12:21:32",
      "updated_at": "2018-01-10 12:21:32"
    }
  ]
}

This endpoint returns a list of all created watermarks.

HTTP Request

GET https://api.publit.io/v1/watermarks/list

Query Parameters

This call does not support any parameters at this moment.

Show Watermark

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show watermark with id mytestwm
$response = $publitio_api->call('/watermarks/show/mytestwm', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/watermarks/show/mytestwm?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show watermark with id mytestwm
publitio.call('/watermarks/show/mytestwm', 'GET')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show watermark with id mytestwm
publitio_api.show_watermark('mytestwm')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "mytestwm",
  "extension": "png",
  "width": 100,
  "height": 100,
  "size": 3056,
  "position": "top-right",
  "padding": 20,
  "url": "https://media.publit.io/watermark/c74i.png",
  "created_at": "2018-01-10 13:04:45",
  "updated_at": "2018-01-10 13:04:45"
}

This endpoint shows watermark info based on its ID.

HTTP Request

GET https://api.publit.io/v1/watermarks/show/<watermark_id>

Query Parameters

Parameter Required Type Description
id yes string Target watermark ID (name).

Update Watermark

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update watermark with id mytestwm
$response = $publitio_api->call(
    '/watermarks/update/mytestwm',
    'PUT',
    array(
        'position' => 'top-left',
        'padding' => '10'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/watermarks/update/mytestwm?{{api_signature}}" \
-H "Accept: application/json" \
--data padding="25" \
--data position="top-left"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update watermark with id mytestwm
publitio.call('/watermarks/update/mytestwm', 'PUT', {
   position: 'bottom-right',
   padding: '10'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update watermark with id mytestwm
publitio_api.update_watermark('mytestwm', position='left')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The watermark with name (id) 'mytestwm' has been updated"
}

This endpoint updates watermark info based on its ID.

HTTP Request

PUT https://api.publit.io/v1/watermarks/update/<watermark_id>

Query Parameters

Parameter Required Type Description
id yes string Target watermark ID.
position no string Watermark position, valid values are center, top-left, top, top-right, left, right, bottom-left, bottom, bottom-right. Default is bottom-right.
padding no int Padding in pixels (ignored if position is center). Default is 0.

Delete Watermark

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete watermark with id mytestwm
$response = $publitio_api->call('/watermarks/delete/mytestwm', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/watermarks/delete/mytestwm?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete watermark with id mytestwm
publitio.call('/watermarks/delete/mytestwm', 'DELETE')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete watermark with id mytestwm
publitio_api.delete_watermark('mytestwm')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The watermark with name (id) 'mytestwm' has been deleted!"
}

This endpoint deletes a watermark based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/watermarks/delete/<watermark_id>

Query Parameters

Parameter Required Type Description
id yes string Target watermark ID.

Errors

Most of the errors returned by the API would have a response body in the following form:

[
  {
    "success": false,
    "code": 404,
    "error": {
        "message": "The file with id 'RVsbVdyzp' doesn't exist"
    }
  }
]

The Publitio API might respond with the following HTTP response codes:

Error Code Meaning
400 Bad Request -- Your request sucks
401 Unauthorized -- Your API Signature is wrong
403 Forbidden -- The requested resource is hidden for private only
404 Not Found -- The requested resource could not be found
405 Method Not Allowed -- You tried to access a request with an invalid method
406 Not Acceptable -- You requested a format that isn't json
410 Gone -- The resource requested has been removed from our servers
429 Too Many Requests -- You're making to much requestis! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- Resource or service temporarially unavailable. Please try again later.