API Reference

iconik uses a REST API to make it easy to create, update and delete resources entities.

The APIs

If you want to try and use the interactive documentation please make sure that you have a token and an App-ID key that you can use. You can find out how to set that up here.

iconik /API/Resource List

acls/
Access Control List for Groups, Users, Shares and Objects
assets/
Assets, Collections, Delete Queue and associated sub-resources
auth/
Authentication, SAML, Apps and System Domain
files/
Files, Formats, Storage and Transcoders
jobs/
Jobs
metadata/
Metadata, Metadata Views and Metadata on Objects
notifications/
Webhook definitions
search/
Search, Discovery, Saved Searches and associated sub-resources
settings/
Settings
stats/
Statistics
transcode/
Create & Cancel Transcodes, AI and Keyframe Jobs
users/
Users, Groups and associated sub-resources

When you visit the links above to the API you will get the list of endpoints. Each end point can be clicked on to get more information and try the API out.

Important URL information

Each resource in above linked documentation will show it sub-resources, for example clicking on the auth/ link will show information for everything under the resource auth/. To build the complete URI you must concatenate the API endpoint API/ with the resource you are using ( e.g. auth/), and the associated sub-resource.

/API/auth/v1/auth/simple/login/ would make the complete URN for the resource for POSTing email and password for logging in a user.

Versioning

Each API is versioned. v1/ contains Version 1 of the API.

New versions of the API that signicantly change the API call parameters and/or response document will sequentially raise the version number.

Minor changes, and currently, additions to the existing API such as a new end-point will not generate a new API version.

Full URI

A full URI to an end point will be made up of scheme://iconik.url/API/resource/version/subresource/

Please try and always use https as the schema type

QueryString parameters

Some end points accept querystring parameters, examples of this are listing and searching which typically take ?page= and ?per_page= parameters. These should come after the end slash.

The querystring parameters are documented under each resource and sub-resource, as well as the expected parameter type and data type.

Recommend REST Clients

This is our un-official recommendations for testing our REST API:

Request Document

The iconik API expects JSON payloads in request bodies. Set Content-Type: application/json.

Visit the API documentation for a full list of what a request document could consist of and whether certain parameters are optional or not.

Response Document

The iconik API uses JSON to send its response when making an API call with Content-Type: application/json.

Using the interactive API documentation will shows a typical response what to an API call.

The response codes that you can expect are also listed in the documentation.

Swagger Definition file

Please visit our page about swagger on how you can use the definition files in your API programs and development.

Specification

Here is some more detailed information about the REST API:

General HTTP Headers

App-ID
Required: The application ID you wish to use to authenticate.
Auth-Token
Required: Your private application token
Host
The application server that iconik is running against
Content-Type
Required: application/json

HTTP Status codes

End-point documentation will show more precise definition of the codes.

200
Success
202
Success and created
204
Success and deleted
400
Bad request
401
Token you used is invalid
403
Permission denied
404
Entity not found
409
Already exists

Overview of Supported HTTP Verbs

Not all end-points support every verb, so please visit the API documentation to see which you can use.

GET
Get information about a given entity, resource, or a list of resources.
POST
Create a new entity under the given resource end-point.
DELETE
Delete a resource.
PUT
Replace all information about an entity with the given payload
PATCH
Partially modify the resource with the given payload