Overview

This article will help provide more insight into MaestroQA's API. Please keep in mind, in order to execute the below actions, you must be an Admin user within MaestroQA. With that said, let's get started!

Table of Contents


Authentication - Obtaining API Token

In order to make requests to the Maestro QA API, you must attach a valid API token to your request. API tokens can be generated in the MaestroQA dashboard on the Other Settings page.

Within "Other Settings", scroll down to the API Tokens section and click "Create New Token".

By default, API Tokens expire every 90 days for security purposes. This expiration can be turned off, or tokens can be deactivated manually.

An API token must be provided for all requests. The token should be passed in the request's headers, in the format:

'apitoken': 'YOUR_API_TOKEN'

Example (Python)

import requests

headers = {
'Content-Type': 'application/json',
'apitoken': 'YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)

Certain endpoints allow tokens to be passed in the request body (noted in the endpoint's documentation); this is supported for backward compatibility and is subject to change.

__________________________________________________________________

Formats

1. All dates should be UTC offset datetime strings, formatted according to the extended ISO 8601 format (reference)

[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z

ex. 2017-12-13T05:00:00Z

2. Each endpoint’s request parameters and response content should be JSON-encoded

Endpoints

The * symbol is used to denote required parameters

If a parameter is optional, it may be omitted from the request parameters. If an optional parameter is included, it must contain a valid value.

Request A “Raw” Export

Raw exports are the equivalent to the Raw CSV export in the MaestroQA dashboard. The export will include grades that were last updated between the specified start date and end date.

Raw exports generate a zip file containing a CSV for each level of rubric scores:

  • total rubric scores

  • section scores

  • individual answer scores

  • annotations

  • CSAT

Definition

POST https://app.maestroqa.com/api/v1/request-raw-export

Body Parameters

Name

Type

Description

startDate*

string (see formats)

Include grades that were updated after this date
(required)

endDate*

string (see formats)

Include grades that were updated before this date
(required)

name

string

Name for the export. Defaults to a randomly generated name
(optional)

singleFileExport

enum

(individual_answers, section_scores, total_scores, annotations, csat)

Specify a single csv file to export instead of the default zip file with all csvs

(optional)

includeCalibrations

enum

(all, none, only)

Specify whether calibration scores should be included in the export.

  • "none": (default) - don't include calibration scores

  • "only": only include calibration scores

  • "all": include all scores, regardless of type

(optional)

includeGraderQA

boolean

Specify whether grader QA benchmark scores should be included in the export. Default is false

(optional)

apiToken

string

See authentication
(optional) - token may be passed in request body or in request headers

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Name

Type

Description

exportId

string

ID of the export that was requested

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-raw-export'

payload = {
'startDate': '2018-08-13T00:00:00Z',
'endDate': '2018-08-19T00:00:00Z',
'name': 'Weekly Maestro Grades Export'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

Retrieve the results of an export

After an export has been requested, check its status and fetch the URL from which to download the export’s results.

Definition

GET https://app.maestroqa.com/api/v1/get-export-data

Header or Body Parameters

Name

Type

Description

exportId*

string

The ID of the export whose results should be returned
(required)

apiToken

string

See authentication
(optional) - token may be passed in request body or in request headers

Response

Status and result data for the requested export

Name

Type

Description

status

enum

(requested, in_progress, complete, errored)

The status of the export

dataUrl

string

If status is "complete" and there is data to download, contains the URL to download the export. Otherwise, contains an empty string.

Note: if there was no matching data for the parameters requested (ex. if you request dates in the future), the dataUrl field will be empty, even when the status is 'complete' as there is nothing to download.

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/get-export-data'

payload = {
'exportId': 'THE_EXPORT_ID'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.get(url, json=payload, headers=headers)

Example Response

{
'status': 'complete',
'dataUrl': 'https://subdomain.s3.amazonaws.com/path/to/file'
}

__________________________________________________________________

Request an “agent groups” export

An “agent groups” export is the equivalent to the Agent Groups export in the MaestroQA App. This will export all the agent groups and group membership.

Definition

POST https://app.maestroqa.com/api/v1/request-groups-export

Body Parameters

Name

Type

Description

name

string

Name for the export. Defaults to a randomly generated name
(optional)

includeUnavailable

boolean

Whether to include all agents, or just those currently marked “available”. Default is false.

(optional)

apiToken

string

See authentication
(optional) - token may be passed in request body or in request headers

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Name

Type

Description

exportId

string

ID of the export that was requested

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-groups-export'

payload = {
'name': 'Maestro Agent Groups Export',
'includeUnavailable': False
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

Request an “audit logs” export

An “audit log” export is the equivalent to the Activity Logs export in the MaestroQA App. This will export all the user activity in your account during the specified date range. See "What Can I Track in the Activity Log" for details on what is tracked in the activity log.

Definition

POST https://app.maestroqa.com/api/v1/request-audit-log-export

Body Parameters

Name

Type

Description

startDate*

string (see formats)

Include logs that were created after this date
(required)

endDate*

string (see formats)

Include logs that were created before this date
(required)

name

string

Name for the export. Defaults to a randomly generated name
(optional)

apiToken

string

See authentication
(optional) - token may be passed in request body or in request headers

Response

The ID of the export that was requested - used to track the export's status and retrieve its results.

Name

Type

Description

exportId

string

ID of the export that was requested

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/request-audit-log-export'

payload = {
'startDate': '2018-08-13T00:00:00Z',
'endDate': '2018-08-19T00:00:00Z',
'name': 'Maestro Activity Log Export',
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{ 'exportId': 'id_1234' }

__________________________________________________________________

Request Screen Capture Usage Stats

Get the data for your agents' usage of the MaestroQA screen capture tool.

Definition

POST https://app.maestroqa.com/api/v1/screen-capture-usage-stats

Body Parameters

Name

Type

Description

groupIds*

array[string]

IDs of the agent groups whose data should be included in the screen capture usage stats
(required)

interval*

enum

(day, week, month)

Time interval for data returned in screen capture usage stats

(required)

apiToken

string

See authentication
(optional) - token may be passed in request body or in request headers

Response

List of data for agents in the specified groups who have used the extension during the given time interval.

Name

Type

Description

data

array[object]

Screen recording stats for each agent

data.agentId

string

The agent's id

data.numberExpectedRecordings

number

Number of recordings expected for this time interval

data.numberRecordings

number

Actual number of recordings for this time interval

data.percentRecorded

number

Percent of tickets recorded

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/screen-capture-usage-stats'

payload = {
'groupIds': ['123'],
'interval': 'day',
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{
'data': [
{ 'agentId': 'abc',
'numberExpectedRecordings': 10,
'numberRecordings': 1,
'percentRecorded': 10 },
{ 'agentId': 'def',
'numberExpectedRecordings': 5,
'numberRecordings': 1,
'percentRecorded': 20 }
]
}

__________________________________________________________________

Create a Ticket

Create a new Ticket in your MaestroQA account.

Definition

POST https://app.maestroqa.com/api/v1/tickets

Body Parameters

Name

Type

Description

gradable_id*

string

A unique identifier for the ticket.

(required)

Note: this id must be unique - if the id is in use by any other ticket in your account, the request will fail with a 409 Conflict error

type*

string

The ticket type/source from your external support system

(required)

subject*

string

The ticket's subject

(required)

agents*

array[string]

A list of the IDs of agents associated with the ticket

(required)

See Guide to User Roles for information about Agent IDs

link*

string

A link to the ticket in your external resource

(required)

body*

string

The text content of the ticket

(required)

tags

string

The ticket's tags, formatted as a comma-separated string

status

string

The ticket's status

(ex: "Closed")

csat_score

number

The CSAT score for the ticket

first_seen

string (see formats)

The date the ticket was created

Defaults to the current date

last_seen

string (see formats)

The date of the last activity on the ticket

Defaults to the current date

Response

The ticket that was created

Name

Type

Description

gradable_id

string

A unique identifier for the ticket.

type

string

The ticket type/source from your external support system

subject

string

The ticket's subject

agents

array[string]

A list of the IDs of agents associated with the ticket

link

string

A link to the ticket in your external resource

body

string

The text content of the ticket

tags

string

The ticket's tags, formatted as a comma-separated string

status

string

The ticket's status

csat_score

number

The CSAT score for the ticket

first_seen

string (see formats)

The date the ticket was created

last_seen

string (see formats)

The date of the last activity on the ticket

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/tickets'

payload = {
'gradable_id': 'unique_ticket_id',
'type': 'custom helpdesk',
'subject': 'New ticket',
'link': 'http://www.mynewticket.com',
'body': 'The text content of this ticket',
'status': 'open',
'agents': ['this_agent_id'],
'tags': 'login,support,escalated',
'csat_score': 5,
'first_seen': '2022-02-02T00:00:00.000Z',
'last_seen': '2022-03-07T00:00:00.000Z'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.post(url, json=payload, headers=headers)

Example Response

{
'_id': 'unique_maestro_id_for_ticket',
'gradable_id': 'unique_ticket_id',
'type': 'custom helpdesk',
'subject': 'New ticket',
'link': 'http://www.mynewticket.com',
'body': 'The text content of this ticket',
'status': 'open',
'agents': ['this_agent_id'],
'tags': 'login,support,escalated',
'csat_score': 5,
'first_seen': '2022-02-02T00:00:00.000Z',
'last_seen': '2022-03-07T00:00:00.000Z'
}

__________________________________________________________________

Update a Ticket

Update an existing Ticket in your MaestroQA account.

Note: tickets synced from helpdesk integrations cannot be manually updated

Definition

PATCH https://app.maestroqa.com/api/v1/tickets/:gradable_id

Path Parameters

Name

Type

Description

gradable_id*

string

The unique identifier for the ticket

(required)

Body Parameters

Name

Type

Description

type

string

The ticket type/source from your external support system

subject

string

The ticket's subject

agents

array[string]

A list of the IDs of agents associated with the ticket

See Guide to User Roles for information about Agent IDs

link

string

A link to the ticket in your external resource

body

string

The text content of the ticket

tags

string

The ticket's tags, formatted as a comma-separated string

status

string

The ticket's status

(ex: "Closed")

csat_score

number

The CSAT score for the ticket

first_seen

string (see formats)

The date the ticket was created

last_seen

string (see formats)

The date of the last activity on the ticket

Response

The updated ticket

Name

Type

Description

gradable_id

string

A unique identifier for the ticket.

type

string

The ticket type/source from your external support system

subject

string

The ticket's subject

agents

array[string]

A list of the IDs of agents associated with the ticket

link

string

A link to the ticket in your external resource

body

string

The text content of the ticket

tags

string

The ticket's tags, formatted as a comma-separated string

status

string

The ticket's status

csat_score

number

The CSAT score for the ticket

first_seen

string (see formats)

The date the ticket was created

last_seen

string (see formats)

The date of the last activity on the ticket

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/tickets/unique_ticket_id'

payload = {
'subject': 'Updated subject!',
'status': 'closed',
'last_seen': '2022-03-15T00:00:00.000Z'
}

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.patch(url, json=payload, headers=headers)

Example Response

{
'_id': 'unique_maestro_id_for_ticket',
'gradable_id': 'unique_ticket_id',
'type': 'custom helpdesk',
'subject': 'Updated subject!',
'link': 'http://www.mynewticket.com',
'body': 'The text content of this ticket',
'status': 'closed',
'agents': ['this_agent_id'],
'tags': 'login,support,escalated',
'csat_score': 5,
'first_seen': '2022-02-02T00:00:00.000Z',
'last_seen': '2022-03-15T00:00:00.000Z'
}

__________________________________________________________________

Delete a Ticket

Delete an existing Ticket in your MaestroQA account.

Note: tickets synced from helpdesk integrations cannot be manually deleted

Definition

DELETE https://app.maestroqa.com/api/v1/tickets/:gradable_id

Path Parameters

Name

Type

Description

gradable_id*

string

The unique identifier for the ticket

(required)

Response

N/A - successful delete requests will receive a 200 OK response

Example Request (Python)

import requests

url = 'https://app.maestroqa.com/api/v1/tickets/unique_ticket_id'

headers = { 'apitoken': 'YOUR_API_TOKEN' }

response = requests.delete(url, headers=headers)

__________________________________________________________________

Rate Limits

A given token has limits on how many times it can be used to make a request. These limits are subject to change, but there are guidelines to follow:

Demanding endpoints (such as requesting an export)

       1 request per second

       30 requests per minute

Easy endpoints (such as retrieving an export’s status and data url)

       10 requests per second

       100 requests per minute

You can expect to export 10,000 to 50,000 scores at time. The exact number is variable based on the size of your scorecard, number of comments per scorecard, and other factors.

Did this answer your question?