KZO API

KZO's RESTful Video and Collaboration Platform API, version 1.0

Base URI

https://tenant.kzoplatform.com/api
Parameters
created_by
string optional

Filtering by creator's username with partial matching

Example:
admin
created_at_from
string optional

Filtering by creation time. Specifies beginning of inclusive time interval using ISO8601 standard. If not set, it means from the beginning of time.

Example:
2012-10-10T14:12:24.324Z
created_at_to
string optional

Filtering by creation time. Specifies end of inclusive time interval using ISO8601 standard. If not set, it means until the end of time.

Example:
2013-10-10T14:12:24.324Z
modified_by
string optional

Filtering by last modifier's username with partial matching

Example:
bob
modified_at_from
string optional

Filtering by modification time. Specifies beginning of exclusive time interval using ISO8601 standard. If not set, it means from the beginning of time.

Example:
2012-10-10T14:12:24.324Z
modified_at_to
string optional

Filtering by modification time. Specifies end of exclusive time interval using ISO8601 standard. If not set, it means until the end of time.

Example:
2013-10-10T14:12:24.324Z
deleted_by
string optional

Filtering by deleter's username with partial matching

Example:
bob
deleted_at_from
string optional

Filtering by deletion time. Specifies beginning of exclusive time interval using ISO8601 standard. If not set, it means from the beginning of time.

Example:
2012-10-10T14:12:24.324Z
deleted_at_to
string optional

Filtering by deletion time. Specifies end of exclusive time interval using ISO8601 standard. If not set, it means until the end of time.

Example:
2013-10-10T14:12:24.324Z
unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
include
string optional

Parameter to specify which associated entities shoud be returned by method. For example: users, containers, groups etc. Parameters are joined with comma.

Example:
media,containers,created_by
Headers
Content-Length
number required

Indicates the size of the entity-body.

Content-Type
string required

Indicates the media type of the entity-body. Must be in the form application/vnd.api+json

If-Match
string optional

This should contain the version of the resource to be updated. The version is found from the response headers ETag when the resource was originally created (POST) or queried by the client (GET), or when the client queried metadata on the resource (HEAD). If provided, the current version of the resource must match for the action to proceed.

Host
string required

Specifies the Internet host and port number of the resource being requested.

X-KZO-API-Version
string required

Specifies API version. For details, see API Version.

X-KZO-Auth-AccessKey
string required

Access Key used by the API caller to authenticate against the server. For details, see Authentication and Authorization.

X-KZO-Auth-DelegateGroupId
number optional

Specifies ID of the Group on behalf of which the method should be executed. For details, see Authentication and Authorization.

X-KZO-Auth-DelegateUsername
string optional

Specifies username of the User on behalf of which the method should be executed. For details, see Authentication and Authorization.

X-KZO-Auth-Username
string required

Username used by the API caller to authenticate against the server. For details, see Authentication and Authorization.

X-KZO-Pipeline-Action
string optional

Used to initiate special actions related to pipeline processing on a pipeline-enabled entity or an entity managed by a pipeline of its parent entity. For more details, see Workflow.

X-KZO-Tenant
string required

Specifies name of the Tenant to which the request is issued. For details, see Tenant Management.

Content-Length
number required

Indicates the size of the entity-body.

Content-Type
string required

Indicates the media type of the entity-body. Must be in the form application/vnd.api+json

ETag
number required

Contains the version of the resource being returned.

Location
string optional

Contains the URI of the newly created resource.

X-KZO-API-Version
string required

Specifies API version. For details, see API Version.

X-KZO-Available-API-Versions
string optional

Specifies comma-separated list of API versions available on the server. For details, see API Version.

Responses
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

401 Unauthorized

The request requires Authentication and Authorization.

Adding User to Group Copying Medium Creating Comment Creating Container Creating Group Creating Medium Creating Original Video Creating Permission Creating Platform Access Key Creating Property Creating Reply to Reply Creating Session Access Key Creating Session Access Key: Password Authentication Creating Slide Deck Creating Top-Level Container Creating Used Slide Creating User Creating Viewed Fragment For Medium Delete favorite Deleting Access Key Deleting Container Deleting Group Deleting Medium Deleting Permission Deleting Property Deleting Used Slide Deleting User Deleting User from Group Favorite container Favorite medium Get favorite Get favorites Incremental reordering of descendant playlist entries for container Reordering Children of a Container Replacing Container Replacing Group Replacing Medium Replacing Property Replacing Used Slide Replacing User Replacing Viewed Fragment Searching Capabilities Searching Containers Searching Content Searching Groups Searching Media Searching Montage Options Searching Permissions Searching Roles Searching Screenshot Options Searching Users Searching Video Rendition Options Updating Container Updating Group Updating Medium Updating Used Slide Updating User Viewing Access Key Viewing Asset Viewing Available Properties Viewing Avatar Viewing Capability Viewing Chapter Viewing Comment Viewing Container Viewing Group Viewing Immediate Child Containers Viewing Medium Viewing Montage Viewing Montage Option Viewing Multiple Assets Viewing Multiple Chapters Viewing Multiple Comments Viewing Multiple Containers Viewing Multiple Groups Viewing Multiple Media Viewing Multiple Montages Viewing Multiple Replies Viewing Multiple Screenshots Viewing Multiple Used Slides Viewing Multiple Users Viewing Multiple Video Renditions Viewing Own Administrative Roles Viewing Permission Viewing Property Viewing Reply Viewing Role Viewing Screenshot Viewing Screenshot Option Viewing Slide Viewing Topmost Available Containers Viewing User Viewing Video Rendition Viewing Video Rendition Option
404 Not Found

The server has not found anything matching the Request-URI.

405 Method Not Allowed

The client executed method which is not available on the given resource (see also error 409)

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

408 Request Timeout

Reported by the server in a situation when processing of the API request included request to external resource, and that request times out.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

412 Precondition Failed

The tag specified in If-Match header did not match.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

428 Precondition Required

The client failed to specify If-Match header for PUT request.

Documentation
JSON API

The KZO REST API follows the emerging JSON API specification. JSON API is an attempt to formalize similar ad hoc client-server interfaces that use JSON as an interchange format. It is specifically focused around using those APIs with a smart client that knows how to cache documents it has already seen and avoid asking for them again.

The object returned by the API typically contains the following members:

  1. Top-level primary object -- either a single resource or a collection of resources of the primary entity being requested, keyed by the name of that entity.
  2. Top-level meta -- meta-information about the response object, such as pagination.
  3. Top-level linked -- a collection of flattened collections of resource objects, grouped by object type, that are linked to the primary resource(s) and/or each other (i.e. "linked resource(s)")
  4. Resource-level id -- resource identifier, typically an integer (User is the only entity where username serves as identifier).
  5. Resource-level href -- URI of a resource.
  6. Resource-level links -- linked resources, keyed by the name of each association.
  7. Resource-level meta -- meta-information about a resource object, such as its pipeline status and available actions.

For more information please refer to the JSON API format

API Version

API is versioned according to the specification of Semantic Versioning. Stable versions are specified as M.m.p. Patch versions p introduce bug fixes, minor versions m introduce non-breaking changes, major versions M introduce breaking changes. Several versions of the API may be deployed on the server simultaneously. Information related to API versioning is communicated via custom headers.

Request must specify API version or version range acceptable to the client:

X-KZO-Accept-API-Versions: M1[.m1][-][M2[.m2]]

Patch levels cannot be specified in requests. The requested API version can be specified as a number, meaning a request for a specific major or major-and-minor version, or as a range, and the range may be open-ended on one or both ends. Omission of any of the 4 numbers from the requested version is treated as placing no restrictions on that number (i.e., zero on the lower end and infinity on the uppper end). Either both major and minor version or only major version can be specified for each end. The server determines which of the deployed API versions satisfies the request, and if match is found, the latest of matching versions is used to process the request. If no match is found, error 406 is returned.

Response specifies the actual API version being used to respond:

X-KZO-API-Version: M.m.p

Additionally, response provides a comma-separated list of API versions deployed on the server:

X-KZO-Available-API-Versions: M1.m1.p1[, M2.m2.p2, ...]

Examples:

X-KZO-Accept-API-Versions: 1
X-KZO-Accept-API-Versions: 1.2
X-KZO-Accept-API-Versions: 1.3-1
X-KZO-Accept-API-Versions: 1.3-2.4
X-KZO-Accept-API-Versions: 1-
X-KZO-Accept-API-Versions: -1.2
X-KZO-Accept-API-Versions: -
X-KZO-API-Version: 1.1.5
X-KZO-Available-API-Versions: 1.1.5, 2.2.4

Unless the API client has specific requirements for the API version, it is recommended to request the latest available minor version of the current major version, i.e.:

X-KZO-Accepts-API-Versions: 1
REST Verbs

GET: Used for retrieving resources. Safe and idempotent method.

HEAD: Itentical to GET, except that the server is not returning entity-body in the response. Can be used to "preflight" the request. Safe and idempotent method.

OPTIONS: Supported for compatibility reasons. For the list of actions available on the resource, see Workflow. Safe and idempotent method.

POST: Used for creating new resources. Unsafe and non-idempotent method.

PATCH: Used for updating select attributes for a resource. For example, a Medium object has multiple attributes, such as title and description. PATCH methods implement a subset of JSON Patch specification, namely, multiple invocations of the only method, replace. See http://jsonpatch.com/ for details. ETag header is optional for PATCH, but if provided, it is honored. Unsafe method. The current (limited) implementation makes it idempotent method.

PUT: Used for replacing resources entirely. Any missing attributes will either trigger an error (if they are required), or set the attribute's value to null (if they are optional). ETag header is mandatory for PUT. Unsafe and idempotent method.

DELETE: Used for deleting resources. Unsafe and idempotent method.

Domain Terminology

TBD

Tenancy

KZO Platform is a multi-tenant application. It means that each partner of KZO (Tenant of the KZO Platform) for which an account is set up on a given Installation of KZO Platform, is allocated a logically separate area of the database to store its data, with independent ranges of IDs of all resources.

Each Tenant is identified with a name, which is communicated to the partner at the time its account is created. When an API request is made by API client, Tenant name must be specified via mandatory header:

X-KZO-Tenant: tenant-name
Authentication and Authorization

All communication between the API server and client is always happening over HTTPS. There is no provision for request signature.

Access Control

To be able to execute most API methods, the API client is required to have specific Capabilities. For example, to be able to view media belonging to a given container, the API user is required to have a capability VIEW_CONTENT on that container. Another example: to be able to manage users, the API user is required to have a capability MANAGE_ACCESS on the root container (Capabilities which can only be assigned to root Container are marked root_only). Capabilities are grouped into Roles. Users are grouped into Groups.

Note: as the API is changing over time, the following things may change without advance notice: the set of Capabilities available by the Platform, access rights provided by any given Capability, sets of Capabilities comprising any given Role. Such changes are not considered breaking changes for the API because access rights provided by Roles will never be reduced, they can only grow. API clients should consider Role as an assignable unit of information related to access control. Capabilties are technical entities closely tied to the current implementation state of the Platform. Capabilities and Roles available on the Platform are listed below in the end of this section.

Access to containers is inherited on the Container hierarchy. It means that if a given User has specific access to a given Container, that User will have the same access to all children Containers of that Container, which are connected to its parent via links of types ORIGINAL and FULL_REFERENCE. If the method in question is of the viewer type (property viewerOnly=true, indicated in the description of each method) then in addition to the above, the user will have the same access to all children Containers of that Container, which are connected to its parent via links of type VIEW_ONLY_REFERENCE. For more information, see Content Structure in Migrating from the SOAP API.

Access is managed via Permissions. A permission is comprised of three references: to a container, to a group, and to a role. A given permission therefore gives all Capabilities which the given Role is comprised of on the given Container to all Users of the given Group.

Authorization

The client authorizes itself with an Access Key, which it typically receives from the server at the time of authentication. There are two types of keys: SESSION or PLATFORM. They both expire automatically. SESSION key expires after a certain period of inactivity, 5 hours by default (can be changed on Tenant level). PLATFORM key expires at a specific time, set at the time of its creation. Session key can be created by an unauthenticated user using various authentication methods provided by the Platform, e.g., via password authentication method.

There are no limits on a number of simultaneously active SESSION or PLATFORM Access Keys for any given User.

Authorization is implemented via the following mandatory request headers:

X-KZO-Auth-Username: <username>
X-KZO-Auth-AccessKey: <accessKey>

where

  1. <username> is a username of the API user,
  2. <accessKey> is a 32-symbol alphanumeric access key, returned by one of authetication methods.

Methods which do not require prior authorization will ignore these headers.

Authentication

To obtain an Access Key, the API user must first call one of available access key creation methods, see method group Authentication.

To logout, the API user must delete his active Access Key, see method Deleting Access Key.

Delegated access

The API user can execute requests on behalf of other Users or Groups. To be able to do it, she must have a special Capability. For instance, in order for delegated access to a method which requires capability MANAGE_CONTENT to be granted, the following conditions must satisfy:

  1. the User executing the request must have the Capability DELEGATE_MANAGE_CONTENT,
  2. the User/Group on whose behalf the request is being executed must have Capability MANAGE_CONTENT,
  3. if the request is executed on behalf of a Group, the given method must also have a property delegateGroup=true (indicated in the description of each method).

Delegated access can be requested via one of the following optional headers:

X-KZO-Auth-DelegateUsername: <username>
X-KZO-Auth-DelegateGroupId: <group_id>

which specifies either User or Group, on behalf of which the request should be executed.

Errors

If a request which requires authentication is performed without specifying valid credentials, error 401 is returned. If a request which requires authentication is performed with valid credentials but access rigths of the User are deemed insufficient for the requested action, error 403 will be returned.

Capabilities

Here is the list of Capabilities available on the Platform:

  1. [root_only] MANAGE_TENANT
  2. [root_only] DELEGATE_MANAGE_TENANT
  3. [root_only] MANAGE_INSTALLATION
  4. [root_only] DELEGATE_MANAGE_INSTALLATION
  5. [root_only] MANAGE_IDENTITIES
  6. [root_only] DELEGATE_MANAGE_IDENTITIES
  7. [root_only] MANAGE_INTEGRATION_VISITORS_IDENTITIES
  8. [root_only] DELEGATE_MANAGE_INTEGRATION_VISITORS_IDENTITIES
  9. [root_only] VIEW_IDENTITIES
  10. [root_only] DELEGATE_VIEW_IDENTITIES
  11. [root_only] CREATE_TOP_LEVEL_CONTAINERS
  12. [root_only] DELEGATE_CREATE_TOP_LEVEL_CONTAINERS
  13. MANAGE_ACCESS
  14. DELEGATE_MANAGE_ACCESS
  15. CREATE_CONTENT
  16. DELEGATE_CREATE_CONTENT
  17. CREATE_CONTENT_RECORD_MEDIA
  18. DELEGATE_CREATE_CONTENT_RECORD_MEDIA
  19. CREATE_CONTENT_UPLOAD_MEDIA
  20. DELEGATE_CREATE_CONTENT_UPLOAD_MEDIA
  21. CREATE_CONTENT_COPY_MEDIA
  22. DELEGATE_CREATE_CONTENT_COPY_MEDIA
  23. CREATE_CONTENT_CONTAINERS
  24. DELEGATE_CREATE_CONTENT_CONTAINERS
  25. UPDATE_CONTENT
  26. DELEGATE_UPDATE_CONTENT
  27. DELETE_CONTENT
  28. DELEGATE_DELETE_CONTENT
  29. VIEW_CONTENT
  30. DELEGATE_VIEW_CONTENT
  31. COMMENT_REPLY
  32. DELEGATE_COMMENT_REPLY
  33. MANAGE_AUTHORSHIP
  34. DELEGATE_MANAGE_AUTHORSHIP

Capabilities *_CONTENT allow User to perform respective actions on Containers, Playlist Entries, Media and everything below Media.

Capability MANAGE_ACCESS allow User to manage other user's Permissions on Container on which they are assigned. E.g., if MANAGE_ACCESS is given to a User on a non-root Container, it allow that User to manage Capabilities *_CONTENT and MANAGE_ACCESS for any Group on that Container or below on Container hierarchy. If MANAGE_ACCESS is assigned to a User on a root Container, it allows that User to manage all Capabilities for any Group on all Containers.

Capability MANAGE_IDENTITIES allows User to manage Users, Groups, Group Membership, Access Keys for Users of all authentication_types.

Capability MANAGE_INTEGRATION_VISITORS_IDENTITIES allows User to manage Users, Group Membership, Access Keys for Users of authentication_type=INTEGRATION_VISITOR.

Capability VIEW_IDENTITIES allows User to view Users, Groups, Group Membership.

Capability MANAGE_INSTALLATION allows User to manage Tenants on privileged Tenant.

Capability MANAGE_TENANT allows User to do various administrative tasks not in Container context.

Capability COMMENT_REPLY allows User to create Comments and Replies (other actions with them are managed by the respective capabilities *_CONTENT).

Capability CREATE_TOP_LEVEL_CONTAINERS allows User to create top-level containers (children of root Container) without giving her any other access. In particular, it does not allow her to view the root Container itself.

Roles

Here is the list of Roles available on the Platform, along with Capabilities comprising them:

  1. [root_only] SUPERUSER: MANAGE_TENANT, DELEGATE_MANAGE_TENANT, MANAGE_INSTALLATION, DELEGATE_MANAGE_INSTALLATION, MANAGE_IDENTITIES, DELEGATE_MANAGE_IDENTITIES, VIEW_IDENTITIES, DELEGATE_VIEW_IDENTITIES, CREATE_TOP_LEVEL_CONTAINERS, DELEGATE_CREATE_TOP_LEVEL_CONTAINERS, MANAGE_ACCESS, DELEGATE_MANAGE_ACCESS, VIEW_CONTENT, DELEGATE_VIEW_CONTENT, CREATE_CONTENT, DELEGATE_CREATE_CONTENT, RECORD_CONTENT, DELEGATE_RECORD_CONTENT, CREATE_CONTAINERS, DELEGATE_CREATE_CONTAINERS. UPDATE_CONTENT, DELEGATE_UPDATE_CONTENT, DELETE_CONTENT, DELEGATE_DELETE_CONTENT, COMMENT_REPLY, DELEGATE_COMMENT_REPLY, UPDATE_CONTENT_AUTHORED_BY
  2. [root_only] INSTALLATION_MANAGER: MANAGE_INSTALLATION
  3. [root_only] INSTALLATION_MANAGER_DELEGATOR: DELEGATE_MANAGE_INSTALLATION
  4. [root_only] IDENTITY_MANAGER: VIEW_IDENTITIES, MANAGE_IDENTITIES
  5. [root_only] IDENTITY_MANAGER_DELEGATOR: DELEGATE_VIEW_IDENTITIES, DELEGATE_MANAGE_IDENTITIES
  6. [root_only] IDENTITY_VIEWER: VIEW_IDENTITIES
  7. [root_only] IDENTITY_VIEWER_DELEGATOR: DELEGATE_VIEW_IDENTITIES
  8. [root_only] INTEGRATION_VISITOR_IDENTITY_MANAGER: VIEW_IDENTITIES, MANAGE_INTEGRATION_VISITORS_IDENTITIES
  9. [root_only] INTEGRATION_VISITOR_IDENTITY_MANAGER_DELEGATOR: DELEGATE_VIEW_IDENTITIES, DELEGATE_MANAGE_INTEGRATION_VISITORS_IDENTITIES
  10. [root_only] TOP_LEVEL_CONTAINER_CREATOR: CREATE_TOP_LEVEL_CONTAINERS
  11. [root_only] TOP_LEVEL_CONTAINER_CREATOR_DELEGATOR: DELEGATE_CREATE_TOP_LEVEL_CONTAINERS
  12. ACCESS_MANAGER: VIEW_CONTENT, MANAGE_ACCESS
  13. ACCESS_MANAGER_DELEGATOR: DELEGATE_VIEW_CONTENT, DELEGATE_MANAGE_ACCESS
  14. CONTENT_MANAGER: VIEW_CONTENT, CREATE_CONTENT, UPDATE_CONTENT, DELETE_CONTENT, COMMENT_REPLY, CREATE_TOP_LEVEL_CONTAINERS, RECORD_CONTENT, CREATE_CONTAINERS, UPDATE_CONTENT_AUTHORED_BY
  15. CONTENT_MANAGER_DELEGATOR: DELEGATE_VIEW_CONTENT, DELEGATE_CREATE_CONTENT, DELEGATE_UPDATE_CONTENT, DELEGATE_DELETE_CONTENT, DELEGATE_COMMENT_REPLY, DELEGATE_CREATE_TOP_LEVEL_CONTAINERS, DELEGATE_RECORD_CONTENT, DELEGATE_CREATE_CONTAINERS, DELEGATE_UPDATE_CONTENT_AUTHORED_BY
  16. CONTENT_CREATOR: VIEW_CONTENT, CREATE_CONTENT, RECORD_CONTENT, CREATE_CONTAINERS
  17. CONTENT_CREATOR_DELEGATOR: DELEGATE_VIEW_CONTENT, DELEGATE_CREATE_CONTENT, DELEGATE_RECORD_CONTENT, DELEGATE_CREATE_CONTAINERS
  18. CONTENT_CREATOR_UPLOAD_MEDIA: VIEW_CONTENT, CREATE_CONTENT (hidden=true)
  19. CONTENT_CREATOR_UPLOAD_MEDIA_DELEGATOR: DELEGATE_VIEW_CONTENT, DELEGATE_CREATE_CONTENT (hidden=true)
  20. CONTENT_CREATOR_RECORD_MEDIA: VIEW_CONTENT, RECORD_CONTENT (hidden=true)
  21. CONTENT_CREATOR_RECORD_MEDIA_DELEGATOR: DELEGATE_VIEW_CONTENT, DELEGATE_RECORD_CONTENT (hidden=true)
  22. CONTENT_CREATOR_CONTAINERS: VIEW_CONTENT, CREATE_CONTAINERS (hidden=true)
  23. CONTENT_CREATOR_CONTAINERS: DELEGATE_VIEW_CONTENT, DELEGATE_CREATE_CONTAINERS (hidden=true)
  24. CONTENT_UPDATER: VIEW_CONTENT, UPDATE_CONTENT
  25. CONTENT_UPDATER_DELEGATOR: DELEGATE_VIEW_CONTENT, DELEGATE_UPDATE_CONTENT
  26. CONTENT_DELETER: VIEW_CONTENT, DELETE_CONTENT
  27. CONTENT_DELETER_DELEGATOR: DELEGATE_VIEW_CONTENT, DELEGATE_DELETE_CONTENT
  28. CONTENT_VIEWER: VIEW_CONTENT
  29. CONTENT_VIEWER_DELEGATOR: DELEGATE_VIEW_CONTENT
  30. COMMENTATOR: COMMENT_REPLY
  31. COMMENTATOR_DELEGATOR: DELEGATE_COMMENT_REPLY
  32. AUTHORSHIP_MANAGER: VIEW_CONTENT, MANAGE_AUTHORSHIP
  33. AUTHORSHIP_MANAGER_DELEGATOR: DELEGATE_VIEW_CONTENT, DELEGATE_MANAGE_AUTHORSHIP
Workflow

Pipelines

Some entities on the Platform are "pipeline-enabled", meaning that CUD operations on them are performed by passing them through a pipeline of transitions programmed in a specifc way. The primary purpose of such formalization is to simplify customization of the processing of resources by the API users, for instance, to be able to easily add custom authentication, email notification at different stages of processing, integration with external systems of the client's IT infrastructure, etc.

The following entites are pipeline-enabled:

  • Container,
  • Medium,
  • User,
  • Group,
  • Comment,
  • Reply,
  • Access Key,
  • Metrics Datum,
  • Original Video,
  • Slide Deck.

Pipelines of Slide Deck and Original Video are dependent on pipeline of Medium. Chapters and Used Slides do not have their own pipelines and are managed directly by the pipeline of Medium.

Resources can have one of the following statuses while they are traversing their pipelines:

  1. EDITING -- the resource is in the process if being edited by the admin end user,
  2. PROCESSING -- the resource's editing by the end user is over, it is now in the state of pipeline processing, which may include editing by the admin,
  3. READY -- the resource's processing is over, it is available to all end users, including non-admins, according to their permissions,
  4. ERROR -- the resource's processing is not over, but the resource is in the state of error, from which it could not be recovered without user intervention.
  5. DELETED -- the resource is deleted (it only used for Users, Comments and Replies, other deleted resources are not shown).

The current status of the pipeline-enabled resource is listed in meta.piepline_status.

Transitioning between statuses is done either automatically (i.e., performed by pipeline) or manually by suppying the header of X-KZO-Pipeline-Action as part of the requested method call:

  1. From EDITING to EDITING: by executing API methods of editing type (PUT, PATCH, create subodrinate resources, etc).
  2. From EDITING to PROCESSING: by specifying X-KZO-Pipeline-Action: Process, the processing by pipeline will be started.
  3. From PROCESSING to EDITING or to READY: by specifying X-KZO-Pipeline-Action: Cancel all changes made to the resource are canceled and the resource is returned to READY if it has been published before or to EDITING if it has never been published before.
  4. From PROCESSING to READY: by pipeline, when processing is complete.
  5. From any status to ERROR: by pipeline, when the requested action or automatic processing could not be performed.
  6. From ERROR to EDITING: by specifying X-KZO-Pipeline-Action: Revise, therefore acknowledging that the pipeline-enabled resource was in the status ERROR and the API user wants to revise its state.
  7. From any status to DELETED: by calling Deletion method on the resource

Actions Available for Resources

Actions available for any resource (pipeline-enabled or not) at any given time are listed in its representation as an array meta.actions, an action per array element. Every action is keyed with label, provides an URL and HTTP method to be used on it. Further details, such as query string parameters, can be found in this docuemtnation. This list is the authoritative source of information on what a given user can do with the resource, given her access level and, for pipeline-enabled resources, current status of the resource.

For entites without associated pipelines, this list does not change over time but still depends on user's access level.

Workflow for Pipeline-Enabled Entities

The typical workflow is to

  1. Create the resource by calling its Creation method.
  2. Edit it, if necessary, by methods PUT, PATCH, by creating child resources if they exist for the given piepeline-enabled resource (e.g., create Chapters as part of editing of the object Medium).
  3. Start processing by specifying header X-KZO-Pipeline-Action: Process. It can be performed either together with the last action from item (2), on the pipeline-enabled resource itself or on its subordinate resource, or as a separate empty (with body {}) PATCH request can be called on the resource with this header set.
  4. Wait until the resource is processed and is transitioned to the state READY by the piepeline.
  5. If the resource is found in the status ERROR instead, check the error objects in the array meta.pipeline_errors and transition the resource back to status EDITING by specifying X-KZO-Pipeline-Action: Revise, the proceed starting with item (2) above.
Migrating from the SOAP API

Migrating from the SOAP API

SOAP -> REST

Those currently using the SOAP based API will notice a number of significant differences. First, we've switched from SOAP to REST, which means SOAP methods are no longer used, and instead content is accessed via resource endpoints (/containers/23423) and actions performed on those resources are done using HTTP verbs (GET, POST, DELETE, etc).

Content Structure

The content structure has been modified to provide more flexibility. Previously all content was organized into a fixed 3 level hierarchy:

Courses > Lectures > Parts (often referred to as Communities > Playlists > Videos).

The REST API simplified this into Containers and Media. Containers can contain other containers as well as Media and can be nested as deep or as shallow as makes sense for your application.

By default, the system ships with a root container which serves as a parent to all Containers and Media created.

In addition to parent-child relationship of Containers, it is also allowed to share Containers, i.e. to mark Containers as effective children of other Containers, residing in other parts of the Container hierarchy. It allows to share subtrees of content with different branches of the Container hierarchy without copying it. Hence in the Container hierarchy, Containers can be connected by three types of links:

  1. ORIGINAL -- this is the original parent-child link, created together with the child Container. It cannot be removed in any way other than by deleting the child Container.
  2. FULL_REFERENCE -- this link imitates ORIGINAL link in a sense that all access rights are inherited from the "shared parent" Container to its "shared child" Container. This link can be added and removed via API.
  3. VIEW_ONLY_REFERENCE -- this link restricts access to the "shared child" to only viewing-type actions. I.e., if a given User has administrative rights to the "shared parent" Container, those rights do not apply to its "shared child". This link can be added and removed via API.

The latter two types of links are namaged by methods Creating Full Reference, Creating View-Only Reference, Deleting References. See also Access Control in Authentication and Authorization.

Migrating existing content to version 5

When upgrading to version 5, your existing content will automatically be converted into the newer schema, while preserving your existing content structure. This means that we will keep your three-level hierarchy as it is, and simply update the references accordingly. By preserving your existing hierarchy, upgrading to the new API will be completely transparent to your users.

Example:

Course 1 > Lecture 2 > Part 3

will become:

Container 1 > Container 2 > Medium 3

SOAP -> REST update examples

The following are examples showing a SOAP call, and it's newer, updated REST call. SOAP methods requiring an AuthVO as the first argument have been removed in the following examples for brevity.

ContentService

getCourses()
In order to request all containers available to the user, the following method is provided:

GET https://tenant.kzoplatform.com/containers/top

getCourseDetails(courseId)
Requesting information about a course is the same as requesting the container:

GET https://tenant.kzoplatform.com/containers/:containerId

deleteCourse(courseId)

DELETE https://tenant.kzoplatform.com/containers/:containerId

UMService (User Management)

addRegularUser(user)

POST https://tenant.kzoplatform.com/users

{
  "users": {
    "first_name": "Wes",
    "last_name": "Cruver",
    "username": "wescruver",
    "password": "s3cr3t"
  }
}

deleteUser(userId)

DELETE https://tenant.kzoplatform.com/users/:username
Conditional Requests

Not implemented yet.

JSONP Callbacks

Not implemented yet.

We implement page-based pagination for primary resources of some endpoints and some to-many relationships. It's intended to decrease both response time and response size.

Pagination of primary resources

To paginate over primary resources, an API user can use the following parameters:

  1. page_size_primary is the maximum number of primary resources are to be returned. Default value is 20.
  2. page is the number of page. Default value is 1.

Suppose an API user searches some content, ordered by some criteria, and N of them are relevant to search criteria.

  1. If N is greater than or equal to page * page_size_primary, no primary resources are returned.
  2. Otherwise API skips page * page_size_primary and returns max{page_size_primary, N - page * page_size_primary} primary resources.

Note that we never paginate primary resources for endpoints intended to request specific ones by identifiers.

Endpoints that don't support pagination of primary resources ignore page and page_size_primary.

When primary resources are paginated, pagination object is included in the root meta of response. It contain the following fields:

  1. total_results (integer) - the total number of primary resources. So many resources would be included in response if we didn't use pagination at all.
  2. links is an object containing the following links: first, last, prev, next. prev and/or next can be null if there are no previous/next page.

Pagination of relationships

An API user can limit the maximum number of related resources included in response for some to-many relationships. This can be done with a request parameter page_size_related (default value is 10). For instance, when fetching containers with include=media, each container will be linked with no more than page_size_related media in response.

Endpoints that don't support pagination of relationships ignore page_size_related.

If some relationships of a primary resource can be paginated, meta of the primary resource object included in response contains pagination object with pagination links objects (see pagination links for primary resources) named so as the respective relationship. For instance: {containers: [{id: 123, meta: {pagination: {media: {total_results: 0, ...}}}}]}

Error Reporting

Response meta information may contain information on media or it's subordinates processing errors.

In case when something went wrong while resource processing state object included in the meta of response may contain non blank error_code and error_message fields together with pipeline_status equal to ERROR:

  • pipeline_status - status of entity, in case of error will take 'ERROR' value, that allows error_code and error_message to have not blank values
  • error_code - unique numeric code of error
  • error_message - detailed description of error

When pipeline_status holds value different from ERROR then error_code and error_message are not returned.

Example of meta with error:

 "meta": {
    ...
    "state": {
        ...
        "pipeline_status": "ERROR",
        "error_code": 16033651,
        "error_message": "Slide deck file type incorrect: txt"
    }
}
API Methods
Authentication
GET /access_keys/{key}
POST /access_keys/session
POST /access_keys/platform
DELETE /access_keys/{key}
Viewing Access Key
GET /access_keys/{key}

Viewing access key resource.

For details, see Authentication and Authorization.

The method also returns the list of Roles returned by the method Viewing Own Administrative Roles as users.roles.

User executing this request must either have permission MANAGE_IDENTITIES or the key must be his own.

Path variables

key
string required

The access key

Example:
cf8ac35eca7977f9e6a05f4d7e8f4ff7

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: created_by.modified_by,users,users.roles, users.created_by,users_modified_by. Object users refers to the User for whom the key is issued.
Object roles refers to Own Administrative Roles.

Example:
roles

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/access_keys/cf8ac35eca7977f9e6a05f4d7e8f4ff7 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_keys": {
        "id" : "12345",
        "type" : "SESSION",
        "key" : "cf8ac35eca7977f9e6a05f4d7e8f4ff7",
        "http_user_agent" : "Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; rv:11.0) like Gecko",
        "ip_v4" : "173.74.130.253",
        "published" : true,
        "expires_at" : "2012-10-10T15:12:24Z",
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "href" : "https://tenant.kzoplatform.com/api/access_keys/12345",
        "links" : {
            "created_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "modified_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "users": "admin"
        },
        "meta": {
            "actions": [{
                "label": "ACCESS_KEY___DELETE",
                "href" : "https://tenant.kzoplatform.com/api/access_keys/12345",
                "method" : "DELETE"
            }],
            "pipeline_status": "READY",
            "pipeline_resource": {
                "href" : "https://tenant.kzoplatform.com/api/access_keys/12345",
                "type": "access_keys"
            }
        }
    },
    "linked": {
        "users": [{
            "id": 2,
            "username": "admin",
            "links": {
                "roles": [ 2, 3 ]
                ...
            }
            ...
        }],
        "roles": [{
            "id": 2
            ...
        },{
            "id": 3
            ...
        }]
    },
    "meta": {}
}
Creating Session Access Key
POST /access_keys/session

Creates a session access key.

User executing this request must have permission MANAGE_IDENTITIES. For details, see Authentication and Authorization.

The response is returned as if include=created_by.modified_by,users,users.created_by,users_modified_by,users.roles were set.

Request body

Object
access_keys
Object
username
string

User's login

browser_session_id
string

Id of browser's session, to sync authentication requests

Examples

Request to create session key for user with username = user1 from browser session with id AAAA-FFFF

{
    "access_keys": {
        "username": "user1",
        "browser_session_id": "AAAA-FFFF"
    }
}

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

404 Not Found

In case of miss of browser's session with passed id (browser_session_id).

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Access Key.

POST https://tenant.kzoplatform.com/api/access_keys/session HTTP/1.1 

Content-Type: application/json

{
    "access_keys": {
        "username" : "admin"
    }
}
Creating Session Access Key: Password Authentication
POST /access_keys/password

Used by an API client to authenticate with username and password and establish a session. For details, see Authentication and Authorization.

Does not require the User to be authenticated.

The response is returned as if include=created_by.modified_by,users,users.created_by,users_modified_by,users.roles were set.

Request body

Object
access_keys
Object
username
string

User's login

password
string

User's password

browser_session_id
string

Id of browser's session, to sync authentication requests

Examples

Request to create user session for user with username=user1 who has password password1 from session of browser with id AAA_FFF.

{
    "access_keys": {
        "username": "user1",
        "password": "password1",
        "browser_session_id": "AAA_FFF"
    }
}

Responses

201 Created
Headers
Location
string optional

Contains the URI of the newly created resource.

401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

404 Not Found

In case of miss of browser's session with passed id (browser_session_id).

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Access Key.

POST https://tenant.kzoplatform.com/api/access_keys/password HTTP/1.1 

Content-Type: application/json

{
    "access_keys": {
        "username" : "admin",
        "password" : "myCrypticPassw0rd"
    }
}
Creating Session Access Key for Public Access
POST /access_keys/public

Does not require the User to be authenticated. As a result of the method execution, the caller will be authenticated as user anonymous.

Requires public access to be enabled for the given Tenant.

The response is returned as if include=created_by.modified_by,users,users.created_by,users_modified_by,users.roles were set.

Request body

Object
access_keys
Object
browser_session_id
string

Id of browser's session, to sync authentication requests

Examples

Request to create the session for anonymous user from browser's session with id = 'AAA_FFF'.

{
    "access_keys": {
        "browser_session_id": "AAA_FFF"
    }
}

Responses

201 Created
403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

404 Not Found

In case of miss of browser's session with passed id (browser_session_id).

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

No request body is expected for this request.

The response is the same as that of the method Viewing Access Key.

POST https://tenant.kzoplatform.com/api/access_keys/public HTTP/1.1 
Creating Platform Access Key
POST /access_keys/platform

Creates a platform access key.

User executing this request must have permission MANAGE_IDENTITIES. For details, see Authentication and Authorization.

The response is returned as if include=created_by.modified_by,users,users.created_by,users_modified_by,users.roles were set.

Request body

Object
access_keys
Object
username
string

Username

Example:
admin
expires_at
string date

Date when platform key will expired. Required field.

Example:
2014-10-10T14:13:24.000Z

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

POST https://tenant.kzoplatform.com/api/access_keys/platform HTTP/1.1 

Content-Type: application/json

{
    "access_keys": {
        "username" : "admin",
        "expires_at" : "2014-10-10T14:13:24.000Z"
    }
}
Deleting Access Key
DELETE /access_keys/{key}

Deletes access key, so that user session associated with it becomes invalid.

For session Access Keys, requires either Permission assigning Role IDENTITY_MANAGER, or the key to be owned by the the User calling this method. For platform Access Keys, requires Permission assigning Role IDENTITY_MANAGER. For details, see Authentication and Authorization.

Path variables

key
string required

The Access Key.

Example:
cf8ac35eca7977f9e6a05f4d7e8f4ff7

Responses

204 No Content
401 Unauthorized

The request requires Authentication and Authorization.

200 OK
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/access_keys/cf8ac35eca7977f9e6a05f4d7e8f4ff7 HTTP/1.1 
Containers

Containers are abstract objects that can either contain media (such as videos) or other containers to form a hierarchy. All media created must belong to a container.

Only one root container is allowed, which is created automatically during the tenant creation process. Therefore, all containers created through the API must belong to another container.

GET /containers/{id}
GET /containers/{ids}
GET /containers
POST /containers/{id}/container
POST /containers/root/container
PUT /containers/{id}
PATCH /containers/{id}
DELETE /containers/{id}
POST /containers/{id}/meta/order
GET /playlist/{id}
GET /containers/{id}/containers
GET /containers/{id}/media
GET /containers/{id}/playlist_entries
Viewing Container
GET /containers/{id}

Fetch a container with a given ID.

Requires Permission assigning Role VIEWER on the given Container.

Pagination: containers, media.

This endpoint supports 2 output modes of operation: the normal and the proxy ones.

The normal mode is used when child containers and/or media are requested (see parameter include) as containers and media, respectively. In this mode:

  1. links in container objects contain unordered sets media and containers, containing direct links to corresponding child media and containers, respectively.
  2. Order of child containers and media is represented by meta.order of the container object.
  3. Child containers and media are two separate relationships, so their paginations are independent from each other.

The proxy mode is used when child containers and/or media are requested (see parameter include) as playlist_entries.container and playlist_entries.medium, respectively. In this mode:

  1. links in container objects contain arrays playlist_entries, containing links to proxy objects linked.playlist_entries.
  2. Each element of linked.playlist_entries is a link to the corresponding container/medium.
  3. Order of child containers and media is represented by the order of links to the corresponding proxy objects in links.playlist_entries of the container object.
  4. Child containers and media are considered as a single heterogeneous collection, with the pagination across this collection.

Note that if modes are mixed up in include, 400 This endpoint can be used either in normal or in proxy mode. will be returned. This applies also to subordinate relationships of containers and media. For example, if media are requested in the proxy mode (playlist_entries.medium), their slide decks should be, too (playlist_entries.medium.slide_deck).

Path variables

id
number required

The id of container

Example:
1

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
child_depth
number optional

Depth of the heirarchy of Container resources to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no children are included, value -1 means the full hierarchy is included. Default value is 0.

Example:
1
parent_depth
number optional

Depth of the heirarchy of Container resources up from the given Container (using only links of type ORIGINAL) to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no parent are included, value -1 means the full hierarchy is included. Default value is 0. For the topmost Container, no parent is specified.

Example:
1
include
string optional

Comma-separated list of associated objects which should be included in the response. Applicable to all levels of the hierarchy but the deepest one. Default value: empty. What can be included at most in the normal mode: parent,containers,media,containers.modified_by,containers.created_by, media.modified_by,media.created_by,media.slide_deck,media.parent,containers.authored_by,media.authored_by,media.closed_captions_sets,media.closed_captions_sets.languages,favorites,favorites.containers,favorites.media,favorites.created_by,media.favorites,media.favorites.media,media.favorites.created_by,containers.favorites,containers.favorites.containers,containers.favorites.created_by. What can be included at most in the proxy mode: parent,playlist_entries.container,playlist_entries.medium,playlist_entries.container.modified_by,playlist_entries.container.created_by,playlist_entries.medium.modified_by,playlist_entries.medium.created_by,playlist_entries.medium.slide_deck,playlist_entries.medium.parent,playlist_entries.container.authored_by,playlist_entries.medium.authored_by,playlist_entries.medium.closed_captions_sets,playlist_entries.medium.closed_captions_sets.languages,favorites,favorites.containers,favorites.media,favorites.created_by,playlist_entries.medium.favorites,playlist_entries.medium.favorites.media,playlist_entries.medium.favorites.created_by,playlist_entries.container.favorites,playlist_entries.container.favorites.containers,playlist_entries.container.favorites.created_by Inclusion of Containers is also controlled by parameters parent_depth and child_depth. Use include=parent to fill respective link for all primary and linked containers. Use include=media.parent to fill respective link for all linked media.

Example:
media
page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10
preauth_actions
boolean optional

Whether to include actions to get and play container by unauthenticated users. The URLs of actions will contain temporal access key.

Default:
false

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/containers/14 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "containers": {
        "id" : "14",
        "title" : "Yep, this is title",
        "description" : "My description",
        "root" : false,
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "comment_notification": true,
        "href": "https://tenant.kzoplatform.com/api/containers/14",
        "screenshot_href": "http://d6mgdbc2kfx06.cloudfront.net/...",
        "links" : {
            "created_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "modified_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "parent": {
                "id": 12,
                "type": "containers"
            },
            "containers": [2, 3, 4],
            "media": [5, 6]
        },
        "meta": {
            "collective": {
                "views": 234958,
                "trt_msec": 38522000,
                "media_count": 24,
                "container_count": 6
            },
            "actions": [{
                "label": "CONTAINER___GET",
                "href" : "https://tenant.kzoplatform.com/api/containers/14",
                "method" : "GET"
            },{
                "label": "CONTAINER___EDIT_METADATA",
                "href" : "https://tenant.kzoplatform.com/api/containers/14",
                "method" : "PATCH"
            },{
                "label": "CONTAINER___UPDATE",
                "href" : "https://tenant.kzoplatform.com/api/containers/14",
                "method" : "PUT"
            }],
            "order": {
                "containers": {
                    "0": 2,
                    "2": 3,
                    "3": 4
                },
                "media": {
                    "1": 6,
                    "4": 5
                }
            },
            "pipeline_status": "EDITING",
            "pipeline_resource": {
                "href": "https://tenant.kzoplatform.com/api/containers/14",
                "type": "containers"
            }
        },
        "thumbnails": null
    },
    "linked": {
        "containers": [{
            "id": 2,
            "links": {
                "containers": [20, 30],
                "media": [200, 300]
                ...
            },
            "meta": {
                "order": {
                    "containers": {
                        "1": 30,
                        "2": 20
                    },
                    "media": {
                        "0": 200,
                        "3": 300
                    }
                }
                ...
            }
            ...
        }, {
            "id": 3,
            "links": {
                "containers": [50],
                "media": [500]
                ...
            },
            "meta": {
                "order": {
                    "containers": {
                        "1": 50
                    },
                    "media": {
                        "0": 500
                    }
                }
                ...
            }
            ...
        }, {
            "id": 4,
            "links": {
                "containers": [],
                "media": []
                ...
            },
            "meta": {
                "order": {
                    "containers": {},
                    "media": {}
                }
                ...
            }
            ...
        }, {
            "id": 20,
            "links": {
                "containers": [],
                "media": []
                ...
            },
            "meta": {
                "order": {
                    "containers": {},
                    "media": {}
                }
                ...
            }
            ...
        }, {
            "id": 30,
            "links": {
                "containers": [],
                "media": []
                ...
            },
            "meta": {
                "order": {
                    "containers": {},
                    "media": {}
                }
                ...
            }
            ...
        }, {
            "id": 50,
            "links": {
                "containers": [],
                "media": []
                ...
            },
            "meta": {
                "order": {
                    "containers": {},
                    "media": {}
                }
                ...
            }
            ...
        }, {
            "id": 20,
            "links": {
                "containers": [],
                "media": []
                ...
            },
            "meta": {
                "order": {
                    "containers": {},
                    "media": {}
                }
                ...
            }
            ...
        }, {
            "id": 12,
            "links": {
                "containers": [],
                "media": []
                ...
            },
            "meta": {
                "order": {
                    "containers": {
                        "0": 12
                    },
                    "media": {}
                }
                ...
            }
            ...
        }],
        "media": [{
            "id": 5
            ...
        }, {
            "id": 6
            ...
        }, {
            "id": 200
            ...
        }, {
            "id": 300
            ...
        }, {
            "id": 500
            ...
        }],
        "users": [{
            "id": 1,
            "username": "admin"
            ...
        }]
    },
    "meta": {}
}
GET https://tenant.kzoplatform.com/api/containers/14?parent_depth=-1&child_depth=-1&include=parent,playlist_entries.container,playlist_entries.medium HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "containers": {
        "id" : "14",
        "title" : "Yep, this is title",
        "description" : "My description",
        "root" : false,
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "comment_notification": true,
        "href": "https://tenant.kzoplatform.com/api/containers/14",
        "screenshot_href": "http://d6mgdbc2kfx06.cloudfront.net/...",
        "links" : {
            "created_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "modified_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "parent": {
                "id": 12,
                "type": "containers"
            },
            "containers": [],
            "media": [],
            "playlist_entries": ["C_2", "M_6", "C_3", "C_4", "M_5"]
        },
        "meta": {
            "pagination": {
                "playlist_entries": {
                    "total_results": 5,
                    "links": {
                        "first": "https://tenant.kzoplatform.com/api/containers/14/playlist_entries?page=1&page_size_primary=10000&page_size_related=10000",
                        "last": "https://tenant.kzoplatform.com/api/containers/14/playlist_entries?page=1&page_size_primary=10000&page_size_related=10000"
                    }
                }
            },
            "collective": {
                "views": 234958,
                "trt_msec": 38522000,
                "media_count": 24,
                "container_count": 6
            },
            "actions": [{
                "label": "CONTAINER___GET",
                "href" : "https://tenant.kzoplatform.com/api/containers/14",
                "method" : "GET"
            },{
                "label": "CONTAINER___EDIT_METADATA",
                "href" : "https://tenant.kzoplatform.com/api/containers/14",
                "method" : "PATCH"
            },{
                "label": "CONTAINER___UPDATE",
                "href" : "https://tenant.kzoplatform.com/api/containers/14",
                "method" : "PUT"
            }],
            "order": {
                "containers": {},
                "media": {}
            },
            "pipeline_status": "EDITING",
            "pipeline_resource": {
                "href": "https://tenant.kzoplatform.com/api/containers/14",
                "type": "containers"
            }
        },
        "thumbnails": null
    },
    "linked": {
        "playlist_entries": [{
            "id": "C_2",
            "href": "",
            "links":{"container": "2"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "M_6",
            "href": "",
            "links":{"medium": "6"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "C_3",
            "href": "",
            "links":{"container": "3"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "C_4",
            "href": "",
            "links":{"container": "4"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "M_5",
            "href": "",
            "links":{"medium": "5"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "C_20",
            "href": "",
            "links":{"container": "20"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "C_30",
            "href": "",
            "links":{"container": "30"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "M_200",
            "href": "",
            "links":{"medium": "200"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "M_300",
            "href": "",
            "links":{"medium": "300"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "M_500",
            "href": "",
            "links":{"medium": "500"},
            "meta":{"pagination":{}, "actions":[]}
        },{
            "id": "C_50",
            "href": "",
            "links":{"container": "50"},
            "meta":{"pagination":{}, "actions":[]}
        }],
        "containers": [{
            "id": 2,
            "links": {
                "playlist_entries": ["M_200", "C_30", "C_20", "M_300"]
                ...
            },
            "meta": {
                "order": {},
                "pagination": {...}
                ...
            }
            ...
        }, {
            "id": 3,
            "links": {
                "playlist_entries": ["M_500", "C_50"]
                ...
            },
            "meta": {
                "order": {},
                "pagination": {...}
                ...
            }
            ...
        }, {
            "id": 4,
            "links": {
                "playlist_entries": []
                ...
            },
            "meta": {
                "order": {},
                "pagination": {...}
                ...
            }
            ...
        }, {
            "id": 20,
            "links": {
                "playlist_entries": []
                ...
            },
            "meta": {
                "order": {},
                "pagination": {...}
                ...
            }
            ...
        }, {
            "id": 30,
            "links": {
                "playlist_entries": []
                ...
            },
            "meta": {
                "order": {},
                "pagination": {...}
                ...
            }
            ...
        }, {
            "id": 50,
            "links": {
                "playlist_entries": []
                ...
            },
            "meta": {
                "order": {},
                "pagination": {...}
                ...
            }
            ...
        }, {
            "id": 20,
            "links": {
                "playlist_entries": []
                ...
            },
            "meta": {
                "order": {},
                "pagination": {...}
                ...
            }
            ...
        }, {
            "id": 12,
            "links": {
                "playlist_entries": []
                ...
            },
            "meta": {
                "order": {},
                "pagination": {...}
                ...
            }
            ...
        }],
        "media": [{
            "id": 5
            ...
        }, {
            "id": 6
            ...
        }, {
            "id": 200
            ...
        }, {
            "id": 300
            ...
        }, {
            "id": 500
            ...
        }],
        "users": [{
            "id": 1,
            "username": "admin"
            ...
        }]
    },
    "meta": {}
}
Viewing Multiple Containers
GET /containers/{ids}

Fetch containers with specific IDs.

Requires Permission assigning Role VIEWER on the given Containers.

Pagination: containers, media.

This endpoint supports 2 output modes of operation: the normal and the proxy ones.

The normal mode is used when child containers and/or media are requested (see parameter include) as containers and media, respectively. In this mode:

  1. links in container objects contain unordered sets media and containers, containing direct links to corresponding child media and containers, respectively.
  2. Order of child containers and media is represented by meta.order of the container object.
  3. Child containers and media are two separate relationships, so their paginations are independent from each other.

The proxy mode is used when child containers and/or media are requested (see parameter include) as playlist_entries.container and playlist_entries.medium, respectively. In this mode:

  1. links in container objects contain arrays playlist_entries, containing links to proxy objects linked.playlist_entries.
  2. Each element of linked.playlist_entries is a link to the corresponding container/medium.
  3. Order of child containers and media is represented by the order of links to the corresponding proxy objects in links.playlist_entries of the container object.
  4. Child containers and media are considered as a single heterogeneous collection, with the pagination across this collection.

Note that if modes are mixed up in include, 400 This endpoint can be used either in normal or in proxy mode. will be returned. This applies also to subordinate relationships of containers and media. For example, if media are requested in the proxy mode (playlist_entries.medium), their slide decks should be, too (playlist_entries.medium.slide_deck).

Path variables

ids
string required

Comma-separated list of the IDs of multiple containers

Example:
1,2

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
child_depth
number optional

Depth of the heirarchy of Container resources to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no children are included, value -1 means the full hierarchy is included. Default value is 0.

Example:
2
parent_depth
number optional

Depth of the heirarchy of Container resources up from the given Container (using only links of type ORIGINAL) to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no parent are included, value -1 means the full hierarchy is included. Default value is 0. For the topmost Container, no parent is specified.

Example:
1
include
string optional

Comma-separated list of associated objects which should be included in the response. Applicable to all levels of the hierarchy but the deepest one. Default value: empty. What can be included at most in the normal mode: parent,containers,media,containers.modified_by,containers.created_by, media.modified_by,media.created_by,media.slide_deck,media.parent,containers.authored_by,media.authored_by,media.closed_captions_sets,media.closed_captions_sets.languages,favorites,favorites.containers,favorites.media,favorites.created_by,media.favorites,media.favorites.media,media.favorites.created_by,containers.favorites,containers.favorites.containers,containers.favorites.created_by. What can be included at most in the proxy mode: parent,playlist_entries.container,playlist_entries.medium,playlist_entries.container.modified_by,playlist_entries.container.created_by,playlist_entries.medium.modified_by,playlist_entries.medium.created_by,playlist_entries.medium.slide_deck,playlist_entries.medium.parent,playlist_entries.container.authored_by,playlist_entries.medium.authored_by,playlist_entries.medium.closed_captions_sets,playlist_entries.medium.closed_captions_sets.languages,favorites,favorites.containers,favorites.media,favorites.created_by,playlist_entries.medium.favorites,playlist_entries.medium.favorites.media,playlist_entries.medium.favorites.created_by,playlist_entries.container.favorites,playlist_entries.container.favorites.containers,playlist_entries.container.favorites.created_by Inclusion of Containers is also controlled by parameters parent_depth and child_depth. Use include=parent to fill respective link for all primary and linked containers. Use include=media.parent to fill respective link for all linked media.

Example:
media.modified_by
page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

This example only demonstrates the key differences of the response from the response of the method Viewing Container.

GET https://tenant.kzoplatform.com/api/containers/1,2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "containers": [{
        "id" : "1"
        ...
    }, {
        "id" : "2"
        ...
    }]
    ...
}
Viewing Topmost Available Containers
GET /containers/top

This method returns the topmost avalilable Containers in the hierarchy to which the user has access. Hence, if the user has access to the full Container hierarchy, the only Container returned in the primary resource collection will be the root Container. If the user has access only to one or more subtrees of the Container tree, the Containers which are roots of all Container hierarchy subtrees available to the user will be returned.

Does not require Permissions.

Pagination: primary, containers, media.

This endpoint supports 2 output modes of operation: the normal and the proxy ones.

The normal mode is used when child containers and/or media are requested (see parameter include) as containers and media, respectively. In this mode:

  1. links in container objects contain unordered sets media and containers, containing direct links to corresponding child media and containers, respectively.
  2. Order of child containers and media is represented by meta.order of the container object.
  3. Child containers and media are two separate relationships, so their paginations are independent from each other.

The proxy mode is used when child containers and/or media are requested (see parameter include) as playlist_entries.container and playlist_entries.medium, respectively. In this mode:

  1. links in container objects contain arrays playlist_entries, containing links to proxy objects linked.playlist_entries.
  2. Each element of linked.playlist_entries is a link to the corresponding container/medium.
  3. Order of child containers and media is represented by the order of links to the corresponding proxy objects in links.playlist_entries of the container object.
  4. Child containers and media are considered as a single heterogeneous collection, with the pagination across this collection.

Note that if modes are mixed up in include, 400 This endpoint can be used either in normal or in proxy mode. will be returned. This applies also to subordinate relationships of containers and media. For example, if media are requested in the proxy mode (playlist_entries.medium), their slide decks should be, too (playlist_entries.medium.slide_deck).

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
child_depth
number optional

Depth of the heirarchy of Container resources to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no children are included, value -1 means the full hierarchy is included. Default value is 0.

Example:
0
include
string optional

Comma-separated list of associated objects which should be included in the response. Applicable to all levels of the hierarchy but the deepest one. Default value: empty. What can be included at most in the normal mode: parent,containers,media,containers.modified_by,containers.created_by, media.modified_by,media.created_by,media.slide_deck,media.parent,containers.authored_by,media.authored_by,media.closed_captions_sets,media.closed_captions_sets.languages,favorites,favorites.containers,favorites.media,favorites.created_by,media.favorites,media.favorites.media,media.favorites.created_by,containers.favorites,containers.favorites.containers,containers.favorites.created_by. What can be included at most in the proxy mode: parent,playlist_entries.container,playlist_entries.medium,playlist_entries.container.modified_by,playlist_entries.container.created_by,playlist_entries.medium.modified_by,playlist_entries.medium.created_by,playlist_entries.medium.slide_deck,playlist_entries.medium.parent,playlist_entries.container.authored_by,playlist_entries.medium.authored_by,playlist_entries.medium.closed_captions_sets,playlist_entries.medium.closed_captions_sets.languages,favorites,favorites.containers,favorites.media,favorites.created_by,playlist_entries.medium.favorites,playlist_entries.medium.favorites.media,playlist_entries.medium.favorites.created_by,playlist_entries.container.favorites,playlist_entries.container.favorites.containers,playlist_entries.container.favorites.created_by Inclusion of Containers is also controlled by parameters parent_depth and child_depth. Use include=parent to fill respective link for all primary and linked containers. Use include=media.parent to fill respective link for all linked media.

Example:
media,media.modified_by,media.created_by
page
number optional

The number of page (see Pagination).

Max:2147483647
Default:
1
page_size_primary
number optional

The maximum number of primary resources are to be returned (see Pagination).

Min:1 Max:2147483647
Default:
20
page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Multiple Containers.

GET https://tenant.kzoplatform.com/api/containers/top HTTP/1.1 
Searching Containers
GET /containers

Fetch containers satisfying specific criteria.

Does not require Permissions.

Pagination: primary, containers, media.

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
title
string optional

Filtering by container title with partial matching.

Example:
New
description
string optional

Filtering by container description with partial matching

Example:
York
page
number optional

The number of page (see Pagination).

Max:2147483647
Default:
1
page_size_primary
number optional

The maximum number of primary resources are to be returned (see Pagination).

Min:1 Max:2147483647
Default:
20
page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10

Responses

200 OK

No associated resources are included with the response.

401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

Find all containers titles of which include the word 'new'.

The response is the same as that of the method Viewing Multiple Containers.

GET https://tenant.kzoplatform.com/api/containers?title=new HTTP/1.1 
Creating Container
POST /containers/{id}/container

Creates a container.

Requires Permission assigning Role CONTENT_CREATOR_CONTAINERS on the parent Container of the Container to be created.

Path variables

id
number required

The id of the parent container that this container should become a child of

Example:
1

Responses

201 Created

No associated resources are included with the response.

Headers
Location
string required

URI of a newly created resource

401 Unauthorized

The request requires Authentication and Authorization.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Container.

POST https://tenant.kzoplatform.com/api/containers/1/container HTTP/1.1 

Content-Type: application/json

{
    "containers": {
        "title" : "Marketing Videos",
        "description": "All of our Marketing videos will go in here"
    }
}
POST https://tenant.kzoplatform.com/api/containers/{id}/container HTTP/1.1 

Content-Type: application/json

{
    "containers": {
        "title" : "Marketing Videos",
        "description": "All of our Marketing videos will go in here",
        "authored_by": "author"
    }
}
Creating Top-Level Container
POST /containers/root/container

Creates a new top-level Container -- a direct descendant of the root Container.

Requires Permission assigning Role TOP_LEVEL_CONTAINER_CREATOR on the root Container. If the User has not been assigned Role CONTENT_VIEWER on the root Container, the newly created container will be returned parentless.

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Container.

POST https://tenant.kzoplatform.com/api/containers/root/container HTTP/1.1 
Replacing Container
PUT /containers/{id}

Complete replacement of container.

Requires Permission assigning Role CONTENT_UPDATER on the given Container.

Requires Permission assigning Role AUTHORSHIP_MANAGER on the given Container for updating an author of Container.

Path variables

id
number required

The id of container

Example:
1

Responses

200 OK

No associated resources are included with the response.

401 Unauthorized

The request requires Authentication and Authorization.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Container.

PUT https://tenant.kzoplatform.com/api/containers/1 HTTP/1.1 

Content-Type: application/json

{
    "containers": {
        "title" : "Marketing Videos",
        "description": "All of our Marketing videos will go in here",
        "parent_id" : "id of new parent(optional field)"
    }
}
PUT https://tenant.kzoplatform.com/api/containers/{id} HTTP/1.1 

Content-Type: application/json

{
    "containers": {
        "title" : "Marketing Videos",
        "description": "All of our Marketing videos will go in here",
        "parent_id" : "id of new parent(optional field)",
        "authored_by": "author"
    }
}
Updating Container
PATCH /containers/{id}

Partial update of the container.

Requires Permission assigning Role CONTENT_UPDATER on the given Container.

Requires Permission assigning Role AUTHORSHIP_MANAGER on the given Container for updating an author of Container.

Path variables

id
number required

The id of container

Example:
1

Responses

200 OK

No associated resources are included with the response.

401 Unauthorized

The request requires Authentication and Authorization.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

Request is an array representing sequence of patch operations.

The response is the same as that of the method Viewing Container.

PATCH https://tenant.kzoplatform.com/api/containers/5 HTTP/1.1 

Content-Type: application/json

[{ 
    "op": "replace", 
    "path": "/title", 
    "value": "It is new title" 
}, { 
    "op": "replace", 
    "path": "/description", 
    "value": "It is new description" 
}, { 
    "op": "replace", 
    "path": "/parent_id", 
    "value": "123"
}, {
    "op": "replace",
    "path": "/created_at",
    "value": "2016-05-14T08:05:50.374Z"
}]
Deleting Container
DELETE /containers/{id}

Deletes container

Requires Permission assigning Role CONTENT_DELETER on the given Container.

Path variables

id
number required

The id of container

Example:
2

Responses

204 No Content

The response does not include body.

401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/containers/10 HTTP/1.1 
Reordering Children of a Container
POST /containers/{id}/meta/order

It is not possible to add or delete children of a Container using this method, only reorder. Error 400 is returned if either duplicate keys are provided or not all IDs of Media and Containers which are children of the given Container are specified. Keys have to be non-negative integers, but not necessarily consecutive ones.

The endpoint supports request payloads in normal and proxy modes.

In the normal mode, the order is represented by 2 separate assotiative arrays, one for media and one for containers. Each key is a unique (across all immediate child containers and media of the container) integer priority, while the corresponding value is the ID of the container/medium, which should have that priority.

In the proxy mode, all immediate child containers and media should be represented by a single heterogeneous array of their encoded IDs. Encoded ID of container {id} should be "C_{id}". Encoded ID of medium {id} should be "M_{id}".

Mixing of the normal and proxy modes is forbidden: 400 Bad Request will be returned.

Path variables

id
number optional

The ID of Container

Example:
123

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

POST https://tenant.kzoplatform.com/api/containers/123/meta/order HTTP/1.1 

Content-Type: application/json

{
    "order": {
        "containers": {
            "0": 3,
            "2": 2,
            "3": 4
        },
        "media": {
            "1": 6,
            "4": 5
        }
    }
}
POST https://tenant.kzoplatform.com/api/containers/123/meta/order HTTP/1.1 

Content-Type: application/json

{
    "order": {
        "playlist_entries": ["C_3", "M_6", "C_2", "C_4", "M_5"]
    }
}
Viewing Playlist
GET /playlist/{id}

Fetch all PUBLISHED media under container with the specified id

Path variables

id
string required

The id of container

Example:
123

Responses

200 OK
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/playlist/123 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "playlist": {
    "id": 123,
    "links": {
      "media": [ 1, 89 ]
    }
  },
  "linked": {
    "media": [{
      "id": "1"
      ...
    },{
      "id": "89"
      ...
    ]},
  "meta": {}
}
Viewing Immediate Child Containers
GET /containers/{id}/containers

Fetch containers linked directly with a container with a given ID as children (link type does not matter).

Requires Permission assigning Role VIEWER on the given Container.

Pagination: primary, containers, media.

This endpoint supports 2 output modes of operation: the normal and the proxy ones.

The normal mode is used when child containers and/or media are requested (see parameter include) as containers and media, respectively. In this mode:

  1. links in container objects contain unordered sets media and containers, containing direct links to corresponding child media and containers, respectively.
  2. Order of child containers and media is represented by meta.order of the container object.
  3. Child containers and media are two separate relationships, so their paginations are independent from each other.

The proxy mode is used when child containers and/or media are requested (see parameter include) as playlist_entries.container and playlist_entries.medium, respectively. In this mode:

  1. links in container objects contain arrays playlist_entries, containing links to proxy objects linked.playlist_entries.
  2. Each element of linked.playlist_entries is a link to the corresponding container/medium.
  3. Order of child containers and media is represented by the order of links to the corresponding proxy objects in links.playlist_entries of the container object.
  4. Child containers and media are considered as a single heterogeneous collection, with the pagination across this collection.

Note that if modes are mixed up in include, 400 This endpoint can be used either in normal or in proxy mode. will be returned. This applies also to subordinate relationships of containers and media. For example, if media are requested in the proxy mode (playlist_entries.medium), their slide decks should be, too (playlist_entries.medium.slide_deck).

Path variables

id
number required

The id of container

Example:
1

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
child_depth
number optional

Depth of the heirarchy of Container resources to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no children are included, value -1 means the full hierarchy is included.

Min:-1
parent_depth
number optional

Depth of the heirarchy of Container resources up from the given Container (using only links of type ORIGINAL) to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no parent are included, value -1 means the full hierarchy is included. For the topmost Container, no parent is specified.

Min:-1
include
string optional

Comma-separated list of associated objects which should be included in the response. Applicable to all levels of the hierarchy but the deepest one. Default value: empty. What can be included at most in the normal mode: parent,containers,media,containers.modified_by,containers.created_by, media.modified_by,media.created_by,media.slide_deck,media.parent,containers.authored_by,media.authored_by,media.closed_captions_sets,media.closed_captions_sets.languages,favorites,favorites.containers,favorites.media,favorites.created_by,media.favorites,media.favorites.media,media.favorites.created_by,containers.favorites,containers.favorites.containers,containers.favorites.created_by. What can be included at most in the proxy mode: parent,playlist_entries.container,playlist_entries.medium,playlist_entries.container.modified_by,playlist_entries.container.created_by,playlist_entries.medium.modified_by,playlist_entries.medium.created_by,playlist_entries.medium.slide_deck,playlist_entries.medium.parent,playlist_entries.container.authored_by,playlist_entries.medium.authored_by,playlist_entries.medium.closed_captions_sets,playlist_entries.medium.closed_captions_sets.languages,favorites,favorites.containers,favorites.media,favorites.created_by,playlist_entries.medium.favorites,playlist_entries.medium.favorites.media,playlist_entries.medium.favorites.created_by,playlist_entries.container.favorites,playlist_entries.container.favorites.containers,playlist_entries.container.favorites.created_by Inclusion of Containers is also controlled by parameters parent_depth and child_depth. Use include=parent to fill respective link for all primary and linked containers. Use include=media.parent to fill respective link for all linked media.

Example:
media
page
number optional

The number of page (see Pagination).

Max:2147483647
Default:
1
page_size_primary
number optional

The maximum number of primary resources are to be returned (see Pagination).

Min:1 Max:2147483647
Default:
20
page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Fetching immediate media
GET /containers/{id}/media

Fetch media linked directly with a container with a given ID (link type does not matter).

Requires Permission assigning Role VIEWER on the given Container.

Pagination: primary.

Path variables

id
number required

The id of container

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: media.created_by,media.modified_by, parent,parent.created_by,parent.modified_by, chapters,chapters.created_by,chapters.modified_by, original_videos,original_videos.created_by,original_videos.modified_by, video_renditions,video_renditions.created_by,video_renditions.modified_by, slide_decks,slide_decks.created_by,slide_decks.modified_by, slides,slides.created_by,slides.modified_by, used_slides,used_slides.created_by,used_slides.modified_by, comments,comments.created_by,comments.modified_by,comments.deleted_by, replies,replies.created_by,replies.modified_by,replies.deleted_by, video_rendition_options,screenshots,screenshot_options, montages,montage_options,media.authored_by,closed_captions_sets.

If Replies are included, it is assumed that unlimited depth is requested.

Example:
parent,parent.created_by
parent_depth
number optional

Depth of the heirarchy of Container resources up from the given Container (using only links of type ORIGINAL) to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no parent are included, value -1 means the full hierarchy is included.

Min:-1 Max:2147483647
Default:
0
page
number optional

The number of page (see Pagination).

Max:2147483647
Default:
1
page_size_primary
number optional

The maximum number of primary resources are to be returned (see Pagination).

Min:1 Max:2147483647
Default:
20
Fetching Immediate Children
GET /containers/{id}/playlist_entries

Fetch playlist entries linked directly with a container with a given ID as children.

Requires Permission assigning Role CONTENT_VIEWER on the given Container.

Pagination: primary.

Path variables

id
number required

The id of container

Example:
1

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most:

  • playlist_entries.container
  • playlist_entries.container.created_by
  • playlist_entries.container.authored_by
  • playlist_entries.container.modified_by
  • playlist_entries.medium
  • playlist_entries.medium.created_by
  • playlist_entries.medium.authored_by
  • playlist_entries.medium.modified_by
page
number optional

The number of page (see Pagination).

Max:2147483647
Default:
1
page_size_primary
number optional

The maximum number of primary resources are to be returned (see Pagination).

Min:1 Max:2147483647
Default:
20

Responses

200 OK
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/containers/325641022015018940/playlist_entries?include=playlist_entries.container,playlist_entries.medium&page_size_primary=3 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "linked": {
        "containers": [
            {
                "id": "472060407171781682",
                "href": "https://staging-101.kzoinnovations.com/api/containers/472060407171781682?page_size_related=10000",
                "links": {
                    "favorites": {
                    },
                    "parent": {
                    },
                    "authored_by": {
                    },
                    "modified_by": {
                    },
                    "deleted_by": {
                    },
                    "playlist_entries": [
                    ],
                    "owned_by": {
                        "type": "users",
                        "username": "admin"
                    },
                    "containers": [
                    ],
                    "media": [
                    ],
                    "created_by": {
                    }
                },
                "meta": {
                    "notification_subscription": {
                        "direct": null,
                        "inherited": false
                    },
                    "pagination": {
                    },
                    "state": {
                        "pipeline_status": "EDITING",
                        "published": true,
                        "pipeline_resource": {
                            "href": "https://staging-101.kzoinnovations.com/api/containers/472060407171781682?page_size_related=10000",
                            "type": "containers"
                        }
                    },
                    "collective": {
                    },
                    "actions": [
                        {
                            "label": "CONTAINER_GET",
                            "href": "https://staging-101.kzoinnovations.com/api/containers/472060407171781682?page_size_related=10000",
                            "method": "GET"
                        }
                    ],
                    "order": {
                        "containers": {
                        },
                        "media": {
                        }
                    }
                },
                "root": false,
                "title": "Lexxxxx child",
                "description": null,
                "created_at": "2015-10-14T07:39:45.761Z",
                "modified_at": "2015-10-14T07:39:45.761Z",
                "deleted_at": null,
                "screenshot_href": "https://d1nqj7fk8ojzpc.cloudfront.net/kzo3/SCREENSHOT/612003726051251892.png?Expires=1495793925&Signature=NsRZDAhnP3JUNrYYOIz4lAQG8-~EBn-OrrzHXRbKWFwOvZbKIYqzuXBHGZOLExrflqQcCvbVpsW22tpWP99SqpYKvB~Qz7VT1gC-bYQXhJ0CoSPxzrhsiDvpFszmBPrWqBbEgp4Ae7rG0slUWR2A20A3Fgi2V7wjln1h7kCCtavG2TwIJRmYpMkCxlSvfAyjg4sHd6A9dq9vpH7pQs0fI4IFkH~8-Ey7eFFjsR0Ztnl-c992ycRmhrJ9iu3s3FUdE6QXS-0pErENV0RSoeYSk~H~42nXL6XLkK49y-u9TTU53Qv2enpD1SoZiQ3Sp6dhuzpp3DvF4VJPYR68ZcuYZw__&Key-Pair-Id=APKAI3Y7W2IRT5A2ADMA",
                "thumbnails": [
                    ...
                ],
                "subscription": false
            }
        ],
        "media": [
            {
                "id": "328537880626468139",
                "href": "https://staging-101.kzoinnovations.com/api/media/328537880626468139?page_size_related=10000",
                "links": {
                    "favorites": {
                    },
                    "parent": {
                    },
                    "slides": [
                    ],
                    "authored_by": {
                    },
                    "comments": [
                    ],
                    "chapters": [
                    ],
                    "montages": [
                    ],
                    "closed_captions_sets": [
                    ],
                    "original_video": {
                    },
                    "deleted_by": {
                    },
                    "owned_by": {
                        "type": "users",
                        "username": "admin"
                    },
                    "created_by": {
                    },
                    "used_slides": [
                    ],
                    "screenshots": [
                    ],
                    "replies": [
                    ],
                    "modified_by": {
                    },
                    "video_renditions": [
                    ],
                    "screenshot_positions": [
                    ],
                    "slide_deck": {
                    }
                },
                "meta": {
                    "notification_subscription": {
                        "direct": "SUBSCRIPTION",
                        "inherited": false
                    },
                    "pagination": {
                    },
                    "state": {
                        "pipeline_status": "READY",
                        "published": true,
                        "pipeline_resource": {
                            "href": "https://staging-101.kzoinnovations.com/api/media/328537880626468139?page_size_related=10000",
                            "type": "media"
                        }
                    },
                    "metrics": {
                        "favorites": 0,
                        "comments": 0,
                        "views": 9
                    },
                    "actions": [
                        {
                            "label": "MEDIA_GET",
                            "href": "https://staging-101.kzoinnovations.com/api/media/328537880626468139?page_size_related=10000",
                            "method": "GET"
                        }
                    ]
                },
                "title": "My Media",
                "description": "Media description",
                "created_at": "2015-03-30T07:06:17.398Z",
                "modified_at": "2015-03-30T07:06:17.398Z",
                "deleted_at": null,
                "trt_msec": 16000,
                "screenshot_href": "https://d1nqj7fk8ojzpc.cloudfront.net/kzo3/SCREENSHOT/612003561265436316.jpg?Expires=1495793915&Signature=ZrT2b02Xa3wow5lOSTBvgsw0PNDjIVaQ4Z-Ur819uEW3eMozcLA07Zwy-M4eYoAqjgbQe4z6nMvn~L6PIOPqyN89xPecu~Pi6ewW4EPcuh3HNtTCJQdnFk3gZush1iPuV8~OhLYQaNWNX3KCfB6oHvgpn5ziJVRJsH9xKeH0A1JPhN3eXdbeOBhRFoswXNThbN7VJfDDQK8iMRyDTG3EwOCp~8TA5K1S81vJISCZ280JZ03M3BlC6P6361SZcL2NwFrhv37R8WvMqSj2Nk4uv25xPuSHwzPcOvTRT4TUfvPyuAx~9RvC5Wb1PFF2Mc52Ma14LgMiuyEj0bDAtoYHmw__&Key-Pair-Id=APKAI3Y7W2IRT5A2ADMA",
                "subscription": true,
                "thumbnails": [
                    ...
                ]
            },
            {
                "id": "374948088395077039",
                "href": "https://staging-101.kzoinnovations.com/api/media/374948088395077039?page_size_related=10000",
                "links": {
                    "favorites": {
                    },
                    "parent": {
                    },
                    "slides": [
                    ],
                    "authored_by": {
                    },
                    "comments": [
                    ],
                    "chapters": [
                    ],
                    "montages": [
                    ],
                    "closed_captions_sets": [
                    ],
                    "original_video": {
                    },
                    "deleted_by": {
                    },
                    "owned_by": {
                        "type": "users",
                        "username": "admin"
                    },
                    "created_by": {
                    },
                    "used_slides": [
                    ],
                    "screenshots": [
                    ],
                    "replies": [
                    ],
                    "modified_by": {
                    },
                    "video_renditions": [
                    ],
                    "screenshot_positions": [
                    ],
                    "slide_deck": {
                    }
                },
                "meta": {
                    "notification_subscription": {
                        "direct": "SUBSCRIPTION",
                        "inherited": false
                    },
                    "pagination": {
                    },
                    "state": {
                        "pipeline_status": "READY",
                        "published": true,
                        "pipeline_resource": {
                            "href": "https://staging-101.kzoinnovations.com/api/media/374948088395077039?page_size_related=10000",
                            "type": "media"
                        }
                    },
                    "metrics": {
                        "favorites": 0,
                        "comments": 0,
                        "views": 6
                    },
                    "actions": [
                        {
                            "label": "MEDIA_GET",
                            "href": "https://staging-101.kzoinnovations.com/api/media/374948088395077039?page_size_related=10000",
                            "method": "GET"
                        }
                    ]
                },
                "title": "My Media",
                "description": "Media description",
                "created_at": "2015-06-02T07:55:16.807Z",
                "modified_at": "2015-12-10T19:56:31.642Z",
                "deleted_at": null,
                "trt_msec": 23000,
                "screenshot_href": "https://d1nqj7fk8ojzpc.cloudfront.net/kzo3/SCREENSHOT/598990642600744268.jpg?Expires=1495793927&Signature=WCxEuPyX4iGNtjP6w3Zf5U3zPk4nR4MmtJNBBvFLr-AtHW4DAGbXcWulKhr41QqUkX3Op1cJVSJDIl2HawUtMXozssbYaRxCOZncPgtNkkzoPAY~0CCoAxqRsgMJ1AMD5pNHFqKRo2Yjr6N17xa2ylmlgqMpjcecdpNlKUVw~XcbwT-A1cLHDFEW5~zD8Hpp7f4FIxGJ7AJx9HlArnb-C78AKkMum-kN4ZdiUpZCEgkkS1aJymnJhWe0PsAdy1xF7ilf6zE3yWjsH9tfGVBklVdeRpDaBQVGoNaR69vBEEmeM4pWRPgwRHlG4enF5nYEBo9sshPXVfwCiUA2zIl1~Q__&Key-Pair-Id=APKAI3Y7W2IRT5A2ADMA",
                "subscription": true,
                "thumbnails": [
                    ...
                ]
            }
        ],
        "users": [
            {
                "id": "316971525670441986",
                "href": "https://staging-101.kzoinnovations.com/api/users/admin?page_size_related=10000",
                "links": {
                    "modified_by": {
                    },
                    "home_container": {
                    },
                    "deleted_by": {
                    },
                    "groups": [
                    ],
                    "created_by": {
                    },
                    "avatars": ""
                },
                "meta": {
                    "pagination": {
                    },
                    "state": {
                    },
                    "actions": [
                        {
                            "label": "USER_GET",
                            "href": "https://staging-101.kzoinnovations.com/api/users/admin?page_size_related=10000",
                            "method": "GET"
                        },
                        {
                            "label": "USER_GET_ALL",
                            "href": "https://staging-101.kzoinnovations.com/api/users?page_size_primary=2147483647&page_size_related=10000&page=1",
                            "method": "GET"
                        },
                        {
                            "label": "USER_UPDATE",
                            "href": "https://staging-101.kzoinnovations.com/api/users/admin",
                            "method": "PUT"
                        },
                        {
                            "label": "USER_EDIT_METADATA",
                            "href": "https://staging-101.kzoinnovations.com/api/users/admin",
                            "method": "PATCH"
                        },
                        {
                            "label": "USER_CREATE",
                            "href": "https://staging-101.kzoinnovations.com/api/users",
                            "method": "POST"
                        }
                    ]
                },
                "created_at": "2015-03-14T08:05:50.374Z",
                "modified_at": "2017-04-27T22:24:06.911Z",
                "deleted_at": null,
                "first_name": "admin",
                "last_name": "admin",
                "username": "admin",
                "email": "admin@kzotest.com",
                "authentication_type": "PASSWORD",
                "avatar_href": "https://d1nqj7fk8ojzpc.cloudfront.net/kzo3/AVATAR/359696837701014575.png?Expires=1497388851&Signature=b1DQclt9YfqMm~mTBq15Hr1JDGAQu86KDGb6vS7Ca-pM2Vaixwnl5jMp4G~1K-Jp1C9qXXoWT4wazc5pUOpMeJJNhciX4RLJHE8sNR9mLhmmBPA8J8CxySBPcOHsIPd5UCaq4DZ1oonJUdyVnp5hqwGWl~9FsDOGH2UbCFiA9Z1-SdWaDOxQRb8cuRIyzwd1o~hGKNUGVJUCRw0Kqsnl9~zUUIGzXr3o15T-HLDvs-eCb5yCbfF6LwoVXE6v3CX9J4e2xKHJ-aCDD1ecqP44aC~~D87GSlZ6ejRu-wxqMTQCOVf43-jbzbjBTkYwbp5NPWRNwDaWSYiqWA7KR1dSBw__&Key-Pair-Id=APKAI3Y7W2IRT5A2ADMA",
                "custom_authn_option_id": null
            }
        ]
    },
    "meta": {
        "pagination": {
            "total_results": 17,
            "links": {
                "next": "https://staging-101.kzoinnovations.com/api/containers/325641022015018973/playlist_entries?page_size_primary=3&include=playlist_entries,playlist_entries.container,playlist_entries.medium&page_size_related=10000&page=2",
                "2next": "https://staging-101.kzoinnovations.com/api/containers/325641022015018973/playlist_entries?page_size_primary=3&include=playlist_entries,playlist_entries.container,playlist_entries.medium&page_size_related=10000&page=3",
                "last": "https://staging-101.kzoinnovations.com/api/containers/325641022015018973/playlist_entries?page_size_primary=3&include=playlist_entries,playlist_entries.container,playlist_entries.medium&page_size_related=10000&page=6",
                "3next": "https://staging-101.kzoinnovations.com/api/containers/325641022015018973/playlist_entries?page_size_primary=3&include=playlist_entries,playlist_entries.container,playlist_entries.medium&page_size_related=10000&page=4",
                "first": "https://staging-101.kzoinnovations.com/api/containers/325641022015018973/playlist_entries?page_size_primary=3&include=playlist_entries,playlist_entries.container,playlist_entries.medium&page_size_related=10000&page=1"
            }
        }
    },
    "playlist_entries": [
        {
            "id": "C_472060407171781682",
            "href": "",
            "links": {
                "container": "472060407171781682"
            },
            "meta": {
                "pagination": {
                },
                "actions": [
                ]
            }
        },
        {
            "id": "M_328537880626468139",
            "href": "",
            "links": {
                "medium": "328537880626468139"
            },
            "meta": {
                "pagination": {
                },
                "actions": [
                ]
            }
        },
        {
            "id": "M_374948088395077039",
            "href": "",
            "links": {
                "medium": "374948088395077039"
            },
            "meta": {
                "pagination": {
                },
                "actions": [
                ]
            }
        }
    ]
}
Incremental reordering of descendant playlist entries for container
POST /containers/{id}/meta/set_order

Method performs reordering of child content units for container under consideration. The main difference from https://speca.io/KZO/kzo-api#reordering-children-of-a-container is that this method requires only new orders of PLEs to be moved.

Path variables

id
number optional

The ID of Container

Example:
123

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad request

If input data is incorrect: incorrect content units ids or related orders are passed

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

POST https://tenant.kzoplatform.com/api/containers/123/meta/set_order HTTP/1.1 

Content-Type: application/json

{
    "order": {
        "playlist_entries": {
            "3": "M_6",
            "5": "C_2"
        }
    }
}
Media
GET /media/{id}
GET /media/{ids}
GET /media
POST /containers/{id}/medium
PATCH /media/{id}
PUT /media/{id}
DELETE /media/{id}
POST /media/{id}/copy
Viewing Medium
GET /media/{id}

View information about a given Medium object.

Requires Permission assigning Role VIEWER on the parent Container of the given Medium.

Path variables

id
number required

The id of media

Example:
1

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: media.created_by,media.modified_by, parent,parent.created_by,parent.modified_by, chapters,chapters.created_by,chapters.modified_by, original_videos,original_videos.created_by,original_videos.modified_by, video_renditions,video_renditions.created_by,video_renditions.modified_by, slide_decks,slide_decks.created_by,slide_decks.modified_by, slides,slides.created_by,slides.modified_by, used_slides,used_slides.created_by,used_slides.modified_by, comments,comments.created_by,comments.modified_by,comments.deleted_by, comments.replies,comments.replies.created_by,comments.replies.modified_by,comments.replies.deleted_by, video_rendition_options,screenshots,screenshot_options, montages,montage_options,media.authored_by,closed_captions_sets, closed_captions_sets.languages.

If Replies are included, it is assumed that unlimited depth is requested.

Example:
parent,parent.created_by
parent_depth
number optional

Depth of the heirarchy of Container resources up from the given Container (using only links of type ORIGINAL) to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no parent are included, value -1 means the full hierarchy is included. Default value is 0.

Example:
2
preauth_actions
boolean optional

Whether to include actions to get and play medium by unauthenticated users. The URLs of actions will contain temporal access key.

Default:
false

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/media/234 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "media": {
        "id" : "234",
        "title" : "Baby's first video!",
        "description" : "A lovely description for your new video.",
        "trt_msec" : 48000,
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "updated_at" : "2012-10-10T14:12:24Z",
        "comment_notification": true,
        "href": "https://tenant.kzoplatform.com/api/media/234",
        "screenshot_href": "http://d6mgdbc2kfx06.cloudfront.net/...",
        "links" : {
            "parent": {
                "id": 1,
                "type": "containers"
            },
            "original_video": 99,
            "video_renditions": [ 345, 456 ],
            "slide_deck": 567,
            "used_slides": [ 678, 789 ],
            "chapters": [ 890, 901 ],
            "comments": [ 45, 56 ],
            "replies": [ 67, 78 ],
            "created_by": {
                "username": "admin",
                "type": "users"
            },
            "modified_by": {
                "username": "admin",
                "type": "users"
            },
        },
        "meta": {
            "actions": [{
                "label": "MEDIUM___EDIT_METADATA",
                "href" : "https://tenant.kzoplatform.com/api/media/234",
                "method" : "PATCH"
            },{
                "label": "MEDIUM___DELETE",
                "href" : "https://tenant.kzoplatform.com/api/media/234",
                "method" : "DELETE"
            }],
            "pipeline_status": "EDITING",
            "pipeline_resource": {
                "href": "https://tenant.kzoplatform.com/api/media/234",
                "type": "media"
            }
        },
        thumbnails":[{
            "x": null,
            "y": null,
            "href":{
                "DEFAULT": "https://d1nqj7fk8ojzpc.cloudfront.net/kzo3/SCREENSHOT/428121458238035702.jpg?Expires=1443172157&Signature=Sr5LJJ9qrar4yLgyKTbz4V2weeo5TFyiGhb119t7SvHVDmOhZPHx6enrh1LuLh68MjEWqQaVefdOPaIRB~mJGZ95GDd0~jptft~Ew5lRJj1ilHJczwUyYS9rWtCxT0ItnDeEJr9cItC1AtAAKsjd~uvkILhkiLYc0BZCVDJ56qDlbKxrBldWq4RjIifcGh1SQVrxFaKMekfNM6T8TQCoAvVOQ4DEr7jHwwiV1eqoGYxghribGEAsHs4x2YUlMIetx6QqOcrzllhKDy2~DyN7rvdJHJAE5c69ySnydOkpyMDCUThdKXGW2w8gjjwKBGGZySaGPOXqh0Tr1RcNGdt58A__&Key-Pair-Id=APKAI3Y7W2IRT5A2ADMA",
                "LARGE": "https://d1nqj7fk8ojzpc.cloudfront.net/kzo3/SCREENSHOT/428121458246424311.jpg?Expires=1443172157&Signature=If46AI0HYJoWyqkhX2MqH5SLh6TdtOHALiJBJMkgtdNL-3hNYWkeZYhQ1mgxl~moFW7-KD4oam2tJUMDQfQ8gvxS1KHAlI8ywXr6Jlfy15z~iUdzfr8bfIocrA~ELdg9RNPlV1qKQyc52li-sP2NLto9lvIQpS8dJNOOyEWhuBOzICZivJGLm~i-QDxQzUcToP1KAQpXT0qJntnFdtvBL8Oc9MoUKXPicsC9DX2zYUs2j78bFvUL2BJC35EDHerK-MMSERRI3LoFBqq0MCCQZn4FUFoCB9qfa6kHA5klck-4LrDMRRBPI1ZNZATZn9dcPp6JKebxDMJQL-x1w8lrRg__&Key-Pair-Id=APKAI3Y7W2IRT5A2ADMA"
            }
        }]
    },
    "linked": {
        "containers": [{
            "id": 1
            ...
        }],
        "original_videos": [{
            "id": 99
            ...
        },{
        "video_renditions": [{
            "id": 345
            ...
        },{
            "id": 456
            ...
        }
        }],
        "slide_decks": [{
            "id": 567
            ...
        }],
        "used_slides": [{
            "id": 678
            ...
        },{
            "id": 789
            ...
        }],
        "chapters": [{
            "id": 809
            ...
        },{
            "id": 901
            ...
        }],
        "comments": [{
            "id": 45
            ...
        },{
            "id": 56
            ...
        }],
        "replies": [{
            "id": 67
            ...
        },{
            "id": 78
            ...
        }],
        "users": [{
            "id": 2,
            "username": "admin"
            ...
        }]
    },
    "meta": {}
}
Viewing Multiple Media
GET /media/{ids}

View information about a given Media objects.

Requires Permission assigning Role VIEWER on the parent Containers of the given Media objects.

Path variables

ids
string required

Comma-separated list of the IDs of multiple media

Example:
1,2

Request parameters

unpublished
boolean optional

Whether to include resources with attribute published = false into the response. API user needs to have specific permissions to be able to access unpublished content. Default value is false.

Example:
true
include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: media.created_by,media.modified_by, parent,parent.created_by,parent.modified_by, chapters,chapters.created_by,chapters.modified_by, original_videos,original_videos.created_by,original_videos.modified_by, video_renditions,video_renditions.created_by,video_renditions.modified_by, slide_decks,slide_decks.created_by,slide_decks.modified_by, slides,slides.created_by,slides.modified_by, used_slides,used_slides.created_by,used_slides.modified_by, comments,comments.created_by,comments.modified_by, replies,replies.created_by,replies.modified_by, video_rendition_options,screenshots,screenshot_options, montages,montage_options,media.authored_by,closed_captions_sets, closed_captions_sets.languages.

Example:
parent
parent_depth
number optional

Depth of the heirarchy of Container resources up from the given Container (using only links of type ORIGINAL) to be included in the response (namely, into the top-level collection linked, resource-level collection links). Value 0 means no parent are included, value -1 means the full hierarchy is included. Default value is 0.

Example:
1

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

This example only demonstrates the key differences of the response from the response of the method Viewing Medium.

GET https://tenant.kzoplatform.com/api/media/1,2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "media": [{
        "id": 1
        ...
    },{
        "id": 2
        ...
    }]
    ...
}
Searching Media
GET /media

Does not require Permissions.

Request parameters

title
string optional

Filtering by media title with partial matching.

Example:
New
description
string optional

Filtering by media description with partial matching.

Example:
York
created_at_to
string optional

Filtering by creation time. Specifies end of inclusive time interval using ISO8601 standard. If not set, it means until the end of time.

Example:
2013-10-10T14:12:24.324Z
created_at_from
string optional

Filtering by creation time. Specifies beginning of inclusive time interval using ISO8601 standard. If not set, it means from the beginning of time.

Example:
2013-10-10T14:12:24.324Z

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

Dsiplay all media with a title matching a.

The response is the same as that of the method Viewing Multiple Media.

GET https://tenant.kzoplatform.com/api/media?title=A HTTP/1.1 
Creating Medium
POST /containers/{id}/medium

Creates a medium.

Requires Permission assigning Role CONTENT_CREATOR on the given Container.

Path variables

id
number required

The id of the container you wish to put the new Medium in.

Example:
1234

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Medium.

POST https://tenant.kzoplatform.com/api/containers/1234/medium HTTP/1.1 

Content-Type: application/json

{
    "media" : {
        "title" : "Baby's first video!",
        "description" : "A lovely description for your new video."
    }
}
POST https://tenant.kzoplatform.com/api/containers/{id}/medium HTTP/1.1 

Content-Type: application/json

{
    "media" : {
        "title" : "Baby's first video!",
        "description" : "A lovely description for your new video.",
        "authored_by": "author"
    }
}
Updating Medium
PATCH /media/{id}

Partial update of the medium.

Requires Permission assigning Role CONTENT_UPDATER on the parent Container of the given Medium.

Requires Permission assigning Role AUTHORSHIP_MANAGER on the parent Container of the given Medium for updating an author of Medium.

Path variables

id
number required

The id of media

Example:
1

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Medium.

PATCH https://tenant.kzoplatform.com/api/media/5 HTTP/1.1 

Content-Type: application/json

[{ 
    "op": "replace", 
    "path": "/title", 
    "value": "It is new title" 
}, { 
    "op": "replace", 
    "path": "/description", 
    "value": "It is new description" 
}, { 
    "op": "replace", 
    "path": "/parent_id", 
    "value": "123"
}, {
    "op": "replace",
    "path": "/created_at",
    "value": "2016-05-14T08:05:50.374Z"
}]
Replacing Medium
PUT /media/{id}

Complete replacement of media.

Requires Permission assigning Role CONTENT_UPDATER on the parent Container of the given Medium.

Requires Permission assigning Role AUTHORSHIP_MANAGER on the parent Container of the given Medium for updating an author of Medium.

Path variables

id
number required

The id of media

Example:
1

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Medium.

PUT https://tenant.kzoplatform.com/api/media/1 HTTP/1.1 

Content-Type: application/json

{
    "media" : {
        "title" : "Baby's first update video!",
        "description" : "A lovely new description for your new video.",
        "parent_id" : "id of new parent(optional field)"
    }
}
PUT https://tenant.kzoplatform.com/api/media/{id} HTTP/1.1 

Content-Type: application/json

{
    "media" : {
        "title" : "Baby's first update video!",
        "description" : "A lovely new description for your new video.",
        "parent_id" : "id of new parent(optional field)",
        "authored_by": "author"
    }
}
Deleting Medium
DELETE /media/{id}

Requires Permission assigning Role CONTENT_DELETER on the parent Container of the given Medium.

Path variables

id
number required

The id of media

Example:
1

Responses

204 No Content
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/media/1 HTTP/1.1 
Copying Medium
POST /media/{id}/copy

Creates a full copy of a given medium.

Requires Permission assigning Role VIEW_CONTENT on the given Medium.

Path variables

id
string required

The id of medium

Example:
123

Request parameters

target_container_id
string required

The id of Container where Medium will be copying. Requires Permission assigning Role CREATE_CONTENT_COPY_MEDIA on the given Container.

Example:
1234

Responses

401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

201 Created
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Medium.

POST https://tenant.kzoplatform.com/api/media/123/copy?target_container_id=1234 HTTP/1.1 

HTTP/1.1 201 Created 
Original Videos

The purpose of Original Videos is to accept upload of a video file.

GET /original_video/{id}
POST /media/{id}/original_video
PUT /original_videos/{id}
Viewing Original Video
GET /original_video/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium.

Path variables

id
number required

The ID of the Original Video

Example:
123

Responses

200 OK

Action ORIGINAL_VIDEO___UPLOAD provides an URL to which the upload should be performed, as well as all information necessary for upload. The only upload method supported at the moment is direct upload to AWS S3 via POST form. See AWS S3 howto for details on how to perform the upload. All additional attributes required to compose the form are provided in meta.actions.post_presigned_s3.

Actions ORIGINAL_VIDEO___UPLOAD and ORIGINAL_VIDEO___DOWNLOAD are never available at the same time. The former is available only when the resource pipeline is in the status EDITING, the latter is only available when it is in the status READY and sometimes ERROR.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/original_video/234 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "original_videos": {
        "id": "234",
        "trim_beginning_msec": 0,
        "trim_end_msec": null,
        "href": "https://tenant.kzoplatform.com/api/original_videos/234",
        "links" : {
            "parent": {
                "id": 12,
                "type": "media"
            }
        },
        "meta": {
            "stream_name": "567/video_rendition/mp4:234.mp4",
            "pipeline_status": "EDITING",
            "pipeline_resource": {
                "href": "https://tenant.kzoplatform.com/api/original_videos/234",
                "type": "original_videos"
            },
            "actions": [{
                "label": "ORIGINAL_VIDEO___UPLOAD",
                "href": "http://uploads-presigned-post-s3.s3.amazonaws.com/",
                "method": "POST",
                "post_presigned_aws_s3": {
                    "key": "123/ORIGINAL_VIDEO/456",
                    "AWSAccessKeyId": "AKIAJQEXAMPLEEXAMPLE",
                    "acl": "bucket-owner-full-control",
                    "policy": "asdklfjadskf...283749234",
                    "signature": "123...kjdfgkj"
                }
            }, {
                "label": "ORIGINAL_VIDEO___DOWNLOAD",
                "href": "http://d6mgdbc2kfx06.cloudfront.net/...",
                "method": "GET"
            }
            ...
            ]
        }
        ...
    },
    "linked": {},
    "meta": {}
}
Creating Original Video
POST /media/{id}/original_video

Creates resource to hold Original Video. Attribute meta.actions for meta.action.label=ORIGINAL_VIDEO___UPLOAD provide information on how to upload the video file.

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the given Medium.

Path variables

id
number required

The ID of the Medium for which this Original Video is being created.

Example:
1

Request body

Object
original_videos
Object
trim_beginning_msec
integer nullable
trim_end_msec
integer nullable

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Original Video.

POST https://tenant.kzoplatform.com/api/media/1/original_video HTTP/1.1 

Content-Type: application/json

{
    "original_videos": {
    }
}
POST https://tenant.kzoplatform.com/api/media/1/original_video HTTP/1.1 

Content-Type: application/json

{
    "original_videos": {
        "trim_beginning_msec": 1000
    }
}
POST https://tenant.kzoplatform.com/api/media/1/original_video HTTP/1.1 

Content-Type: application/json

{
    "original_videos": {
        "trim_beginning_msec": 1000,
        "trim_end_msec": 1000
    }
}
Updating Original Video
PUT /original_videos/{id}

Changes trimming parameters of the video. If a parameter was actually changed, the video has to be processed.

Requires Permission assigning Role CONTENT_UPDATER, CONTENT_CREATOR, CONTENT_CREATOR_UPLOAD_MEDIA, CONTENT_CREATOR_RECORD_MEDIA or CONTENT_CREATOR_COPY_MEDIA on the parent Container of the parent Medium.

The response is the same as that of the method Viewing Original Video.

Path variables

id
string required

The ID of the Original Video

Request body

Object
original_videos
Object
trim_beginning_msec
integer nullable

pass null to keep the current value unchanged

trim_end_msec
integer nullable

pass null to keep the current value unchanged

Video Renditions
GET /video_renditions/{id}
GET /video_renditions/{ids}
Viewing Video Rendition
GET /video_renditions/{id}

Path variables

id
number required

The ID of the Video Rendition

Example:
1

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/video_renditions/234 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "video_renditions": {
        "id": "234",
        "href": "https://tenant.kzoplatform.com/api/video_renditions/234",
        "links" : {
            "parent": {
                "id": 12,
                "type": "media"
            }
        },
        "meta": {
            "actions": [{
                "label": "VIDEO_RENDITION___DOWNLOAD",
                "href": "http://d6mgdbc2kfx06.cloudfront.net/...",
                "method": "GET"
            }
            ...
            ]
        }
        ...
    },
    "linked": {},
    "meta": {}
}
Viewing Multiple Video Renditions
GET /video_renditions/{ids}

Path variables

ids
string optional

Comma-separated list of the IDs of multiple Video Renditions

Example:
1,2

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/video_renditions/1,2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "video_renditions": [{
        "id" : "1"
        ...
    }, {
        "id" : "2"
        ...
    }]
    ...
}
Video Rendition Options
GET /video_rendition_options/{id}
GET /video_rendition_options
Viewing Video Rendition Option
GET /video_rendition_options/{id}

Requires authenticated user.

Path variables

id
number optional

The ID of the Video Rendition Option

Example:
123

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/video_rendition_options/12 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "video_rendition_options": {
        "links": [],
        "meta": {},
        "id": 123,
        "href": "https://tenant.kzoplatform.com/api/video_rendition_options/123",
        "amazon_preset_id": "1409118559066-rg63pm",
        "video_bitrate": 300,
        "video_codec": "mp4"
        ...
    },
    "linked": [],
    "meta": {}
}
Searching Video Rendition Options
GET /video_rendition_options

Limited functionality: returns all Video Rendition Options.

Requires authenticated user.

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/video_rendition_options HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "video_rendition_options": [{
        "id": 12
        ...
    }, {
        "id": 34
        ...
    }
    ...
    ]
    ...
}
Screenshots
GET /screenshot/{id}
GET /screenshots/{ids}
Viewing Screenshot
GET /screenshot/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium.

Path variables

id
number required

The ID of the Screenshot

Example:
1

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: created_by,modified_by, media,screenshot_options.

Example:
screenshot_options

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/screenshot/14 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "screenshots": {
        "id" : "14",
        "width": 1920,
        "height": 1080,
        "default": false,
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "href": "https://tenant.kzoplatform.com/api/screenshots/14",
        "links" : {
            "medium": 123,
            "screenshot_option": 2,
            "created_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "modified_by" : {
                "username" : "admin",
                "type" : "users"
            }
        },
        "meta": {
            "actions": [{
                "label": "SCREENSHOT___GET",
                "href": "https://tenant.kzoplatform.com/api/screenshots/14",
                "method": "GET"
            }, {
                "label": "SCREENSHOT___DOWNLOAD",
                "href": "http://d6mgdbc2kfx06.cloudfront.net/...",
                "method": "GET"
            }
            ...
            ]
        }
    },
    "linked": {
        "media": [{
            "id": 123
            ...
        }],
        "users": [{
            "id": 2,
            "username": "admin"
            ...
        }],
        "screenshot_options": [{
            "id": 2
            ...
        }]
    },
    "meta": {}
}
Viewing Multiple Screenshots
GET /screenshots/{ids}

Requires Permission assigning Role CONTENT_VIEWER on the parent Containers of the parent Media.

Path variables

ids
string optional

The IDs of the Screenshots

Example:
12,34

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: created_by,modified_by, media,screenshot_options.

Example:
media

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

This example only demonstrates the key differences of the response from the response of the method Viewing Screenshot.

GET https://tenant.kzoplatform.com/api/screenshots/12,34 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "screeshots": [{
        "id" : "12"
        ...
    }, {
        "id" : "34"
        ...
    }]
    ...
}
Screenshot Options
GET /screenshot_options/{id}
GET /screenshot_options
PUT /screenshot_options/{id}
Viewing Screenshot Option
GET /screenshot_options/{id}

Screenshot option types are vertcal resolutions of images.

Requires authenticated user.

Path variables

id
number optional

The ID of the Screenshot Option

Example:
12

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/screenshot_options/12 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "screenshot_options": {
        "id": 123,
        "href": "https://tenant.kzoplatform.com/api/screenshot_options/12",
        "width": 295,
        "height": 166,
        "screenshot_type": "166",
        "default": false,
        "playicon": false
        "links": [],
        "meta": {}
    },
    "linked": [],
    "meta": {}
}
Searching Screenshot Options
GET /screenshot_options

Limited functionality: returns all Screenshot Options.

Requires authenticated user.

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/screenshot_options HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "screenshot_options": [{
        "id": 12
        ...
    }, {
        "id": 34
        ...
    }
    ...
    ]
    ...
}
Replacing Screenshot Options
PUT /screenshot_options/{id}

Replacing thumbnail_type of screenshot option. Allowed values: NONE, DEFAULT, SMALL, MEDIUM, LARGE, SMALL_PLAYICON, MEDIUM_PLAYICON, LARGE_PLAYICON.

Requires Permission assigning Role MANAGE_TENANT on the given Container.

Path variables

id
number required

The id of screenshot options

Example:
123

Examples

PUT https://tenant.kzoplatform.com/api/screenshot_options/234 HTTP/1.1 

Content-Type: application/json

{
  "screenshot_options": {
    "thumbnail_type": "LARGE_PLAYICON"
  }
}
Montages
GET /montages/{id}
GET /montages/{ids}
Viewing Montage
GET /montages/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium.

Path variables

id
number optional

The ID of the Montage

Example:
123

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: created_by,modified_by, media,montage_options.

Example:
media

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/montages/14 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "montages": {
        "id" : "14",
        "page_number": 2,
        "number_pages": 4,
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "href": "https://tenant.kzoplatform.com/api/montages/14",
        "links" : {
            "medium": 123,
            "montage_option": 2,
            "created_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "modified_by" : {
                "username" : "admin",
                "type" : "users"
            }
        },
        "meta": {
            "actions": [{
                "label": "MONTAGE___GET",
                "href": "https://tenant.kzoplatform.com/api/montages/14",
                "method": "GET"
            }, {
                "label": "MONTAGE___DOWNLOAD",
                "href": "http://d6mgdbc2kfx06.cloudfront.net/...",
                "method": "GET"
            }
            ...
            ]
        }
    },
    "linked": {
        "media": [{
            "id": 123
            ...
        }],
        "users": [{
            "id": 2,
            "username": "admin"
            ...
        }],
        "montage_options": [{
            "id": 2
            ...
        }]
    },
    "meta": {}
}
Viewing Multiple Montages
GET /montages/{ids}

Requires Permission assigning Role CONTENT_VIEWER on the parent Containers of the parent Media.

Path variables

ids
string optional

The IDs of the Montages

Example:
12,34

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: created_by,modified_by, media,montage_options.

Example:
media

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/montages/12,34 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "montages": [{
        "id" : "12"
        ...
    }, {
        "id" : "34"
        ...
    }]
    ...
}
Montage Options
GET /montage_options/{id}
Viewing Montage Option
GET /montage_options/{id}

Requires authenticated user.

Path variables

id
string optional

The ID of the Montage Option

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/montage_options/123 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "montage_options": {
        "id": 123,
        "href": "https://tenant.kzoplatform.com/api/montage_options/123",
        "width": 1000,
        "height": 750,
        "number_cells_x": 10,
        "number_cells_y": 10,
        "cell_interval_msec": 5000,
        "links": [],
        "meta": {}
    },
    "linked": [],
    "meta": {}
}
Searching Montage Options
GET /montages

Limited functionality: returns all Montage Options.

Requires authenticated user.

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/montages HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "montage_options": [{
        "id": 12
        ...
    }, {
        "id": 34
        ...
    }
    ...
    ]
    ...
}
Slide Decks
GET /slide_decks/{id}
POST /media/{id}/slide_deck
DELETE /slide_decks/{id}
Viewing Slide Deck
GET /slide_decks/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium.

Path variables

id
number required

The ID of the Slide Deck

Example:
1

Responses

200 OK

Slide Deck will accept upload of video file. Action SLIDE_DECK___UPLOAD provides an URL to which the upload should be performed, as well as all information necessary for upload. The only upload method supported at the moment is direct upload to AWS S3 via POST form. See AWS S3 howto for details on how to perform the upload. All additional attributes required to compose the form are provided in meta.actions.post_presigned_s3.

Actions SLIDE_DECK___UPLOAD and SLIDE_DECK___DOWNLOAD are never available at the same time. The former is available only when the resource pipeline is in the status EDITING, the latter is only available when it is in the status READY and sometimes ERROR.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/slide_decks/789 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "slide_decks": {
        "id": "789",
        "number_slides": 10,
        "href": "https://tenant.kzoplatform.com/api/slide_decks/234",
        "links" : {
            "parent": {
                "id": 12,
                "type": "media"
            }
        },
        "meta": {
            "pipeline_status": "EDITING",
            "pipeline_resource": {
                "href": "https://tenant.kzoplatform.com/api/slide_decks/789",
                "type": "slide_decks"
            },
            "actions": [{
                "label": "SLIDE_DECK___UPLOAD",
                "href": "http://uploads-presigned-post-s3.s3.amazonaws.com/",
                "method": "POST",
                "post_presigned_aws_s3": {
                    "key": "123/SLIDE_DECK/456",
                    "AWSAccessKeyId": "AKIAJQEXAMPLEEXAMPLE",
                    "acl": "bucket-owner-full-control",
                    "policy": "asdklfjadskf...283749234",
                    "signature": "123...kjdfgkj"
                }
            }, {
                "label": "SLIDE_DECK___DOWNLOAD",
                "href": "http://d6mgdbc2kfx06.cloudfront.net/...",
                "method": "GET"
            }
            ...
            ]
        }
        ...
    },
    "linked": {},
    "meta": {}
}
Creating Slide Deck
POST /media/{id}/slide_deck

Creates resource to hold the Slide Deck. Attribute meta.actions for meta.action.label=SLIDE_DECK___UPLOAD provide information on how to upload the slide deck file.

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the given Medium.

Path variables

id
string required

The ID of the Medium in which Slide Deck is being created.

Example:
111

Request body

Request body is ignored.

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Slide Deck.

POST https://tenant.kzoplatform.com/api/media/111/slide_deck HTTP/1.1 
Deleting Slide Deck
DELETE /slide_decks/{id}

Deletes the given Slide Deck, its Slides and associated Used Slides.

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the parent Medium.

Path variables

id
number required

The ID of the Slide Deck to be deleted

Example:
123

Responses

204 No Content
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/slide_decks/123 HTTP/1.1 
Slides
GET /slides/{id}
Viewing Slide
GET /slides/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium.

Path variables

id
number required

The ID of the Slide

Example:
1

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: slides.created_by,slides.modified_by, slide_decks,slide_decks.created_by,slide_decks.modified_by

Example:
slide_decks

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/slides/1 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "slides": {
        "id" : "14",
        "page_number": 4,
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "href": "https://tenant.kzoplatform.com/api/slides/14",
        "links" : {
            "slide_deck": 123,
            "created_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "modified_by" : {
                "username" : "admin",
                "type" : "users"
            }
        },
        "meta": {
            "actions": [{
                "label": "SLIDE___GET",
                "href": "https://tenant.kzoplatform.com/api/slides/14",
                "method": "GET"
            }, {
                "label": "SLIDE___DOWNLOAD",
                "href": "http://d6mgdbc2kfx06.cloudfront.net/...",
                "method": "GET"
            }
            ...
            ]
        }
    },
    "linked": {
        "slide_decks": {
            "id": 123
            ...
        },
        "users": {
            "id": 2,
            "username": "admin"
            ...
        }
    },
    "meta": {}
}
Used Slides
GET /used_slides/{id}
GET /used_slides/{ids}
POST /media/{id}/used_slide
PUT /used_slides/{id}
PATCH /used_slides/{id}
DELETE /used_slides/{id}
Viewing Used Slide
GET /used_slides/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium.

Path variables

id
number required

The ID of Used Slide

Example:
1

Responses

200 OK
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/used_slides/14 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "slides": {
        "id" : "14",
        "start_msec" : 15,
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "href": "https://tenant.kzoplatform.com/api/used_slides/14",
        "links" : {
            "slide": 123,
            "medium": 456,
            "created_by" : {
                "username" : "admin",
                "type" : "users"
            },
            "modified_by" : {
                "username" : "admin",
                "type" : "users"
            }
        },
        "meta": {
            "actions": [{
                "label": "USED_SLIDE___GET",
                "href": "https://tenant.kzoplatform.com/api/used_slides/14",
                "method": "GET"
            }
            ...
            ]
        }
    },
    "linked": {
        "slides": {
            "id": 123
            ...
        },
        "users": {
            "id": 2,
            "username": "admin"
            ...
        },
        "media": {
            "id": 456
            ...
        }
    },
    "meta": {}
}
Viewing Multiple Used Slides
GET /used_slides/{ids}

Path variables

ids
string required

Comma-separated list of the IDs of multiple Used Slides

Example:
1,2

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: slides.created_by,slides.modified_by, slide_decks,slide_decks.created_by,slide_decks.modified_by

Example:
slide_decks

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

This example only demonstrates the key differences of the response from the response of the method Viewing Slide.

GET https://tenant.kzoplatform.com/api/used_slides/1,2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "used_slides": [{
        "id" : "1"
        ...
    }, {
        "id" : "2"
        ...
    }]
    ...
}
Creating Used Slide
POST /media/{id}/used_slide

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the given Medium.

Path variables

id
number required

The ID of media

Example:
1

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Used Slide.

POST https://tenant.kzoplatform.com/api/media/1/used_slide HTTP/1.1 

Content-Type: application/json

{
    "used_slides": {
        "slide": 234,
        "start_msec": 456
    }
}
Replacing Used Slide
PUT /used_slides/{id}

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the parent Medium.

Path variables

id
number required

The id of slide

Example:
1

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Used Slide.

PUT https://tenant.kzoplatform.com/api/used_slides/1 HTTP/1.1 

Content-Type: application/json

{
    "used_slides": {
        "slide": 234,
        "start_msec": 456
    }
}
Updating Used Slide
PATCH /used_slides/{id}

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the parent Medium.

Path variables

id
number required

The ID of the Used Slide

Example:
1

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Used Slide.

PATCH https://tenant.kzoplatform.com/api/used_slides/1 HTTP/1.1 

Content-Type: application/json

[{ 
    "op": "replace", 
    "path": "/start_msec", 
    "value": 2000
}]
Deleting Used Slide
DELETE /used_slides/{id}

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the parent Medium.

Path variables

id
number required

The id of slide

Example:
1

Responses

204 No Content
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/used_slides/1 HTTP/1.1 
Chapters
GET /chapters/{id}
GET /chapters/{ids}
POST /media/{id}/chapter
PATCH /chapters/{id}
PUT /chapters/{id}
DELETE /chapters/{id}
Viewing Chapter
GET /chapters/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium.

Path variables

id
number required

The id of chapter

Example:
1

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: modified_by,created_by,media,media.modified_by,media.created_by.

Example:
media

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/chapters/14?include=modified_by,created_by,media HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "chapters": {
        "id" : "14",
        "title" : "Yep, this is title",
        "start_msec" : 5,
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "links" : {
            "media" : 111,
            "created_by" : {
                "username" : "admin",
                "type": "users",
            },
            "modified_by" : {
                "username" : "admin",
                "type": "users",
            }
        },
        "meta": {
            "actions": [{
                "label": "CHAPTER___GET",
                "href" : "https://tenant.kzoplatform.com/api/chapters/14",
                "method" : "GET"
            }],
            "pipeline_status": "READY",
            "pipeline_resource": {
                "href": "https://tenant.kzoplatform.com/api/media/111",
                "type": "media"
            }
        }
    },
    "linked": {
        "media":  {
            "id": 111
            ...
        },
        "users": {
            "id": 2,
            "username": "admin"
            ...
        }
    },
    "meta": {}
}
Viewing Multiple Chapters
GET /chapters/{ids}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Media.

Path variables

ids
string optional

Comma-separated list of the IDs of multiple Chapters

Example:
22,33

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: modified_by,created_by,media,media.modified_by,media.created_by.

Example:
media

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

This example only demonstrates the key differences of the response from the response of the method Viewing Chapter.

GET https://tenant.kzoplatform.com/api/chapters/22,33 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "chapters": [{
        "id" : "22"
        ...
    }, {
        "id" : "33"
        ...
    }]
    ...
}
Create chapter
POST /media/{id}/chapter

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the given Medium.

Path variables

id
number required

The id of media

Example:
1

Responses

201 CREATED
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Chapter.

POST https://tenant.kzoplatform.com/api/media/1/chapter HTTP/1.1 

Content-Type: application/json

{
    "chapters": {
        "title" : "Yep, this is title",
        "start_msec" : 5
    }
}
Update chapter
PATCH /chapters/{id}

Requires Permission assigning Role CONTENT_UPDATER on the parent Container of the given Medium.

Path variables

id
number required

The id of chapter

Example:
1

Responses

200 OK
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

PATCH https://tenant.kzoplatform.com/api/chapters/1 HTTP/1.1 

Content-Type: application/json

[{ 
    "op": "replace", 
    "path": "/title", 
    "value": "We are changed title"
}, { 
    "op": "replace", 
    "path": "/start_msec", 
    "value": 25
}]
Replace chapter
PUT /chapters/{id}

Requires Permission assigning Role CONTENT_UPDATER on the parent Container of the given Medium.

Path variables

id
number required

The id of chapter

Example:
1

Responses

200 OK
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

PUT https://tenant.kzoplatform.com/api/chapters/1 HTTP/1.1 

Content-Type: application/json

{
    "chapters": {
        "title" : "Nope, this is no title",
        "start_msec" : 10
    }
}

HTTP/1.1 200 OK 
Delete chapter
DELETE /chapters/{id}

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the given Medium.

Path variables

id
number required

The id of chapter

Example:
1

Responses

204 No Content
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/chapters/1 HTTP/1.1 
Search
GET /search
Searching Content
GET /search

Search content. The results are returned grouped by Containers.

Pagination: primary (containers).

Request parameters

q
string required

Term to search for

Example:
awesome
domain
string optional

Attributes to be searched.
Possble value is a comma-separated list of any of the following:
media -- Media title and/or description,
containers -- Container title and/or description,
slides -- Slide text,
chapters -- Chapter title,
comments -- text of Comments and/or Replies,
closed_captions_sets -- Closed captions text, everything -- all of the above (default value).

Example:
media,containers
within_container
number optional

Limits the resultset to the Container with the specified ID and all content below it in the Container hierarchy.

Example:
123
page
number optional

The number of page (see Pagination).

Max:2147483647
Default:
1
page_size_primary
number optional

The maximum number of primary resources are to be returned (see Pagination).

Min:1 Max:2147483647
Default:
20

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/search?q=awesome&domain=containers,chapters HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "containers": [{
        "id" : "1",
        "title": "some title 1",
        "description": "some descr 1",
        "links": {
            "media": [ 5 ]
            ...
        }
        ...
    }, {
        "id" : "2",
        "title": "c2",
        "description": "nothing awesome"
        ...
    }],
    "linked": {
        "media": [{
            "id": 5,
            "title": "some title 3",
            "description": "some descr 3",
            "links": {
                "chapters": [ 6 ]
                ...
            }
            ...
        }],
        "chapters": [{
            "id": 6,
            "title": "pure awesomeness"
            ...
        }],
        "closed_captions_sets": [
            {
                "created_at": "2017-03-16T05:57:32.248Z",
                "hash_md5": "86e66f62e8ef434fbc89bff52e41404e",
                "hash_sha1": "415f5403fa0735ab28407cdd6c6df94222eb1df9",
                "href": "https://tenant.kzoplatform.com/api/closed_captions_sets/848167560019973580",
                "id": "848167560019973580",
                "size": 114830,
                "links": {
                    "closed_captions_cues": [
                        "848165158084679110.216",
                        "848165158084679110.570"
                    ],
                    "language": {
                        "id": "en",
                        "type": "languages"
                    },
                },
                ...
            }
        ],
         "closed_captions_cues": [
            {
                "start_msec": "925024",
                "end_msec": "929094",
                "id": "848167560019973580.216",
                "text": "Probably doing something awesome, right?"
            },
            {
                "start_msec": "2614211",
                "end_msec": "2615847",
                "id": "848167560019973580.570",
                "text": "What I would like to see is... something awesome."
            }
        ],
        "languages": [
            {
                "id": "en",
                "name": "English"
            }
        ]
    },
    "meta": {}
}
Comments
GET /comments/{id}
GET /comments/{ids}
POST /media/{id}/comment
DELETE /comments/{id}
Viewing Comment
GET /comments/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium.

Path variables

id
number required

The id of Comment

Example:
123

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: comments.created_by,comments.updated_by, replies,replies.created_by,replies.updated_by, parent,parent.created_by,parent.updated_by.
If Replies are included, it is assumed that unlimited depth is requested.

Example:
parent

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/comments/123 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "comments" : {
        "id" : "123",
        "text" : "This is new comment", 
        "time_msec" : 36,
        "coordinate_x" : 22.46,
        "coordinate_y" : 32.46,
        "coordinate_radius" : 10.5,
        "coordinate_target" : "VIDEO",
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "links" : {
            "parent": {
                "id": 4,
                "type": "media"
            },
            "replies": [ 567, 890 ],
            "created_by" : {
                "username" : "admin",
                "type": "users",
            },
            "modified_by" : {
                "username" : "admin",
                "type": "users",
            }
        },
        "meta" : {
            "actions": [{
                "label": "COMMENT___CREATE_REPLY"
                ...
            }, {
                "label": "COMMENT___DELETE"
                ...
            }]
        }
    },
    "linked" : {
        "media": [{
            "id": 4
            ...
        }],
        "users": [{
            "username": "admin"
            ...
        }],
        "replies": [{
            "id": 567
            ...
        }, {
            "id": 890
            ...
        }]
    },
    "meta" : {}
}
Viewing Multiple Comments
GET /comments/{ids}

Requires Permission assigning Role CONTENT_VIEWER on the parent Containers of the parent Media. The Comments may belong to different Containers, Media.

Path variables

ids
string optional

IDs of Comments

Example:
123,456

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: comments.created_by,comments.updated_by, replies,replies.created_by,replies.updated_by, parent,parent.created_by,parent.updated_by.
If Replies are included, it is assumed that unlimited depth is requested.

Example:
parent

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

This example only demonstrates the key differences of the response from the response of the method Viewing Comment

GET https://tenant.kzoplatform.com/api/comments/1,2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "conmments": [{
        "id" : "1"
        ...
    }, {
        "id" : "2"
        ...
    }]
    ...
}
Creating Comment
POST /media/{id}/comment

Requires Permission assigning Roles CONTENT_MANAGER or COMMENTATOR on the parent Container of the parent Medium.

Path variables

id
number required

The id of Medium

Example:
123

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Comment

POST https://tenant.kzoplatform.com/api/media/5/comment HTTP/1.1 

Content-Type: application/json

{
    "comments" : {
        "text" : "This is new comment", 
        "time_msec" : 36,
        "coordinate_x" : 22.46,
        "coordinate_y" : 32.46,
        "coordinate_radius" : 10.5,
        "coordinate_target" : "VIDEO"
    }
}
Deleting comment
DELETE /comments/{id}

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the parent Medium.

Path variables

id
number required

The ID of Comment

Example:
123

Responses

204 No Content
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/comments/456 HTTP/1.1 
Replies
GET /replies/{id}
GET /replies/{ids}
POST /comments/{id}/reply
POST /replies/{id}/reply
DELETE /replies/{id}
Viewing Reply
GET /replies/{id}

Requires Permission assigning Role CONTENT_VIEWER on the parent Container of the parent Medium of the parent Comment.

Path variables

id
number optional

The ID of the Reply

Example:
123

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: comments.created_by,comments.updated_by, replies,replies.created_by,replies.updated_by, parent,parent.created_by,parent.updated_by.
If Replies are included, it is assumed that unlimited child depth is requested.

Example:
parent

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/replies/123 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "replies" : {
        "id" : "123",
        "text" : "This is new comment", 
        "published" : true,
        "created_at" : "2012-10-10T14:12:24Z",
        "modified_at" : "2012-10-10T14:12:24Z",
        "links" : {
            "parent": {
                "id": 345,
                "type": "comment"
            }
            "replies": [ 567, 890 ],
            "created_by" : {
                "username" : "admin",
                "type": "users",
            },
            "modified_by" : {
                "username" : "admin",
                "type": "users",
            }
        },
        "meta" : {
            "actions": [{
                "label": "REPLY___CREATE_REPLY"
                ...
            }, {
                "label": "REPLY___DELETE"
                ...
            }]
        }
    },
    "linked" : {
        "comments": [{
            "id": 345
            ...
        }],
        "users": [{
            "username": "admin"
            ...
        }],
        "replies": [{
            "id": 567
            ...
        }, {
            "id": 890
            ...
        }]
    },
    "meta" : {}
}
Viewing Multiple Replies
GET /replies/{ids}

Requires Permission assigning Role CONTENT_VIEWER on the parent Containers of the parent Media of the parent Comments. The Replies may belong to different Containers, Media, Comments, Replies.

Path variables

ids
string optional

The IDs of the Replies

Example:
23,45

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response.
Default value: empty.
What can be included at most: comments.created_by,comments.updated_by, replies,replies.created_by,replies.updated_by, parent,parent.created_by,parent.updated_by.
If Replies are included, it is assumed that unlimited child depth is requested.

Example:
parent

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

This example only demonstrates the key differences of the response from the response of the method Viewing Reply. It also illustrates that requested Replies may belong to different parent Comments or Replies.

GET https://tenant.kzoplatform.com/api/replies/12,56 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "replies": [{
        "id" : "12",
        "links": {
            "parent": {
                "id": 34,
                "type": "comment"
            }
            ...
        }
        ...
    }, {
        "id" : "56",
        "links": {
            "parent": {
                "id": 78,
                "type": "reply"
            }
            ...
        }
        ...
        ...
    }]
    ...
}
Creating Reply to Comment
POST /comments/{id}/reply

Requires Permission assigning Roles CONTENT_MANAGER or COMMENTATOR on the parent Container of the parent Medium of the parent Comment.

Path variables

id
number required

The id of the parent Comment

Example:
123

Responses

201 Created
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the method Viewing Reply

POST https://tenant.kzoplatform.com/api/comments/5/reply HTTP/1.1 

Content-Type: application/json

{
    "replies": {
        "text" : "This is a reply to comment"
    }
}
Creating Reply to Reply
POST /replies/{id}/reply

Requires Permission assigning Roles CONTENT_MANAGER or COMMENTATOR on the parent Container of the parent Medium of the parent Comment.

Path variables

id
number optional

The ID of the parent Reply

Example:
34

Responses

201 Created
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

POST https://tenant.kzoplatform.com/api/replies/34/reply HTTP/1.1 

Content-Type: application/json

{
    "replies": {
        "text" : "This is a reply to reply"
    }
}
Deleting Reply
DELETE /replies/{id}

Requires Permission assigning Role CONTENT_MANAGER or CONTENT_UPDATER on the parent Container of the parent Medium of the parent COmment.

Path variables

id
number required

The id of reply

Example:
1

Responses

204 No Content
400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/replies/1 HTTP/1.1 
Users
GET /users/{username}
GET /users/{usernames}
GET /users
POST /users
PATCH /users/{username}
PUT /users/{username}
DELETE /users/{username}
Viewing User
GET /users/{username}

Requires authenticated user.

Pagination: groups.

Path variables

username
string required

Username

Example:
admin

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: modified_by,created_by,groups,groups.modified_by, groups.created_by,roles,avatars,home_container.

Example:
users
group_labels
string optional

Which kinds of groups are returned in associated objects if groups are requested in include.
Possible values: INDIVIDUAL,NONINDIVIDUAL,ALL.
NONINDIVIDUAL indicates that groups with all labels other than INDIVIDUAL should be returned. INDIVIDUAL and ALL are self-explanatory.
Default value: NONINDIVIDUAL.

page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/users/admin HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "users": {
        "id": "2",
        "username": "admin",
        "first_name": "joe",
        "last_name": "smith",
        "email": "email@email.com",
        "created_at": "2012-10-10T14:12:24Z",
        "modified_at": "2012-10-10T14:12:24Z",
        "href": "https://tenant.kzoplatform.com/api/users/admin",
        "avatar_href": "http://d6mgdbc2kfx06.cloudfront.net/...",
        "published": true,
        "links": {
            "created_by": {
                "username": "system",
                "type": "users"
            },
            "modified_by": {
                "username": "system",
                "type": "users"
            },
            "groups": [ 1, 2 ]
        },
        "meta": {
            "pipeline_status": "READY",
            "pipeline_resource": {
                "href": "https://tenant.kzoplatform.com/api/users/admin",
                "type": "containers"
            },
            "actions": [{
                "label" : "USER__EDIT_METADATA",
                "href" : "https://tenant.kzoplatform.com/api/users/admin",
                "method" : "PATCH"
            }, {
                "label" : "USER__UPDATE",
                "href" : "https://tenant.kzoplatform.com/api/users/admin",
                "type" : "PUT"
            }]
        }
    },
    "linked": {
        "users": [{
            "id": 1,
            "username": "system"
            ...
        }],
        "groups": [{
            "id": 1
            ...
        },{
            "id": 2
            ...
        }]
    },
    "meta": {}
}
Viewing Multiple Users
GET /users/{usernames}

Filtering is not supported.

Requires authenticated user.

Pagination: groups.

Path variables

usernames
string required

Comma-separated list of the usernames of multiple users

Example:
admin,system

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: modified_by,created_by,groups,groups.modified_by, groups.created_by,roles,avatars,home_container.

Example:
users
group_labels
string optional

Which kinds of groups are returned in associated objects if groups are requested in include.
Possible values: INDIVIDUAL,NONINDIVIDUAL,ALL.
NONINDIVIDUAL indicates that groups with all labels other than INDIVIDUAL should be returned. INDIVIDUAL and ALL are self-explanatory.
Default value: NONINDIVIDUAL.

page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/users/admin,system HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "users": [{
        "username" : "system"
        ...
    }, {
        "username" : "admin"
        ...
    }]
    ...
}
Searching Users
GET /users

Requires authenticated user.

Pagination: primary, groups.

Request parameters

created_by
string optional

Filtering by creator's username with partial matching

Example:
admin
created_at_from
string optional

Filtering by creation time. Specifies beginning of inclusive time interval using ISO8601 standard. If not set, it means from the beginning of time.

Example:
2012-10-10T14:12:24.324Z
created_at_to
string optional

Filtering by creation time. Specifies end of inclusive time interval using ISO8601 standard. If not set, it means until the end of time.

Example:
2013-10-10T14:12:24.324Z
modified_by
string optional

Filtering by last modifier's username with partial matching

Example:
bob
modified_at_from
string optional

Filtering by modification time. Specifies beginning of exclusive time interval using ISO8601 standard. If not set, it means from the beginning of time.

Example:
2012-10-10T14:12:24.324Z
modified_at_to
string optional

Filtering by modification time. Specifies end of exclusive time interval using ISO8601 standard. If not set, it means until the end of time.

Example:
2013-10-10T14:12:24.324Z
email
string optional

Filtering by email with partial matching.

Example:
com
username
string optional

Filtering by username with partial matching.

Example:
bob
first_name
string optional

Filtering by first name with partial matching.

Example:
john
last_name
string optional

Filtering by last name with partial matching.

Example:
smith
include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: modified_by,created_by,groups,groups.modified_by, groups.created_by,users.roles,home_container.

Example:
groups
sort
string optional

Comma-separated list of attributes by which sorting should be performed. The default sort order is ascending. A - prefix to attribute name on any sort field specifies a descending sort order. Default is unsorted. What can be included at most: TBD

Example:
-username
q
string optional

Filtering to match any of the following: username, email, first name, last name.

Example:
john
group_labels
string optional

Which kinds of groups are returned in associated objects if groups are requested in include.
Possible values: INDIVIDUAL,NONINDIVIDUAL,ALL.
NONINDIVIDUAL indicates that groups with all labels other than INDIVIDUAL should be returned. INDIVIDUAL and ALL are self-explanatory.
Default value: NONINDIVIDUAL.

group_id
number optional

If specified, return only members of a group with a given ID.

Example:
1
page
number optional

The number of page (see Pagination).

Max:2147483647
Default:
1
page_size_primary
number optional

The maximum number of primary resources are to be returned (see Pagination).

Min:1 Max:2147483647
Default:
20
page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the Viewing Multiple Users.

GET https://tenant.kzoplatform.com/api/users?include=users&sort=-username HTTP/1.1 
Creating User
POST /users

Requires Permission assigning Role:

  • IDENTITY_MANAGER for Users of all authentication_types.
  • INTEGRATION_VISITOR_IDENTITY_MANAGER for Users of all authentication_type=INTEGRATION_VISITOR.

User authentication types: NONE, PASSWORD, PUBLIC, IPAAS, SAML2, INTEGRATION_RESIDENT, INTEGRATION_VISITOR.

Allowed user authentication types via API: PASSWORD, INTEGRATION_RESIDENT, INTEGRATION_VISITOR.

Responses

201 Created
Headers
Location
string optional

Contains the URI of the newly created resource.

401 Unauthorized

The request requires Authentication and Authorization.

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the Viewing User.

POST https://tenant.kzoplatform.com/api/users HTTP/1.1 

Content-Type: application/json

{
    "users" : {
        "username" : "cparker",
        "first_name" : "Chris", 
        "last_name" : "Parker",
        "email" : "cparker@example.org",
        "password" : "password",
        "authentication_type": "PASSWORD"
    }
}
Updating User
PATCH /users/{username}

Requires Permission assigning Role:

  • IDENTITY_MANAGER for Users of all authentication_types.
  • INTEGRATION_VISITOR_IDENTITY_MANAGER for Users of all authentication_type=INTEGRATION_VISITOR.
  • Or if current user is user for editing (the same users).

Path variables

username
string required

Username

Example:
admin

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the Viewing User.

PATCH https://tenant.kzoplatform.com/api/users/admin HTTP/1.1 

Content-Type: application/json

[{
    "op": "replace", "path": "/email", "value": "new@example.org"  
}, {
    "op": "replace", "path": "/last_name", "value": "Bell"  
}]
Replacing User
PUT /users/{username}

Requires Permission assigning Role:

  • IDENTITY_MANAGER for Users of all authentication_types.
  • INTEGRATION_VISITOR_IDENTITY_MANAGER for Users of all authentication_type=INTEGRATION_VISITOR.
  • Or if current user is user for editing (the same users).

Path variables

username
string required

Username

Example:
admin

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

411 Length Required

The server refuses to accept the request without a defined Content-Length.

415 Unsupported media type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. For example, the server does not support the requested Content-Type.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

The response is the same as that of the Viewing User.

PUT https://tenant.kzoplatform.com/api/users/admin HTTP/1.1 

Content-Type: application/json

{
    "users" : {
        "username" : "cparker",
        "first_name" : "Chris", 
        "last_name" : "Parker",
        "email" : "cparker@example.org",
        "password" : "password"
    }
}
Deleting User
DELETE /users/{username}

Requires Permission assigning Role:

  • IDENTITY_MANAGER for Users of all authentication_types.
  • INTEGRATION_VISITOR_IDENTITY_MANAGER for Users of all authentication_type=INTEGRATION_VISITOR.

Path variables

username
string required

Username

Example:
admin

Responses

204 No Content
401 Unauthorized

The request requires Authentication and Authorization.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. Examples: PUT is attempted with outdated ETag, or execution of a currently unavailable method was attempted (see also error 405 and Workflow for details).

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

DELETE https://tenant.kzoplatform.com/api/users/admin HTTP/1.1 
Groups
GET /groups/{id}
GET /groups/{ids}
GET /groups
POST /groups
PATCH /groups/{id}
PUT /groups/{id}
DELETE /groups/{id}
POST /groups/{id}/users
DELETE /groups/{id}/users/{username}
Viewing Group
GET /groups/{id}

Requires authenticated user.

Pagination: users.

Path variables

id
number required

The id of group

Example:
1

Request parameters

include
string optional

Comma-separated list of associated objects which should be included in the response. Default value: empty. What can be included at most: modified_by,created_by,users,users.modified_by,users.created_by, permissions,permissions.modified_by,permissions.created_by.

group_labels
string optional

Which kinds of groups are returned.
Possible values: INDIVIDUAL,NONINDIVIDUAL,ALL.
NONINDIVIDUAL indicates that groups with all labels other than INDIVIDUAL should be returned. INDIVIDUAL and ALL are self-explanatory.
Default value: NONINDIVIDUAL.

page_size_related
number optional

The limit for paginated relationships (see Pagination).

Min:1 Max:2147483647
Default:
10

Responses

200 OK
401 Unauthorized

The request requires Authentication and Authorization.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.

404 Not Found

The server has not found anything matching the Request-URI.

406 Not Acceptable

The server cannot respond with content type specified in the Accept request header or the requested API Version is not supported by the server.

Examples

GET https://tenant.kzoplatform.com/api/groups/1?include=users,permissions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "linked": {
        "users": [{
            "id": 1,
            "username": "system"
            ...
        }, {
            "id": 2,
            "username": "admin"
            ...
        }, {
            "id": 22,
            "username": "bob"