Skip to content

REST API

Getting Started

This REST API provides an application access to the TickStream.CV behavior analytics services via simple HTTP requests. To use the this API, it is important that you understand the basics of RESTful web services and JSON data representations.

Access to the TickStream.CV API requires a valid license key. Please contact us at developer@intensityanalytics.com for more information.

Guidelines

Compliance

Any and all use of the TickStream.CV API implies consent to the terms of the Intensity Analytics End-User License Agreement (EULA). Any modification of the results produced from the TickStream.CV API, including client libraries, may result in degraded performance, and may also result in a void of warranty.

Platforms

As it is accessible through REST, the TickStream.CV API may be consumed by a variety of development platforms, including Microsoft.NET (VB,C#, etc.), Java, JavaScript, Perl, PHP, Python, Ruby, and many others. However, for the sake of security practice, we strongly recommend accessing these services from a compiled application whenever transmitting your license key, or any other sensitive data, to protect that information from the client.

Cross-Origin Resource Sharing (CORS)

The TickStream.CV API supports CORS. This enables JavaScript code served from a domain other than the server hosting this API to make Ajax requests to it. However, with limited exceptions (the client library, validation, etc.), we strongly urge developers to use a compiled application to access these services.

Secure Sockets Layer (SSL)

Secure connection to the server hosting the TickStream.CV API is controlled by the configuration of that server. Access through both SSL and TLS are fully supported, provided the server has a valid certificate, and the appropriate TCP ports are open to the application.

Support

Priority support is available with a paid subscription. Please contact us at developer@intensityanalytics.com for more information. For community support, access our customer forum at http://intensityanalytics.com/forum.

Resource Summary

Click any resource to jump to that section.

Generic methods include:

  • Evaluate compares a two given efforts, generating dynamic results.
  • Library retrieves the JavaScript client library for TickStream.CV operations.

Database specific methods include:

  • EntityApplications retrieves a list of applications associated with a given EntityID.
  • Entity retrieves of list of EntityID values and associated metadata.
  • EntityData retrieves TickStream.CV data for a given EntityID.

Evaluate

Used for comparing two raw samples, where the data is gathered from any source. This calls the evaluation process directly.

GET

Not used, returns a 404 response code.

POST

URI

/evaluate

Header Parameters

Authorization
The TickStream.CV license code value.

URI Parameters

none

Data Parameters

Sample1
The behavior values for the first data sample, either in raw form, or serialized and compressed as returned from the populateControlWithKeyDataConcatenated function in the TickStream.CV jQuery library, or an equivalent.

Sample1Name
A name to label the first sample in the evaluation results.

Sample2
The behavior values for the second data sample, either in raw form, or serialized and compressed as returned from the populateControlWithKeyDataConcatenated function in the TickStream.CV jQuery library, or an equivalent.

Sample2Name
A name to label the second sample in the evaluation results.

ImageCompositeSize (optional)
A value representing the size, in pixels, of the Composite Graph returned (as identified in the Images parameter). This value should follow the form: "width, length", such as "400,300".

ImageFrequencySize (optional)
A value representing the size, in pixels, of the Frequency Graph returned (as identified in the Images parameter). This value should follow the form: "width, length", such as "400,300".

ImageOverlapSize (optional)
A value representing the size, in pixels, of the Overlap Graph returned (as identified in the Images parameter). This value should follow the form: "width, length", such as "400,300".

ImageSeismicSize (optional)
A value representing the size, in pixels, of the Seismic Graph returned (as identified in the Images parameter). This value should follow the form: "width, length", such as "400,300".

ImageTFIDFSize (optional)
A value representing the size, in pixels, of the TF/IDF Graph returned (as identified in the Images parameter). This value should follow the form: "width, length", such as "400,300".

Statistics (optional)
Expects one or more of the following values, in an array value (even for a single option):

  • Basic
    Returns a set of basic evaluation summary statistics.

  • Extended
    Returns an extended version of the evaluation statistics.

  • Report
    Returns a narrative description of the evaluation results, with an explanation about the statistics.

Images (optional)
Expects one or more of the following values, in an array value (even for a single option):

  • Composite
    Returns the Composite Graph as a Base64 encoded image in the results.

  • Frequency
    Returns the Frequency Graph as a Base64 encoded image in the results.

  • Overlap
    Returns the Overlap Graph as a Base64 encoded image in the results.

  • Seismic
    Returns the Seismic Graph as a Base64 encoded image in the results.

  • TFIDF
    Returns the TF/IDF Graph as a Base64 encoded image in the results.

Success Response

[{"Error":"", "Projection":"(Integer)", "Confidence":"(Integer)*", "Matching Features":"(Integer)"}]


Additional values may appear, depending on the value of the Statistics and Images parameters.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client.

[{"Error": "Error message (String)"}]

Sample

given the following data submitted via POST (application/x-www-form-urlencoded)

=[{'Statistics':['basic'], 'Images':['all'],'Sample1Name':'test1','Sample2Name':'test2','Sample1':'<data>', 'Sample2':'<data>'}]

returns

{"Error": "", "Confidence": "100", "Matching Features": "17", "Projection": "93"}
PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

Library

Method to retrieve the client library, used to bind fields and create the TickStream.CV data values. This can be retrieved in a variety of formats and injected into a web page at runtime, or included directly by using a standard JavaScript src tag. Most of the library can be cached, and dynamic portions, such as the otk nonce variable, can be retrieved separately.

GET

URI

/library/<Library Name>

Header Parameters

Authorization
The TickStream.CV license code value.

URI Parameters

Library Name
Expects one of the following values:

  • cv
    The minified, dynamically obfuscated library most often used on production systems.

  • cv-min
    The minified library most often used on production systems that use a cached copy.

  • cv-verbose
    The unobfuscated library, with carriage returns intact that make it readable. This option can be disabled by configuring server settings.

  • cv-documented
    The unobfuscated library, with carriage returns intact, and all inline documentation that make it readable. This option can be disabled by configuring server settings.

  • otk
    Returns only the otk nonce variable declaration, used in concert with a cached version of the library.

Exclude
Expects one or more of the following values:

  • otk
    This requests a version of the library that does not include the otk nonce variable, and so it can be safely cached. This requires a separate call to retrieve the otk declaration, such as http://keyid-services.anycorp.com/library/otk.

Data Parameters

none

Success Response

Returns a string value that is the TickStream.KeyID jQuery library, formatted as specified by the LibraryName parameter.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client.

[{"Error": "Error message (String)"}]

Sample

<script src="https://cv-services.anycorp.com/library/cv"></script>
POST

Not used, and disabled, returns nothing.

PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

Entity

Describe

GET

URI

/database/entity

Header Parameters

Authorization
The TickStream.CV license code value.

URI Parameters

Source
Expects one of the following values:

  • SQL
    Retrieves the data from the Microsoft SQL database server, as configured on the web services host.

  • Impala
    Retrieves the data from the Apache Impala (Hadoop) database server, as configured on the web services host.

List
Expects one of the following values:

  • users
    Returns a list of distinct users found in the database, along with the EntityID values corresponding to the unique machine names associated with each user.

  • usersbymachine
    Returns a list of distinct user and machine names found in the database, along with the EntityID value corresponding to that pair.

  • machinesbyuser
    Returns a list of distinct user names, machine names, and combined user and machine name pairs found in the database, along with the EntityID value corresponding to that pair.

Data Parameters

none

Success Response

Returns a list of EntityID values, along with the data specified by the List parameter.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client.

[{"Error": "Error message (String)"}]

Sample

given the following URI submitted via GET

http://cv-services.anycorp.com/database/entity?source=sql&list=machinesbyuser

returns

[{"UserName": "User1", "MachineName": "Machine1",
"UserMachine": "Machine1\\User1", "EntityID": "00000000-0000-0000-0000-000000000000"},
{"UserName": "User2", "MachineName": "Machine2",
"UserMachine": "Machine2\\User2", "EntityID": "11111111-1111-1111-1111-111111111111"}]
POST

Not used, returns a 404 response code.

PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

EntityApplications

Describe

GET

URI

/database/entityapplications

Header Parameters

Authorization
The TickStream.CV license code value.

URI Parameters

Source
Expects one of the following values:

  • SQL
    Retrieves the data from the Microsoft SQL database server, as configured on the web services host.

  • Impala
    Retrieves the data from the Apache Impala (Hadoop) database server, as configured on the web services host.

EntityID
The unique identifier for the application list to be returned, as retrieved from the Entity method. Multiple identifiers (Microsoft SQL only) can be submitted as single-quoted values separated by commas.

Data Parameters

none

Success Response

Returns a list of application names that are found to be associated with data events for the given EntityID.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client.

[{"Error": "Error message (String)"}]

Sample

given the following URI submitted via GET

http://cv-services.anycorp.com/database/entityapplications?source=sql&entityid=00000000-0000-0000-0000-000000000000

returns

[{"Application": "Microsoft Excel"},{"Application": "Microsoft Outlook"},{"Application": "Microsoft Word"}]
POST

Not used, returns a 404 response code.

PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

EntityData

Describe

GET

Not used, returns a 404 response code.

POST

URI

/database/entitydata

Header Parameters

Authorization
The TickStream.CV license code value.

URI Parameters

none

Data Parameters

Source
Expects one of the following values:

  • SQL
    Retrieves the data from the Microsoft SQL database server, as configured on the web services host.

  • Impala
    Retrieves the data from the Apache Impala (Hadoop) database server, as configured on the web services host.

EntityID
The unique identifiers for the data to be returned, as retrieved from the Entity method, in an array value (even for a single EntityID). Multiple identifiers are only support for Microsoft SQL.

StartDate
The minimum date and time of data events to include in the results.

EndDate
The maximum date and time of data events to include in the results.

Applications (optional)
One or more application names, as retrieved from the EntityApplications method, to filter the results by only those data events associated with the given names (in an array value for multiple application names). Leaving this optional parameter out of the POST request will default to include all application names in the results.

Success Response

Returns a list of TickStream.CV event data for the given parameters, along with the corresponding date and time, and application name associated with each event.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client.

[{"Error": "Error message (String)"}]

Sample

given the following data submitted via POST (application/x-www-form-urlencoded)

=[{'Source':'sql', 'EntityID':'00000000-0000-0000-0000-000000000000', 'Applications':'Microsoft Word', 'StartDate':'1/1/2017', 'EndDate':'2/1/2017'}]

returns

[{"EventTime": "2017-01-03T22:36:01", "EventName": "Microsoft Word","EventCV": "<data>"},
{"EventTime": "2017-01-03T22:36:46", "EventName": "Microsoft Word", "EventCV": "<data>"}]
PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.