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

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.

TBD

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

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

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

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

Not implemented yet.

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.

Pagination links

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.

Pagination links

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, ...}}}}]}

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"
    }
}