API Reference

REST is the foundation of the Adilo API. Our API uses standard HTTP response codes, authentication, and verbs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses predictable resource-oriented URLs

This guide will show you how to make use of the reference.

https://adilo-api.bigcommand.com/v1/

Authentication

To authenticate and obtain production data, you'll need both public and secret API keys.

Getting your API Keys

For authentication and getting data, production endpoints require an API key. Make sure to create and obtain your API key from the Adilo dashboard's API Keys section - https://adilo.bigcommand.com/settings/api

Using your API Keys

'X-Public-Key: my-public-key'
'X-Secret-Key: my-secret-key'
'Content-Type: application/json'

You can use your API Key to gain access to API Endpoints once you've received it.

It is important to keep your API Key safe from prying eyes.

REST APIs

Our REST APIs cover the following

Projects Create, update, delete, view, search, view files, view folders of projects.
Folders Create, update and delete folders.
Files Create, update, delete, replace, get meta and download files.
Users Create, update and delete users.
Subtitles Upload, generate and download subtitles.
Translation Generate and download translation.
Contacts Delete and download contacts.

                

Projects

Create Project

Information
Create new project for your current team

HTTP Request
POST https://adilo-api.bigcommand.com/v1/projects

Body

Parameter Type Description
title* String This is the title of the project
description String This is the description of the project
locked Boolean Whether the project should be locked, default is false.
drm Boolean Whether the project has drm, default is false.
private Boolean Whether the project is private, default is false.
password String Password for the project if locked.

Response

HTTP Status Explanation
200 OK The project was created
422 Unprocessed Entity The input data was invalid

List Projects

Information
List all projects of your current team

HTTP Request
GET https://adilo-api.bigcommand.com/v1/projects

Query Parameters

Parameter Type Description
From Integer The start filter of the results, default is 1
To Integer The amount of the results to fetch, default is 50

Response

HTTP Status Explanation
200 OK The projects were fetched

Update Project

Information
Update a project of your current team by it's id

HTTP Request
PUT https://adilo-api.bigcommand.com/v1/projects/{project_id}

Path Parameter

Parameter Type Description
project_id* String This is the ID of the project

Body

Parameter Type Description
Title String This is the title of the project
Description String This is the description of the project
Locked Boolean Whether the project should be locked, default is false.
Drm Boolean Whether the project has drm, default is false.
Private Boolean Whether the project is private, default is false.
Password String Password for the project if locked

Response

HTTP Status Explanation
200 OK The project was updated
403 Forbidden The action is not allowed
422 Unprocessed Entity The input data was invalid

Get Project By ID

Information
Get a project of your current team by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/projects/{project_id}

Path Parameter

Parameter Type Description
project_id* String This is the ID of the project

Response

HTTP Status Explanation
200 OK The project was fetched
403 Forbidden The action is not allowed

Delete Project

Information
Delete a project of your current team by it's id

HTTP Request
DELETE https://adilo-api.bigcommand.com/v1/projects/{project_id}

Path Parameter

Parameter Type Description
project_id* String This is the ID of the project

Response

HTTP Status Explanation
200 OK The project was deleted
403 Forbidden The action is not allowed

Search Project

Information
Search projects of your current team

HTTP Request
GET https://adilo-api.bigcommand.com/v1/projects/search/{string}

Path Parameter

Parameter Type Description
string* String This is the value to be searched for

Query Parameters

Parameter Type Description
From Integer The start filter of the results, default is 1
To Integer The amount of the results to fetch, default is 50

Response

HTTP Status Explanation
200 OK The related projects were fetched

Get Folders By Project ID

Information
Get project folders of your current team by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/projects/{project_id}/folders

Path Parameter

Parameter Type Description
project_id* String This is the ID of the project

Query Parameters

Parameter Type Description
From Integer The start filter of the results, default is 1
To Integer The amount of the results to fetch, default is 50

Response

HTTP Status Explanation
200 OK The project folders were fetched
403 Forbidden The action is not allowed

Get Files By Project ID

Information
Get project files of your current team by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/projects/{project_id}/files

Path Parameter

Parameter Type Description
project_id* String This is the ID of the project

Query Parameters

Parameter Type Description
From Integer The start filter of the results, default is 1
To Integer The amount of the results to fetch, default is 50

Response

HTTP Status Explanation
200 OK The project files were fetched
403 Forbidden The action is not allowed

Example request and response data

Create project request data


                

Create project response data


                

List projects request data


                

List projects response data


                

Folders

Create Folder

Information
Create new folder in a project

HTTP Request
POST https://adilo-api.bigcommand.com/v1/folders

Body

Parameter Type Description
Name* String This is the name of the folder
project_id* String This is the id of the project in which the folder is to be created
parent_id String This is the parent folder_id of the new folder, the new folder will be a sub folder of the parent

Response

HTTP Status Explanation
200 OK The folder was created
404 Not Found The project or parent folder not found
422 Unprocessed Entity The input data was invalid

Update Folder

Information
Update a folder in your project by it's id

HTTP Request
PUT https://adilo-api.bigcommand.com/v1/folders/{folder_id}

Path Parameter

Parameter Type Description
folder_id* String This is the ID of the folder to be updated

Body

Parameter Type Description
Name String This is the name of the folder
project_id String This is the id of the project in which the folder is to be created
parent_id String This is the parent folder_id of the new folder, the new folder will be a sub folder of the parent

Response

HTTP Status Explanation
200 OK The folder was updated
403 Forbidden The action is not allowed
422 Unprocessed Entity The input data was invalid

Get Folder By ID

Information
Get a project folder by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/folders/{folder_id}

Path Parameter

Parameter Type Description
folder_id* String This is the ID of the folder

Response

HTTP Status Explanation
200 OK The folder was fetched
403 Forbidden The action is not allowed

Delete Folder

Information
Delete a project folder by it's id

HTTP Request
DELETE https://adilo-api.bigcommand.com/v1/folders/{folder_id}

Path Parameter

Parameter Type Description
folder_id* String This is the ID of the folder

Response

HTTP Status Explanation
200 OK The project was deleted
403 Forbidden The action is not allowed

Example request and response data

Create folder request data


                

Create folder response data


                

List folders request data


                

List folders response data


                

Files

Create Video or Audio

Information
Create a new video or audio file in a project.
File upload is done using multipart upload, to upload a new file, the following steps should be followed:

  1. Initiate video upload
  2. Get a signed upload URL for each part of your video (Each part must be atleast 5mb, this rule doesn't apply to the last part)
  3. Complete the multipart upload

1. Initiate file upload

HTTP Request
POST https://adilo-api.bigcommand.com/v1/files/upload/start

Body

Parameter Type Description
filename* String This is the name of the file to be uploaded
filesize* Float This is the size in bytes of the file to be uploaded
duration_seconds* Integer This is the duration in seconds of the file to be uploaded
duration_string* String This is the duration in string of the file to be uploaded e.g "00:10:30" for a 10 minutes and 30 seconds video/audio
mime_type* String This is the mime type of the file e.g video/mp4, audio/mp3 e.t.c
project_id* String This is the id of the project to upload the file to
drm_protection* Boolean This deteremines if the video will have DRM protection

Response

HTTP Status Explanation
200 OK The file upload was initiated
403 Forbidden This action is not allowed
422 Unprocessed Entity The input data was invalid

2. Get a signed upload URL for each part of your video

HTTP Request
GET https://adilo-api.bigcommand.com/v1/files/upload/get-signed-url/{uploadId}/{partNumber}

Query Parameters

Parameter Type Description
key* String This is the file upload key

An upload URL is returned from this endpoint, this URL is used to upload the specified part of the file using a PUT method.
Here are some examples of how to upload a file/data using this url.

Response

HTTP Status Explanation
200 OK Signed URL generated
403 Forbidden This action is not allowed
422 Unprocessed Entity The input data was invalid

3. Complete file upload

HTTP Request
POST https://adilo-api.bigcommand.com/v1/files/upload/complete

Body

Parameter Type Description
key* String This is the key of the file upload
uploadId* String This is the uploadId of the file upload
parts* Array This is an array of parts of the file uploaded
parts.PartNumber* Array This is the part number
parts.ETag* String This is ETag gotten from the response header after uploading file part to signed Url

Response

HTTP Status Explanation
200 OK The file upload was completed
403 Forbidden This action is not allowed
422 Unprocessed Entity The input data was invalid

Update File

Information
Update a file in your project by it's id
To update a file, the following steps should be followed:

  1. Get a signed upload URL for file upload
  2. Complete the file upload

1. Get a signed upload URL for file upload

HTTP Request
GET https://adilo-api.bigcommand.com/v1/files/{file_id}/update/get-signed-url

Path Parameter

Parameter Type Description
file_id* String This is the ID of the file to be updated

Body

Parameter Type Description
filename* String This is the name of the file to be uploaded
filesize* Float This is the size in bytes of the file to be uploaded
duration_seconds* Integer This is the duration in seconds of the file to be uploaded
duration_string* String This is the duration in string of the file to be uploaded e.g "00:10:30" for a 10 minutes and 30 seconds video/audio
mime_type* String This is the mime type of the file e.g video/mp4, audio/mp3 e.t.c
drm_protection* Boolean This deteremines if the video will have DRM protection
clear_statistics Boolean This determines whether to clear the statistics of the file to update, default is false

Response

HTTP Status Explanation
200 OK Signed url generated
403 Forbidden The action is not allowed
422 Unprocessed Entity The input data was invalid

2. Complete the file update

HTTP Request
PUT https://adilo-api.bigcommand.com/v1/files/{file_id}/update/complete

Path Parameter

Parameter Type Description
file_id* String This is the ID of the file to be updated

Response

HTTP Status Explanation
200 OK File updated
403 Forbidden The action is not allowed
422 Unprocessed Entity The input data was invalid

Get File By ID

Information
Get a project file by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/files/{file_id}

Path Parameter

Parameter Type Description
file_id* String This is the ID of the folder

Response

HTTP Status Explanation
200 OK The file was fetched
403 Forbidden The action is not allowed

Delete File

Information
Delete a project file by it's id

HTTP Request
DELETE https://adilo-api.bigcommand.com/v1/files/{file_id}

Path Parameter

Parameter Type Description
file_id* String This is the ID of the file

Response

HTTP Status Explanation
200 OK The file was deleted
403 Forbidden The action is not allowed

Get Meta Data Of File

Information
Get a project file meta data by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/files/{file_id}/meta

Path Parameter

Parameter Type Description
file_id* String This is the ID of the file

Response

HTTP Status Explanation
200 OK The file meta data was fetched
403 Forbidden The action is not allowed

Download File

Information
Download a project file by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/files/{file_id}/download

Path Parameter

Parameter Type Description
file_id* String This is the ID of the file

Response

HTTP Status Explanation
200 OK The download urls were generated
403 Forbidden The action is not allowed

Upload Subtitle

Information
Upload subtitle for a project file by it's id

HTTP Request
POST https://adilo-api.bigcommand.com/v1/files/subtitle/upload

Body

Parameter Type Description
file_id* String This is the ID of the file
file* File This is the subtitle file to be uploaded
language* string This is the language of the subtitle file to be uploaded. Supported languages are English, Spanish, French, Chinese, Italian, Vietnamese, Portuguese, Arabic, German, Hindi, Javanese, Korean, Romanian, Polish, Irish, Dutch, Hebrew, Indonesian, Greek, Filipino, Czech, Thai, Urdu, Malay, Persian, Finnish, Turkish, Danish, Swedish"

Response

HTTP Status Explanation
200 OK The subtitle was uploaded
403 Forbidden The action is not allowed
422 Unprocessed Entity The input data was invalid

Generate Subtitle

Information
Generate subtitle for a project file by it's id

HTTP Request
POST https://adilo-api.bigcommand.com/v1/files/subtitle/generate

Body

Parameter Type Description
file_id* String This is the ID of the file
language* string This is the language of the subtitle file to be uploaded. Supported languages are English, Spanish, French, Chinese, Italian, Vietnamese, Portuguese, Arabic, German, Hindi, Javanese, Korean, Romanian, Polish, Irish, Dutch, Hebrew, Indonesian, Greek, Filipino, Czech, Thai, Urdu, Malay, Persian, Finnish, Turkish, Danish, Swedish"

Response

HTTP Status Explanation
200 OK The subtitle is generating
403 Forbidden The action is not allowed

Download Subtitle

Information
Download subtitle for a project file by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/files/{file_id}/subtitle/download

Path Parameter

Parameter Type Description
file_id* String This is the ID of the file

Response

HTTP Status Explanation
200 OK The subtitle download url was generated
403 Forbidden The action is not allowed
404 Not Found No subtitle found for this file

Generate Translation

Information
Generate translation for a project file by it's id

HTTP Request
POST https://adilo-api.bigcommand.com/v1/files/translation/generate

Body

Parameter Type Description
file_id* String This is the ID of the file
language* string This is the language of the subtitle file to be uploaded. Supported languages are English, Spanish, French, Chinese, Italian, Vietnamese, Portuguese, Arabic, German, Hindi, Javanese, Korean, Romanian, Polish, Irish, Dutch, Hebrew, Indonesian, Greek, Filipino, Czech, Thai, Urdu, Malay, Persian, Finnish, Turkish, Danish, Swedish"

Response

HTTP Status Explanation
200 OK The translation was generated
403 Forbidden The action is not allowed
404 Not Found No translation found for this language

Download Translation

Information
Download translation for a project file by it's id

HTTP Request
GET https://adilo-api.bigcommand.com/v1/files/{file_id}/translation/download

Path Parameter

Parameter Type Description
file_id* String This is the ID of the file

Query Parameters

Parameter Type Description
language* string This is the language of the subtitle file to be uploaded. Supported languages are English, Spanish, French, Chinese, Italian, Vietnamese, Portuguese, Arabic, German, Hindi, Javanese, Korean, Romanian, Polish, Irish, Dutch, Hebrew, Indonesian, Greek, Filipino, Czech, Thai, Urdu, Malay, Persian, Finnish, Turkish, Danish, Swedish"

Response

HTTP Status Explanation
200 OK The translation download url was generated
403 Forbidden The action is not allowed
404 Not Found No translation found for this language

Example request and response data

Initiate file upload request data


                

Initiate file upload response data


                

Get signed url for file upload request data


                

Get signed url for file upload response data


                

Complete file upload request data


                

Complete file upload response data


                

Get file update signed url request data


                

Get file update signed url response data


                

List files request data


                

List files response data


                

Get file meta response data


                

Download file response data


                

Users

Create User

Information
Create a new user for your team

HTTP Request
POST https://adilo-api.bigcommand.com/v1/users

Body

Parameter Type Description
name* String This is the name of the user
email* String This is the email of the user
password* String This is the password for the newly created user, this can be changed later by the user in their profile.
permissions* Array This is an array of permissions that the created user will have. Supported permissions are Create ProjectDelete ProjectUpload VideoCustomize VideoDelete VideoProject AnalyticsExperimentationCollaborationPlaylistsEdit StageView SnapsEdit SnapsDelete SnapsCreate SnapsRequest Snaps (Shared Snaps)View AnalyticsNotificationGlobal video settingsView IntergrationsAdd IntergrationsDelete IntergrationsView ChannelsAdd ChannelsEdit ChannelsDelete ChannelsView DomainsAdd DomainsEdit DomainsDelete DomainsView BrandsAdd BrandsEdit BrandsDelete BrandsView ContactsExport ContactsEdit ContactsDelete Contacts

Response

HTTP Status Explanation
200 OK The user was created
403 Forbidden This action is not allowed
422 Unprocessed Entity The input data was invalid

List Users

Information
List all users on your team

HTTP Request
GET https://adilo-api.bigcommand.com/v1/users

Query Parameters

Parameter Type Description
From Integer The start filter of the results, default is 1
To Integer The amount of the results to fetch, default is 50

Response

HTTP Status Explanation
200 OK The users were fetched

Get User By ID

Information
Get a user by ID

HTTP Request
GET https://adilo-api.bigcommand.com/v1/users/{user_id}

Path Parameters

Parameter Type Description
user_id* Integer This is the ID of the user

Response

HTTP Status Explanation
200 OK The user was fetched
403 Forbidden This action is not allowed

Update User

Information
Update a user on your team by ID

HTTP Request
PUT https://adilo-api.bigcommand.com/v1/users/{user_id}

Path Parameters

Parameter Type Description
user_id* Integer This is the ID of the user

Body

Parameter Type Description
name String This is the name of the user
email String This is the email of the user
password String This is the password for the newly created user, this can be changed later by the user in their profile.
permissions Array This is an array of permissions that the created user will have. Supported permissions are Create ProjectDelete ProjectUpload VideoCustomize VideoDelete VideoProject AnalyticsExperimentationCollaborationPlaylistsEdit StageView SnapsEdit SnapsDelete SnapsCreate SnapsRequest Snaps (Shared Snaps)View AnalyticsNotificationGlobal video settingsView IntergrationsAdd IntergrationsDelete IntergrationsView ChannelsAdd ChannelsEdit ChannelsDelete ChannelsView DomainsAdd DomainsEdit DomainsDelete DomainsView BrandsAdd BrandsEdit BrandsDelete BrandsView ContactsExport ContactsEdit ContactsDelete Contacts

Response

HTTP Status Explanation
200 OK The user was updated
403 Forbidden This action is not allowed
422 Unprocessed Entity The input data was invalid

Delete User

Information
Delete a user by ID

HTTP Request
DELETE https://adilo-api.bigcommand.com/v1/users/{user_id}

Path Parameters

Parameter Type Description
user_id* Integer This is the ID ≥≥÷of the user

Response

HTTP Status Explanation
200 OK The user was deleted
403 Forbidden This action is not allowed

Example request and response data

Create user request data


                

Create user response data


                

List users request data


                

List users response data


                

Contacts

List Contacts

Information
List all contacts

HTTP Request
GET https://adilo-api.bigcommand.com/v1/contacts

Query Parameters

Parameter Type Description
From Integer The start filter of the results, default is 1
To Integer The amount of the results to fetch, default is 50

Response

HTTP Status Explanation
200 OK The contacts were fetched

Get Contact By ID

Information
Get a contact by ID

HTTP Request
GET https://adilo-api.bigcommand.com/v1/contacts/{contact_id}

Path Parameters

Parameter Type Description
contact_id* Integer This is the ID of the contact

Response

HTTP Status Explanation
200 OK The contact was fetched
403 Forbidden This action is not allowed

Delete Contact

Information
Delete a user by ID

HTTP Request
DELETE https://adilo-api.bigcommand.com/v1/contacts/{contact_id}

Path Parameters

Parameter Type Description
contact_id* Integer This is the ID of the contact

Response

HTTP Status Explanation
200 OK The contact was deleted
403 Forbidden This action is not allowed

Download Contacts

Information
Download all contacts

HTTP Request
GET https://adilo-api.bigcommand.com/v1/contacts/download

Response

HTTP Status Explanation
200 OK The download URL was generated
403 Forbidden This action is not allowed

Example request and response data

List contacts response data


                

Examples

How to upload your file using a presigned url

Information
Our API only generates a signed (upload) url, that signed url is a link to our storage. You will need to upload your files (in binary format) to our storage through that url.

Example upload url
Below is an example of the returned upload/signed url.
PUT https://adilo-encoding.s3.us-east-2.wasabisys.com/mjhvjgftrFGgdf/gCdSgSsu/gCdSgSsu.mp3?partNumber=1&uploadId=3oj4R1F8tyjrns82scnorAfwR4E2jF2YtEsPA34TK8opZXSj3V3gKsOLL7BF1gddshgdssRHs4l8ui0OnPKip9Im7DZizPwi_EGFw4dn70wydOaaTidl0JDR4yq9R58nMQk6jI8M&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=B3HSNGHP0MKECQHXBMdsfsaea22%f2F20220124%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20220124T053944Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1200&X-Amz-Signature=0be0b1dfbd24215b0d872960ed5a71e4ac7b3704d33b6cb294d52a304a9c1132

Please note that this example is a reference to step 2 of how to create video or audio.

Example request

PHP


                

Node.js


                

HTML Form input with Fetch API


                  

                

Video Player

With Adilo Video player, you get access to the following

Player Current Time This shows how much of the current video a visitor has seen.

Get Player Current Time

Current Time

Information
Adilo video In other to determine how much of a video a user has seen. To achieve this, we emit a postMessage periodically to show the watch progress of the video.

Sample Code

Errors

HTTPS Errors are any requests with a response status code other than 200 (successful HTTP) that must be treated as API call failures. You should anticipate more JSON in the body of the response, with the error message enclosed inside it.

400 - Bad Request There's a problem with your request, which might be caused by an incorrect argument.
401 - Unauthorized Your API keys are incorrect/invalid due to a lack of proper authentication credentials.
403 - Forbidden The request was denied owing to a lack of permission. This resource is not accessible because your API does not have sufficient rights or credits.
404 - Not Found You asked for a specific item that we don't have right now.
409 - Conflict Vivamus rhoncus dui vitae eros tristique cursus (dui vitae eros tristique cursus).
422 - Unprocessable Entity This indicates that the server understands the request entity's content type and that the request entity's syntax is accurate, but that it was unable to process the instructions contained inside.
429 - Too Many Requests Slow down, you are sending too many requests
500, 502, 503, 504 - Server Errors An unexpected server error was encountered, and we're working to resolve it.