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

Create an account
Get API and Secret Keys at your Dashboard
Choose SDK or Framework for integration
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`.

All four API authentication parameters (api_key, api_timestamp, api_nonce and generated api_signature) must always be present in the API call.

API signature generation

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

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

<api_timestamp><api_nonce><api_secret>

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:

api_timestamp and api_nonce make sure that the API call signature is always unique.
API calls with timestamps that are over 1 hour old will be denied.
The API keeps a history of all call signatures for the last 48 hours. If a certain signature already exists in the history, the API call will be not executed.

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

Make sure you remove &api_test=true from your calls as soon as you are done with testing and ready to go into production.

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)

For images please use jpg, jpeg, png, gif, bmp, webp, svg and ico formats. You can also transcode images to mp4, webm and ogv video formats.
For videos use mp4, webm and ogv. You can also transcode videos to images via jpg, jpeg, png, gif, webp and bmp image formats. We also support video to audio transcoding via mp3, wav and ogg audio formats.
For audio use mp3, wav and ogg. You can also transcode audio to image files (waveforms) via jpg, jpeg, png, gif, webp and bmp image formats. We also support audio to video transcoding via mp4, webm and ogv video formats.
For documents use pdf. You can also transcode documents to image files via jpg, jpeg, png, gif, webp and bmp image formats.

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

Files will scale to new dimensions by default (as in the examples above), unless a different cropping mode is selected. See the example below for how to use the c (cropping) option.

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.

To apply watermarks to uploaded files by default, pass a wm_id parameter during the Create File call.

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

You can do image to image transcoding in following formats: jpg, jpeg, png, gif, bmp, webp, svg, ico.

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

You can do image to video transcoding in following formats: mp4, webm, ogv.

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

The t (time) option can be applied in video to image and document to image transformations. For documents, this option gets the requested page from the document.

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

Audio to video and image transformations accept w, h, wm (watermark), fc (foreground color) and bc (background color) parameters.

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')

{
  "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:

Images: jpg, jpeg, jpe, png, gif, bmp, psd, webp, ai, tif, tiff, svg and ico
Videos: mp4, webm, ogv, avi, mov, flv, 3gp, 3g2, wmv, mpeg and mkv
Audios mp3, wav, ogg, aac, aiff, amr, ac3, au, flac, m4a, aac, ra, voc and wma
Documents pdf

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 on the video file. Supported values are `0` (disabled), `1` (enabled).
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)

{
  "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')

{
  "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')

{
  "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 on the video file. Supported values are `0` (disabled), `1` (enabled).
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')

{
  "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')

{
  "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', ...)

{
  "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:

For images please use jpg, jpeg, png, gif, bmp and webp extensions. You can also transcode images to mp4, webm and ogv video formats.
For videos use mp4, webm and ogv. You can also transcode videos to jpg, jpeg, png, gif and webp image formats. We also support video to mp3, wav and ogg audio formats conversion.
For audio use mp3, wav and ogg. You can transcode audio files to jpg, jpeg, png, gif and webp image formats. We also support audio to mp4, webm and ogg video formats conversion.
For documents use pdf. We support document to image conversion with jpg, jpeg, png, gif, webp and bmp formats.

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).

c_fit: the file is resized so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible. For example, to resize an image or video to fit within a width and height of 300 pixels while retaining the aspect ratio, use w_300,h_300,c_fit.
c_limit: same as c_fit, but only if the original image is larger than the given limit (width and height), in which case the image 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. For example, to create a file version limited to a width and height of 300 pixels while retaining the aspect ratio use w_300,h_300,c_limit.
c_fill: create a file version with the exact given width and height while retaining the original aspect ratio, using only part of the original file that fills the given dimensions if necessary. For example, to create a file filled to a width and height of 250 pixels while retaining the aspect ratio use w_250,h_250,c_fill.

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.

t should be used for video to image transformation. For example, to get the image from 10th second of video, use t_10. It can also be used for document to image transformation, as described here.
so defines the time from which to start trimming the video, and is used in video to video transformation. For example, to cut off first 5 seconds of a video and save the rest of it as a new file version, use so_5.
eo defines how long (in seconds) the trimmed video should be. For example, to get a 10 second long video, starting from the 5th second, use so_5,eo_10.

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

fc should be used for audio to image transformation and it will set the waveform (foreground) color. For example, to create an image from audio with a blue waveform, use fc_blue. It will accept any HEX color as its value, or you can use common color names like blue, red, yellow, pink, green, black and white.
bc should be used for audio to image transformation and it will set the waveform (background) color. For example, to create an image from audio with a black background, use bc_black. It will accept any HEX color as its value, or you can use common color names like blue, red, yellow, pink, green, black and white.

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)

{
  "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')

{
  "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')

{
  "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')

{
  "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')

{
  "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')

{
  "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).

Folders are optional, and their names will become part of file URL structure, allowing more unique public_id's for your files.

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')

{
  "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')

{
  "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')

{
  "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')

{
  "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()

{
  "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')

{
  "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.

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

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()

{
  "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')

{
  "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')

{
  "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')

{
  "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=')

{
  "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.

Depending how you pass the tag parameter, you may need to URL encode it.

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()

{
  "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')

{
  "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')

{
  "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')

{
  "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).

This API call completely removes the adtag and will set the adtag_id of all players using it to null!

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.

{
  "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()

{
  "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')

{
  "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')

{
  "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')

{
  "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.

This API call completely removes the watermark! All files associated with it will have their wm_id set to null after this operation.

Errors

[
  {
    "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 is invalid.
401	Unauthorized — Your API Signature is invalid.
403	Forbidden — The requested resource is private.
404	Not Found — The requested resource could not be found.
405	Method Not Allowed — You tried to access an endpoint using an invalid method.
406	Not Acceptable — You requested a format that isn't JSON.
410	Gone — The requested resource has been removed from our servers.
422	Unprocessable Entity — Unable to process the contained instructions.
429	Too Many Requests — You're making too many requests! Slow down!
500	Internal Server Error — We had a problem with our servers. Please try again later.
503	Service Unavailable — Resource or service temporarily unavailable. Please try again later.