Analyze

APIDescription
POST Analyze

Analyze comments as a synchronous operation.
The comments will be analyzed and the results returned in the response message.
Neither the comments nor the text analytics results are persisted on the Ascribe servers.
You may optionally specify a Rule Set to provide your own processing logic, and/or a Taxonomy to group topics.
If you do not specify a Taxonomy the topics will be automatically grouped, but this is effective only if the number of topics found is fairly large. Hence the auto grouping is useful only if you submit a large number of comments to analyze, or a smaller number of lengthly comments.

Batches

Manages batches of responses to add and analyze in an Inspection.

APIDescription
GET Batches/{InspectionKey}/{BatchKey}

Get the current status of a Batch.
The StatusCode value in the response will be one of:

  • 0: NotFound - The requested batch does not exist.
  • 1: Empty - No respondents have yet been added to the Batch.
  • 2: Waiting - The Batch is awaiting additional respondents or start of the analysis.
  • 3: Analyzing - Analysis has started and is not yet complete.
  • 4: Success - Analysis has completed successfully.
  • 5: Failure - Analysis has completed unsuccessfully.

POST Batches/{InspectionKey}/new

Create a new Batch for an Inspection.
The Batch holds respondent data to be submitted for analysis.
Store respondent data in the Batch with one or more POSTs to batches/respondents, then start the analysis with a POST to batches/analyze.

POST Batches/analyze

Start the analysis of a Batch.
The Batch must contain at least one respondent.
This method adds the data in the Batch to the Inspection, and starts text analysis of the specified variables.

POST Batches/respondents

Add respondent data to a Batch.
Use this operation one or more times to add respondent data to the Batch.
You must add at least one respondent to the Batch before you can start the analysis of the Batch.
The maximum request length to this API is 16 MBytes, so if you are adding a large number of respondents you should use this operation multiple times with only as many respondents in each request as will ensure that the maximum request length is not exceeded.

Exports

Exports inspections into Excel

APIDescription
POST Exports/{InspectionKey}/{ExportType}/{Facets}/start

Starts an export of an inspection to Excel.
Multiple ExportType Excel values can be specified by using bar (|) character.
If non-Excel values are specified, they can only be single calls.
e.g. "Excel|ExcelWithTees|ExcelWithHeatMap" is valid but "Excel|SpssFile" and "StudyXml|SpssFile" is not.

POST Exports/start

Starts an export of an inspection to Excel.

GET Exports/{TaskStatusKey}

Retrieves the current status of an export and if applicable, a URL to download the Excel document

Findings

This resource supports queries for the findings in an Inspection.

APIDescription
GET Findings/{InspectionKey}

Gets information about the findings in an Inspection.
Because an Inspection may contain a very large number of findings they are returned one partition at a time.
Each partition contains a number of findings that allow for a manageable payload size.
To retrieve all of the findings in an Inspection, first use this operation to retrieve the number of topic and sentiment partitions in the Inspection, then query for each partition using the
GET /Findings/Topics/{PartitionIndex} and
GET /Findings/Sentiment/{PartitionIndex}
operations.

GET Findings/{InspectionKey}/Topics/{PartitionIndex}

Get a partition of topic findings.
Because an Inspection can contain a very large number of findings, this API returns findings by "partition".
The number of partitions is obtained by GET /Findings/{InspectionKey}
To obtain all of the findings, perform this GET operation repeatedly, iterating from 0 to the number of topic partitions - 1.
This operation returns findings from the topic analysis only. To retrieve the sentiment findings, use the
GET /Findings/{InspectionKey}/Sentiment/{PartitionIndex}
operation.

GET Findings/{InspectionKey}/Sentiment/{PartitionIndex}

Get a partition of sentiment findings.
Because an Inspection can contain a very large number of findings, this API returns findings by "partition".
The number of partitions is obtained by GET /Findings/{InspectionKey}
To obtain all of the findings, perform this GET operation repeatedly, iterating from 0 to the number of sentiment partitions - 1.
This operation returns findings from the sentiment analysis only. To retrieve the topic findings, use the
GET /Findings/{InspectionKey}/Topics/{PartitionIndex}
operation.

Inspections

This resource supports queries for the properties of Inspections, and the creation of new Inspections.

APIDescription
GET Inspections

List the available Inspections.
Returns a list of the properties of all Inspections that are available to the API user.
Inspections are available to the owner of the Inspection only, unless the Inspection is marked as Public.

GET Inspections/{InspectionKey}

Get the properties of a single Inspection.

POST Inspections

Create a new Inspection.
The owner of the new Inspection will be the user credentialed for this API session.

This resource supports retrieval of links to Inspections. A link is a URI to a read-only interactive view of the Inspection.

APIDescription
GET Links/{InspectionKey}

Gets a link for the specified Inspection.
Anyone in possession of a link returned by this operation can view the Inspection in read-only fashion.

RuleSets

This resource provides information about the available Rule Sets and their associated identifiers.

APIDescription
GET RuleSets

Get the available Rule Sets

Sessions

This resource allows creation of a new session for interactions with this API. A POST to this resource is the starting point for all interactions with the API.

APIDescription
POST Sessions

Create a new session for interaction with this API
The credentialed user must have Adminstrator privilege in Ascribe.
The response message contains two tokens, one of which must be passed in a header for all other operations with this API.
You may either use the bearerToken or the authenticationToken. Either send a header with key "authentication" and value the authenticationToken returned in this response, or send a header with key "Authorization" and value the bearerToken returned in this response.
The bearerToken does not expire, but will become invalid if the user's credentials change.
The authenticationToken remains valid until no request is sent to this API using the authenticationToken for 30 minutes.

Taxonomies

This resource provides information about the available Taxonomies and their associated identifiers.

APIDescription
GET Taxonomies

Get the available Taxonomies

GET Taxonomies/{TaxonomyKey}

Get the details of a single Taxonomy

Users

This resource provides information about the users defined in the current account and their associated keys.

APIDescription
GET Users

Get all Users

Variables

This resource supports queries for the variables in an Inspection.

APIDescription
GET Variables/{InspectionKey}

Get the variables in an Inspection.
The variable keys returned in this operation may be used to associate the ID of each variable key returned from the Findings resource.