Before going any further, please ensure you have the following setup.

1. You must have a running Cumulus server of the same version or newer version than the CIP server. CIP works with both Workgroup and Enterprise editions of the Cumulus server. CIP does not work with Cumulus Single User, or versions of Cumulus earlier than Cumulus 8.5.
2. Your Cumulus Server needs an optional serial number for letting the CIP connect to it. This serial number needs to be activated.
3. Make sure your Cumulus server has a client license free to support write activities. CIP will reserve one or more licenses on startup (depending on your configuration).
4. Install CIP on some computer. It does not have to be the same as the one running the Cumulus Server.
5. For development you should have an up to date version of the Firefox browser with the “JSONView” plug-in installed. This will allow you to better see the results of some RESTful requests directly in the browser.
6. For developing your client-side code you can use whatever environment you feel comfortable with. CIP comes with a set of sample source files in different languages to be included in your project.

The instructions for Apache Tomcat can be found here:

1. Provide the user name and password in the request URL using the named parameters “user” and “password.”
2. Provide the user name and password in the request using HTTP Basic Access Authentication (http://en.wikipedia.org/wiki/Basic_access_authentication).
3. Provide a session ID for a valid session in the request. The session had to be opened with valid credentials.
4. In the URL refer to a catalog alias definition in the configuration file that includes user name and password.
5. Without any of the above CIP may initiate HTTP basic access authentication depending on a configuration option.
   In case the client software is a web browser it will ask the user to enter name and password for the realm “CIP.”
   See http://en.wikipedia.org/wiki/Basic_access_authentication for details about HTTP Basic Authentication.
6. If all the above fails CIP returns HTTP status 401 (Unauthorized) to the client.

Besides the typical HTTP Request-Response protocol CIP supports keeping a session for answering requests. The session is identified by a session ID and can store credentials and collections of items to be used across several requests. This way you only need to provide the credentials when opening the session and subsequent requests do not need the credentials anymore.

To start a session you send the session/open request to the CIP server. This will create a new session at the CIP and will return a “jsessionid” cookie as well as the “jsessionid” value in the response data. The value of “jsessionid” is an arbitrary string that your client software needs to keep.

Your client software then provides the “jsessionid” with every subsequent request. You can use either the HTTP cookie mechanism or URL rewriting to provide the “jsessionid” value to CIP.

When you are done with the session you can call the session/close operation to close the session at the server (also providing the “jsessionid”). Every attempt to issue another request for the same session will fail after the session is closed.

• a session/keepalive request is outstanding for more than the time interval specified plus an additional grace period of 60 seconds.
• any request other than session/keepalive is outstanding for more than the session timeout given in the session/open or configured in the CIP web.xml.

You have several options for specifying the parameters for catalog access: user, password, serveradddress, catalogname. They can be configured in the CIP configuration for a catalog, they can be kept in a session in the server and you can specify them in a request.

The CIP server evaluates these parameters in the following priority

1. Passing the parameter in a request has the highest priority and overwrites any of the below.
2. If you specified a collection name in the request the information kept in the collection is taken.
3. If you specified a session (passing a valid jsessionid) the parameter is taken from the session if it was specified when opening the session.
4. If the parameter is not specified by any of the above it is taken from the catalog configuration in the XML file.

Since 10.1.3: By passing the name of one of the configured catalogs in a parameter catalogname you can limit access to the one you specify.

CIP is assuming that the data is organized in the following way:

A server is identified by the server address string is serving one or more catalogs.

Each catalog consists of one or more tables which are identified by their name. The table with the name "AssetRecords" is storing asset information, another table named "Categories" contains categories. Additional tables may exist to store other information not directly related to assets.

Each table stores zero or more items identified by a number called "item ID."

The item ID is a unique identifier of an item inside a table of a catalog. You can safely identify the item representing an asset by specifying the catalog name and item ID (the table name for asset items is fixed).

The item ID is automatically generated and stable during the lifetime of an item.

You can configure pooling to be used when the user name is taken from a configured catalog alias.

Whenever you specify a user name in a request the CIP server will not attempt to use a connection pool but will create a separate connection to the server. To get better performance for subsequent requests with the same user name you should open a session using the user name and password as parameters. In this case the connection will be kept open and stored in the server-side session data.

We recommend using a pool to improve the request handling performance whenever you have configured a technical user to be used to connect to the Cumulus server.

If you want to use a pool you can configure the maximum size and some other parameters for the pool in the CIP configuration file (see the section about configuration below).

For each combination of a user name and catalog the CIP server will keep a separate pool of connections to the catalog.

Each pool (combination of user name and catalog) that is used for write access occupies a separate client license at the Cumulus server.

To let CIP server support the configured pool maximum size you need to activate an additional serial number at the Cumulus server:

1. The "CIP Pooling 3" license allows to configure a maximum pool size of up to 3 connections.
2. The "CIP Pooling 10" license allows to configure a maximum pool size of up to 10 connections.
3. The "CIP Pooling 50" license allows to configure a maximum pool size of up to 50 connections.
4. The "CIP Pooling Unlimited" license allows to configure a pool of any maximum size.

When specifying a field either as a request parameter or in the cip-config.xml you have various options.

You can specify a field by its UID, name, or both and also give it an alias name so the field can be identified in the data by a shorter, more convenient name.

CIP also supports accessing information via some virtual fields that do not exist in the catalog layout.

Specify Field Using Field UID

•                             {af4b2e07-5f6a-11d2-8f20-0000c0e166dc}
                          

  • The Status field specified by using its UID.

Specify Field Using Field UID and Name

•                             {af4b2e07-5f6a-11d2-8f20-0000c0e166dc}:Status
                          

  • The Status field specified by using its UID and a name.

Giving a Field an Alias Name

•                             aliasForStatus:{af4b2e07-5f6a-11d2-8f20-0000c0e166dc}
                          

  • Giving an alias name to the Status field specified by using its UID.

•                             aliasForStatus:{af4b2e07-5f6a-11d2-8f20-0000c0e166dc}:Status
                          

  • Giving an alias name to the Status field specified by using its UID and name.

•                             aliasForStatus:Status
                          

  • Giving an alias name to the Status field specified just by name.

Specifying a Sub-Field

The "Thumbnail" Field

•                             {af4b2e0a-5f6a-11d2-8f20-0000c0e166dc}:Thumbnail/width
                          

  • The width of the thumbnail field in pixels. This sub-field is available for every field of type Picture.

•                             {af4b2e0a-5f6a-11d2-8f20-0000c0e166dc}:Thumbnail/height
                          

  • The height of the thumbnail field in pixels. This sub-field is available for every field of type Picture.

The "Asset Reference" Field

•                             {af4b2e16-5f6a-11d2-8f20-0000c0e166dc}:Asset Reference/Windows
                          

  • The Windows file path to the file asset.

•                             {af4b2e16-5f6a-11d2-8f20-0000c0e166dc}:Asset Reference/Mac OS
                          

  • The display string of the Mac OS path to the file asset.

•                             {af4b2e16-5f6a-11d2-8f20-0000c0e166dc}:Asset Reference/Unix
                          

  • The display string of the Unix path to the file asset.

•                             {af4b2e16-5f6a-11d2-8f20-0000c0e166dc}:Asset Reference/ZIP
                          

  • The name of the asset inside the ZIP archive.

Fields of Type "Date"

•                             {af4b2e02-5f6a-11d2-8f20-0000c0e166dc}:Item Modification Date/format=yyyy-MM-dd'T'HH:mm:ssZ
                          

  • The date and time formatted using the ISO8601 format.

•                             {af4b2e02-5f6a-11d2-8f20-0000c0e166dc}:Item Modification Date/dateformat=medium,timeformat=short
                          

  • The date and time formatted using a standard medium format for the date and a standard short format for the time.

•                             {af4b2e02-5f6a-11d2-8f20-0000c0e166dc}:Item Modification Date/dateformat=long
                          

  • The date and time formatted using a standard long format for the date (time is omitted).

•                             {af4b2e02-5f6a-11d2-8f20-0000c0e166dc}:Item Modification Date/timeformat=full
                          

  • The date and time formatted using a standard full format for the time (date is omitted).

The "Related Master Assets" and "Related Sub-Assets" Fields

• Relation UID	Label for Master Asset	Label for Sub Asset
  {7c41d1b0-4650-11d2-8f00-0000c0e166dc}	Contains	Is contained
  {7c41d1b1-4650-11d2-8f00-0000c0e166dc}	References	Is referenced
  {9ed0887f-40e8-4091-a91c-de356c869251}	Is alternate master	Is alternate
  {6fe3b22c-390e-44b3-99e5-df25de94893b}	Is variant source	Is variant

•                             {af4b2e72-5f6a-11d2-8f20-0000c0e166dc}:Related Master Assets/{9ed0887f-40e8-4091-a91c-de356c869251}
                          

  • The alternate master assets. In the result the field value is identified by the field UID "{af4b2e72-5f6a-11d2-8f20-0000c0e166dc}"

•                             sub-assets:{af4b2e71-5f6a-11d2-8f20-0000c0e166dc}/{7c41d1b0-4650-11d2-8f00-0000c0e166dc}
                          

  • The contained assets. In the result the field value is identified by the alias "sub-assets"

•                             subs:{af4b2e71-5f6a-11d2-8f20-0000c0e166dc}
                          

  • All related sub-assets. In the result the field value is identified by the alias "subs"

Virtual Fields

Virtual fields (Available since: 8.6.1):

•                             NumberOfAssignedAssets:{50f54d0a-0ebe-46ce-bf3c-dbb744349650}
                          

  • contains the number of records being assigned to a category

•                             NumberOfAssignedAssetsIncludingSubCategories:{b46eddc9-dc90-4e31-9474-bee1b9a3fd12}
                          

  • contains the number of records being assigned to a category including its sub-categories

•                             ModifiableFields:{e85fd04a-7e4f-4718-9879-92c0f22ba892}
                          

  • contains list of names of fields that the current user is allowed to modify

Virtual fields (Available since: 9.1.1):

•                             LastVersionNumber:{f226bbd2-beb4-456c-a1a5-8cd88f9ec00a}
                          

  • contains the last version number of an asset that supports version control

Virtual fields (Available since: 10.0):

•                             DirectDownloadUrl:{5e15cd1b-2468-4951-9620-945a71ebe7cc}
                          

  • contains a URL string to directly download the asset from the asset storage (if available).
    This URL can be used to download the asset in the browser by letting the server set the HTTP header "Content-Disposition" to "attachment"
    Note that the URL is valid only for a limited time that is configured in the cip-config.xml: Configure the constraint
    Since API version 13 (CIP 10.0.3) CIP requires the user to have the "Download Asset" and the "Show Original Asset" permissions to see a value in this field.

•                             DirectAccessUrl:{be9f4528-6f5f-4d9d-883e-9017fc3b14dd}
                          

  • contains a URL string to directly download the asset from the asset storage (if available).
    This URL can be used to show the asset in the browser' window by letting the server set the HTTP header "Content-Disposition" to "inline"
    Note that the URL is valid only for a limited time that is configured in the cip-config.xml: Configure the constraint
    Since API version 13 (CIP 10.0.3) CIP requires the user to have the "Download Asset" and the "Show Original Asset" permissions to see a value in this field.

•                             NumberOfPagesInAsset:{309a08c0-e70a-470e-9b60-0ec13f44d964}
                          

  • contains the number of pages that the asset has. For assets that do not support pages this field contains 1.
    This field value is determined at runtime from the original asset which implies a performance drawback compared to the standard field "Number Of Pages" ({af4b2e28-5f6a-11d2-8f20-0000c0e166dc}) which is stored in the catalog but may not be up-to-date if the asset has been changed.
    When deciding how many pages to display for an asset preview you may get the value of this field to determine the current asset's number of pages. See the preview/image operation and the page parameter.

•                             DynamicThumbnail:{dd7c5aba-364b-496c-aa8e-19430047d06f}
                          

  • contains a thumbnail value that may have been dynamically generated by CIP. Many categories do not have a thumbnail being stored in the standard thumbnail field. In order to return a thumbnail image for such a category CIP returns the thumbnail from one of the assets that are assigned to the category.
    The asset record is randomly picked but cached in CIP so that the sub-field values for width and height are from the picked thumbnail. You can also access the sub-fields width and height the same way you would do this for the standard thumbnail field (see below)

•                             DynamicThumbnailWidth:{dd7c5aba-364b-496c-aa8e-19430047d06f}/width
                          

  • contains the width of a thumbnail that may have been dynamically generated by CIP (see the virtual field above).

•                             DynamicThumbnailHeight:{dd7c5aba-364b-496c-aa8e-19430047d06f}/height
                          

  • contains the height of a thumbnail that may have been dynamically generated by CIP (see the virtual field above).

Virtual fields (Available since: 10.0.2):

•                             ObjectPermissions:{167ca894-6022-4400-a5e8-27520ab33155}
                          

  • contains an array of permissions that the current user has on the current object (e.g. ["download", "modify"]).
    
    Possible permissions are
    

    Name	Description
    modify	The user is allowed to modify the item.
    delete	The user is allowed to delete the item.
    download	The user is allowed to download the asset (asset items only).
    checkin	The user is allowed to check in a new version (asset items only).
    videocloudconsumer	(Available since: 10.2.5): The user is allowed to obtain the web embed code for videos and generate a video preview link.

Virtual fields (Available since: 10.2.6):

•                             NumberOfAssignedAssetsUsingUserSettings:{39b339b2-6aa7-4d2b-96f9-b3e5291bd1a7}
                          

  • contains the number of records being assigned to a category by respecting the current user's user settings.

A collection can have values in the following fields:

Field Name	Field GUID	Field Type	Description
Collection Name	{ba35f6a4-3ecc-4262-a50b-b942dea26693}	String	A user-friendly name that can be translated into different languages.
Description	{47544b91-ed41-11d5-b5e8-0050baeba6c7}	String	A description that can be translated into different languages.
Collection Type	{1cad7152-d5d7-4802-b2d1-b41d573d9b70}	Enum	This is an Enum type field with the following possible values: ID Name Description -1 unknown The type is unknown to this version of CIP. 0 auto A (private) collection that is automatically created by a client software. 1 basket A (private) collection to store a collection basket for the user. 2 download A collection shared with other users. A collection link was sent to a list of recipients that can then download the assets contained in the collection. A download collection has an expiration date and optionally also an embargo date. 3 private A collection of assets accessible on to the current user. 4 shared A collection of assets shared with others for accessing the assets. 5 upload A shared collection where other users (even external to the system) can upload assets to. When creating an upload collection a mail is sent with a link to a landing page that allows uploading of assets. 6 custom A collection created by some third-party software which is not shown in any of the Cumulus client applications.
Item Creation Date	{af4b2e01-5f6a-11d2-8f20-0000c0e166dc}	DateTime	The date and time this collection was created.
Item Modification Date	{af4b2e02-5f6a-11d2-8f20-0000c0e166dc}	DateTime	The date and time this collection was last modified.
Collection Catalogs	{e8f80062-4b10-4b33-a261-5de5e1446005}	MultiEnum	The list of catalogs that the collection references. Each catalog is listed with an ID and a location.
Collection Expiration Date	{76f807ae-299f-40f3-b80e-713be5b8324a}	DateTime	The date and time this collection expires. A download collection is deleted automatically when expired whereas an upload collection will refuse to allow uploading any additional asset.
Collection Embargo Date	{01f1663b-b38b-43ca-90e4-1409fa3ddcd7}	DateTime	The date and time this collection will be made usable by others.
Collection Creator	{4b4692ee-456e-46a5-bc5b-f3218f31c8da}	UserUID	The user UID of the user who created this collection.
Collection Recipients	{6c697634-29be-4813-873c-c84d4323425b}	Binary	The list of people who received an e-mail with an access link to the collection. This is only available for download and upload collections. Each recipient is listed with user UID, e-mail address being used and the last access date.
Collection Number of Records	{dd8bfa7e-4637-4b0f-a709-8062e5777f49}	Integer	The number of assets contained in the collection. Only assets from the catalog specified by the catalog alias are counted.

CIP supports to work with multiple catalogs within a single operation.

To use this feature you configure a catalog alias (see Configure a catalog definition) with multiple catalog elements. CIP does currently not support specifying multiple catalogs using the catalogname named parameter in an operation.

Some operations are still limited to only use the first of the configured catalogs:

• asset/import
• metadata/createitem
• workflow/info
• workflow/todo
• workflow/item

When working with multiple catalogs assets, categories, and other table items of the first configured catalog will show the same IDs as if you have configured a single catalog. Items of other catalogs will be constructed by adding the index of the catalog in the configuration as the upper 32 bit value of the ID. This identifies to CIP which catalog the item comes from and is completely transparent. As long as you do not change the catalog list in the catalog alias configuration these IDs are stable. As soon as you have changed the catalog list CIP will use other IDs for the same objects.

Example:

• In the first configured catalog the ID of the "$Keywords" master category is 2.
• If you have configured the catalog alias to have this same catalog as the second configured catalog the ID of the "$Categories" master category is 4294967298 ((1 << 32) + 2).
• If you have configured the catalog alias to have this same catalog as the third configured catalog the ID of the "$Categories" master category is 8589934594 ((2 << 32) + 2).

The metadata/getcategories operation will return an additional level if working with multiple catalogs. This new top-level lists categories that represent each of the catalog:

• The id is 0 for the first catalog, 4294967296 for the second, 8589934592 for the third and so forth.
• The name (value of the field "Category Name" of the category is the catalog name.
• The value of the "Category Type" field is returned as null to let you identify this special kind of category.

When CIP encounters a serious problem while processing a request it responds with an HTTP status code of 500.

The response body is a JSON structure containing detailed information about the error:

Some common errors can be identified with an error code assigned by CIP.

Following is a list of all defined error codes:

Error Code	Description
server.not.found	CIP cannot connect to the given Cumulus server. Please check the server address and network connectivity to the server.
login.failed	The given login user name or password is wrong.
password.expired	The user's password is expired. Please contact your administrator.
permission.denied	The user does not have the necessary permission to perform the operation.
catalog.alias.not.found	A catalog alias specified in the request is not valid. Please check the catalog alias configurations in cip configuration file.
catalog.not.found	The given catalog was not found at the Cumulus server. Please check whether it has been removed or renamed.
item.not.found	The requested item (e.g. asset record, category, or sub-table item) does not exist. It may been deleted recently.
field.not.found	The given metadata field does not exist. Please check the catalog settings.
asset.version.not.found	The specified asset version does not exist. Please check whether the asset version has been deleted recently.
workflow.not.found	The specified workflow does not exist in the given catalog. Please check the catalog settings.
workflow.activity.not.found	The specified workflow activity does not exist in the given catalog. Please check the workflow definition.
workflow.state.not.found	The specified workflow state does not exist in the given catalog. Please check the workflow definition.
server.view.not.found	The specified view set does not exist at the Cumulus server. Please check whether the view set may not be accessible for the given user.
collection.not.found	The specified server-side collection does not exist at the Cumulus server. Please check whether the collection may not be accessible for the given user.
collection.already.exists	The name for a server-side collection is already taken. Please choose another name.
client.configuration.not.found	The specified client configuration cannot be found. Please check the CIP configuration file.
filter.state.not.found	The specified filter state is not valid. You may have closed and re-opened a session which removes all filter states.
invalid.query	The format of the query string is wrong. Please check the syntax. Please see the appendix for a documentation of the query syntax.
cannot.create.preview	CIP cannot create a preview for the given asset. It may have a format that is not supported.
client.product.invalid	The given client product ID is not valid for this version of CIP.
client.product.not.activated	The given client product is not licensed for this version of CIP.
asset.not.found	since 10.0.2: The requested asset can not be found.
no.asset.converted	since 10.1: When requesting an asset conversion the result list was empty. There is nothing to download.
cannot.print	since 10.1.1: An error occurred when generating either a PDF or image using a Print Template.
reset.password.token.not.found	since 10.1.1: when trying to reset a password using a token created when sending the e-mail CIP detected that the token is invalid. The token is probably expired (used more than 24 hours after the e-mail was sent. It could also be that the token was already being used for resetting the password.
page.number.not.valid	since 10.1.1: The given page number is either negative or greater or equal to the total number of pages.
plugin.id.not.found	since 10.1.1: The given plug-in ID is not valid. There is no plug-in of this ID installed at the CIP server.
invalid.session	since 10.1.2: Either the operation or some parameter requires a valid session but there is no session provided.
item.not.published	since 10.2: The asset of the specified item is not published so a preview URL cannot be generated.
configuration.error	since 11.0: Some configuration of the CIP server does not match the usage of CIP.

CIP is supporting older versions of the API by specifying the apiversion named parameter in the request.

By default it is assuming that you want to use it according to the API version that the CIP server was built for.

Some operations or parameters were introduced with a specific API version so they will only work if the API version specified (or implied) is at least at the required level.

Here is a list of API versions and the corresponding CIP release version:

1	CIP 8.5.2 release
2	CIP 8.6 release
3	CIP 8.6.1 release
4	CIP 9.0 release
5	CIP 9.1 release
6	CIP 9.2 release
7	CIP 9.2.1 release
10	CIP 10.0 release
11	CIP 10.0.1 release
12	CIP 10.0.2 release
13	CIP 10.0.3 release
14	CIP 10.1 release
15	CIP 10.1.1 release
16	CIP 10.1.2 release
17	CIP 10.1.3 release
18	CIP 10.2 release
19	CIP 10.2.1 release
20	CIP 10.2.2 release
21	CIP 10.2.3 release
22	CIP 10.2.4 release
23	CIP 10.2.5 release
24	CIP 10.2.6 release
25	CIP 11.0 release
26	CIP 11.0.1 release
27	CIP 11.0.2 release
28	CIP 11.0.3 release
29	CIP 11.0.4 release
30	CIP 11.1 release
31	CIP 11.1.1 release
32	CIP 11.1.2 release

The operations (functions) that CIP provides to clients are grouped into different “services.”
Each service offers a set of operations that conceptually belong together.
The URL for an operation always starts with the following:

• The “cip-server” and “port” are the address and port number of the CIP web application server.
• The “CIP” specifies the web application “CIP”
• The “service” is the name of the CIP service (operation group, always in lower case)
• The “operation” is the name of operation inside the service (always in lower case)
• The “path-parameters” are the optional path elements that the operation uses. Typically only parameters that need to occur exactly once for the operation are given as path-parameters. If a parameter is optional or can occur more than once it is typically provided using named parameters.
• The “named-parameters” are optional parameters for the operation. Typically parameters that are optional or can occur more than once are passed this way. As usual in URLs named parameters are passed using “name=value” notation using a “&” to separate them.

Here is an overview of the services that CIP provides:

• session - Creating and closing a session
• metadata - Operations for searching, reading, and writing asset metadata
• preview - Operations for generating images of assets in different sizes
• asset - Operations for getting or uploading assets
• comments - Operations for getting or uploading assets
• location - Operations for managing locations (e.g. folders on an FTP server)
• process - Operations for managing background processes (e.g. asynchronous download preparation)
• developer - Operations for helping developers (e.g. generating client source code)
• workflow - Operations for using workflows
• subscription - Operations for managing asset subscriptions
• collection - Operations for managing collections and filters
• user - Operations for getting information about users
• configuration - Operations for getting configuration information
• system - Operation for retrieving information about the CIP server system
• mediadelivery - Operation for delivering images

1. As named URL parameters “user” and “password”
2. In a configured catalog alias referenced by a path parameter for this request
3. In the HTTP request header following the HTTP “Basic Access Authentication” standard

The third option is less flexible as it can not handle user names and passwords that contain colon (":") characters.
If you want to hide the credentials and encrypt all communication you should configure your web application server to use SSL.
Then each URL you call needs to start with “https” instead of “http.”

1. Immediately return all IDs of the resulting items.
2. Immediately return metadata field values for each of the items of the result.
3. Store the resulting item IDs in a collection by optionally combining this search result with the previous contents of the collection. You then use the getfieldvalues operation to retrieve metadata for items in the collection. This way you can implement “paging” through a long list of items without returning metadata for all items found in a single operation.

Collections
The search operations allow you to optionally store the result in a named collection which is stored in the current session (see session handling above). You give the collection a name which has to be unique within the current session. The collection is bound to a specific catalog and table within the catalog and only contains a list of item IDs.

After storing a search result in a collection you can then either retrieve the metadata for items in the collection using a getfieldvalues operation or combine the collection with the result of a subsequent search operation. Each search always returns the total number of items found. The getfieldvalues operation allows you to specify a starting offset in the item IDs and a maximum number of items to return. This way you can implement client-side “paging” through a long list of resulting items.

A query configuration can be defined in different ways:

• A “QuickSearch” performed using a simple search string that searches across multiple metadata fields (use parameter quicksearchstring).
• A preset query stored in the Cumulus server (use parameter queryname). This is best suited for searches using a fixed query that is also used by other users of Cumulus.
• A query string that may contain placeholders to be replaced with URL named parameters at runtime (use parameter queryname). This is best suited for searches using a query with some variable parts that are specified in the request.
• A query string explicitly provided with the request (use parameter querystring). This is best suited for any query that is created at runtime.

You specify the items either by setting the named parameter collection or by specifying the catalog and item ID using path parameters 1 and 2 respectively.

The field values are specified using a JSON structure transferred in the request body of a HTTP POST request.

The JSON data always contains the ID of the item to be modified.

• Item 129 via display string
• Item 130 via day, month and year
• Item 131 via month and year
• Item 132 via year
• Item 133 simple form via display string

• Item 129 via milliseconds value
• Item 130 via display string
• Item 131 short form via milliseconds value
• Item 132 short form via display string

• Item 130 via value
• Item 132 simple form via value

• Item 129 via id
• Item 130 via displaystring
• Item 131 simple form via id

The field values are specified using a JSON structure transferred in the request body of a HTTP POST request.

Three options allow specifying the parent category:

1. Specify the category by the complete path (use parameter path).
2. Specify the category by its ID (use parameter categoryid).
3. If neither the path nor categoryid parameter is specified the operation will return the top-level categories.

Three options allow specifying the parent category:

1. Specify the parent category by the complete path (use parameter path).
2. Specify the parent category by its ID (use parameter categoryid).
3. If neither the path nor categoryid parameter is specified the operation will create a top-level category.

Two options allow specifying the category to be deleted:

1. Specify the category by the complete path (use parameterpath).
2. Specify the category by its ID (use parametercategoryid).

The ID of the items are specified using a JSON structure transferred in the request body of a HTTP POST request.

An optional location allows you to store the result in the local file system of the CIP server or on an FTP server instead of downloading the result to the client.

Several options allow specifying the parameters for generating the preview image. The options are applied in the following order:

1. Cropping (use optional parameters left, top, width, height).
2. Scale down the image (use optional parameter maxsize or size).
3. Rotate the image in 90 degree steps (use optional the parameter rotate).
4. Output file format (use optional parameter format and quality).

An optional location allows you to store the result in the local file system of the CIP server or on an FTP server instead of downloading the result to the client.

There are three ways of specifying the asset to be imported:

1. Specify an existing asset using a URL (using the location parameter).
2. Specify an existing asset based on a configured location and a relative path (using the location parameter).
3. Upload the asset in the HTTP request body. This is done by putting the asset contents into the request body and using the HTTP POST method. If no metadata fields are to be set with this request the body only contains the asset contents and you specify the file name to be used in the location parameter. If you want to be able to set metadata fields along with the importing you need to post the request using the MIME type multipart/form-data.

There are three ways of specifying the source asset:

1. Specify an existing asset using a URL (using the location parameter).
2. Specify an existing asset based on a configured location and a relative path (using the location parameter).
3. Upload the asset with the HTTP request. This is done by putting the asset contents into the request body and using the HTTP POST method. This request the body only contains the asset contents.

Optionally you can convert the asset prior to downloading.

An optional location allows you to store the result in the local file system of the CIP server or on an FTP server instead of downloading the result to the client.

In place of location you can specify e-mail parameters to send the asset as an e-mail attachment.

Since API version 10 (CIP 10.0) CIP also supports the HTTP Range header. This way CIP supports delivering video contents to a browser which is embedding a URL with this operation in an HTML5 <video> tag.

Since API version 10 (CIP 10.0) CIP supports asynchronous download handling. You can start an asynchronous download process which prepares the result in the background. Then you can poll for the current state of this process and can obtain the result once the process is finished. This way you can handle cases where the download takes longer than the response timeout of your client software. Asynchronous handling is supported for all destinations: downloading to the requesting client, sending an email, and storing the result at a specified location.

Since API version 13 (CIP 10.0.3) CIP requires the user to have the "Download Asset" permission to download an asset. Additionally if the request does not specify an Asset Action to be performed the "Show Original Asset" permission is also required.