logo
API docs by Redocly

EvaluAgent API (1.0.6)

Download OpenAPI specification:

Support: support@evaluagent.com URL: https://support.evaluagent.com

Introduction

Evaluagent API

You can use the EvaluAgent API to access and update information within your EvaluAgent account. The Evaluagent API is organised around REST. REST stands for Representational State Transfer. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term 'REST API', they are generally referring to an API accessed using the HTTP protocol at a predefined set of URLs.

These URLs represent various resources which can be returned as JSON, HTML or audio files. Often resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT and DELETE. These actions action represent the verbs Fetch, Create, Update and Delete respectively for those resources. The Evaluagent API is structured using the JSON:API specification and described using the OpenAPI specification.

In order to maintain data sovereignty our API can only be accessed regionally by cluster.

For customers on our European cluster (eu-west-1) the API URL is api.evaluagent.com.

For customers on our North America cluster (us-east) the API URL is api.us-east.evaluagent.com.

For customers on our Australian cluster (aus) the API URL is api.aus.evaluagent.com.

Syncing your knowledge base

Context Engine is only as good as the content behind it. The Knowledge Vault endpoints let you sync documents from wherever they actually live — Confluence, Zendesk Guide, Salesforce Knowledge, SharePoint — on a schedule, instead of re-uploading files by hand as they change.

Describe what your source currently holds, and let the Vault work out the difference:

  1. Send a manifest. PUT /context-engine/knowledge-vault/documents with mode=replace, a source, and one entry per document — its external_id, a title, and a SHA-256 content_hash of the text. No file content: this call is a reconciliation, not an upload. Start with dry_run=true, which writes nothing at all and returns exactly the plan the real call would apply.
  2. Read the plan. It comes back in five buckets. unchanged needs nothing. deleted has already happened. create and update are yours to action. skipped is a removal that was refused because the document is attached to a live line item topic — deleting it would leave that scorecard with nothing to assess against, so it was left alone and the topics are named for a human to detach.
  3. Send the content the plan asked for. POST /context-engine/knowledge-vault/documents for each create, and PUT /context-engine/knowledge-vault/documents/{id}/file for each update. Pass the same external_id, external_version and content_hash on those calls: that is what tells the Vault the document is now in sync, and stops the next manifest asking for it again. Replacing a file keeps the document's ID, title, tags and every line item attachment — a naive delete-and-reupload would silently unhook your scorecards.
  4. Confirm indexing. Documents are parsed and embedded asynchronously. Come back and check with filter[indexing_status]=failed to catch anything that could not be read — a PDF of scanned images, for example — rather than assuming a 201 means it is searchable.

Matching is on external_id, so renaming a page at the source updates the document you already have instead of creating a duplicate. And everything is scoped to source, so a sync can never reach documents uploaded by hand, or documents belonging to a different source.

Two things worth building in from the start. Treat 409 on a delete as an expected outcome to report, not an error to retry, because retrying can never succeed until someone detaches the document. And prefer filter[updated_from] over re-reading everything once your vault is large.

Writes are rate limited to 20 requests per minute per API key, separately from the standard tier, because each upload costs a file write, a parse and an embedding run. A 500-article knowledge base still loads in well under an hour.

Changelog

14 September 2026

  • Added a deleted_at field to the /quality/evaluations and /quality/evaluations/{id} resources, holding the UTC timestamp of the deletion and null for every evaluation that has not been deleted
  • Added filter[deleted_at;between] to /quality/evaluations, so deletions can be synced incrementally instead of re-fetching every deleted evaluation on each run. Asking for a range returns deleted evaluations without having to name deleted in filter[status]; naming a filter[status] that leaves deleted out is rejected with a 400
  • Added deleted_at to the sort values accepted by /quality/evaluations

1 September 2026

  • Added filter[status] to /quality/evaluations, accepting a comma-separated list of published, published_edited, published_hidden, calibration_session_published and deleted
  • Deleted evaluations can now be reported on, which brings the API in line with the quality CSV export. They are returned only when deleted is named in filter[status], so omitting the filter keeps the existing behaviour and no change is needed to existing integrations
  • /quality/evaluations/{id} accepts the same filter[status] and will return a deleted evaluation when deleted is named; without it a deleted evaluation still returns 404

19 August 2026

  • Added an analytics_state field to the /analytics/conversations and /analytics/conversations/{id} resources, reporting whether a conversation was analysed or the reason it was skipped
  • Added filter[analytics_state] to /analytics/conversations. Omitting it keeps the existing behaviour of returning only analysed conversations, so no change is needed to existing integrations

18 August 2026

  • created_to / updated_to on /context-engine/knowledge-vault/documents now include the whole of a date-only end day, instead of cutting off at midnight and excluding everything created during it
  • An unreadable date in any of the four date filters returns 400 rather than silently matching nothing
  • Document titles are now enforced unique by a database constraint, so two concurrent uploads of the same title can no longer both succeed; the loser gets the same duplicate_document_title 409 as a sequential duplicate
  • Added Knowledge Vault endpoints under /context-engine/knowledge-vault for managing the documents and tags that ground Context Engine
  • New endpoints: GET, POST /documents; GET, PATCH, DELETE /documents/{id}; PUT /documents/{id}/file; POST /documents/bulk-delete; POST /documents/tags
  • New endpoints: GET, POST /tags; PATCH, DELETE /tags/{id}
  • Documents list with filters on title, tag, indexing status, line item attachment and date ranges, and sort on title, created_at and updated_at
  • PUT /documents/{id}/file replaces a file while preserving the document's ID, title, description, tags and line item attachments
  • Deleting a document attached to a GenAI line item topic is refused with 409 and the blocking line items listed under errors[0].meta.line_items
  • Requires the Context Engine feature; writes are rate limited to 20 requests per minute

12 August 2026

  • Added a section object (id, name) to each entry in scores on the /reports/calibrations endpoint, matching the section already present on /quality/evaluations/{id}. section is null when the scorecard has only one section.
  • section is now null for any scorecard with a single section on both endpoints, not only when that section is named "General". A scorecard with one section is rendered without a section heading in the app, so it is reported as having no sections here too.

5 August 2026

  • Added a section object (id, name) to each line item on the /quality/evaluations/{id} endpoint. section is null when the scorecard does not use sections.

21 July 2026

  • Added /feedback and /feedback/{id} endpoints to list and fetch quality and general (peer-to-peer) feedback in a single consistent shape, distinguished by a type field

17 July 2026

  • Added filter[mode] parameter to /quality/evaluations to filter evaluations by evaluation mode name (case-insensitive exact match, supports a comma-separated list)

8 June 2026

  • Added filter[agent_id] parameter to /quality/evaluations to filter evaluations by the evaluated agent's user UUID (supports a comma-separated list)

10 March 2026

  • Added xcsat_result and xcsat_reasoning fields to the /analytics/conversations resource for xCSAT scores (1-5)
  • Added xces_result and xces_reasoning fields to the /analytics/conversations resource for xCES results (easy, neutral, difficult)
  • Added xces_driver_result and xces_driver_reasoning fields to the /analytics/conversations resource for xCES Driver results

13 February 2026

  • Added /quality/actions endpoints for listing, creating, viewing, updating (completing), and deleting actions
  • Added /quality/actions/{id}/messages endpoints for listing and creating messages on an action
  • Added /quality/messages/{id} endpoints for updating and deleting messages
  • Supports filtering by status, date ranges, assignee, creator, and origination
  • Supports sorting by due_at, created_at, and status
  • Supports including related assignee, creator, evaluation, and messages

13 January 2026

  • Added /quality/disputes endpoint to list evaluation disputes with filtering by status, dates, users, and scorecards
  • Added /quality/disputes/{id} endpoint to view a single dispute
  • Added /quality/evaluations/{id}/disputes endpoint to view disputes for a specific evaluation
  • Supports including related evaluation, contact, agent, stages, and stage line items
  • Added Calibration Sessions endpoints for listing and viewing calibration sessions
  • New endpoint: GET /quality/calibration-sessions - List calibration sessions with filtering, sorting, and pagination
  • New endpoint: GET /quality/calibration-sessions/{id} - Fetch a single calibration session by ID

6 January 2026

  • Added /analytics/conversations/{id}/transcript endpoint to retrieve conversation transcripts with speaker labels

28 November 2025

  • Added filter[scorecard_id] parameter to filter evaluations by scorecard UUID
  • Added filter[scorecard] parameter to filter evaluations by scorecard name (supports prefix matching)

24 July 2025

  • The /quality/evaluations/ now includes the contact's contact_date.

1 July 2025

  • Added updated_at property to line item feedback

25 June 2025

  • Removed reasons_for_contact field from conversationalAnalytics
  • Added rfc_primary_reason field to conversationalAnalytics
  • Added rfc_primary_reason_reasoning field to conversationalAnalytics
  • Added rfc_secondary_reason field to conversationalAnalytics
  • Added rfc_secondary_reason_reasoning field to conversationalAnalytics
  • Added rfc_primary_intent field to conversationalAnalytics
  • Added rfc_primary_intent_reasoning field to conversationalAnalytics
  • Added rfc_secondary_intent field to conversationalAnalytics
  • Added rfc_secondary_intent_reasoning field to conversationalAnalytics

18 June 2025

  • Updated the /quality/evaluations/{id} endpoint to include parent line items, which include an array of child line items.

2nd June 2025

  • Added Reports section with Calibration Reports endpoint

25th February 2025

  • Add include parameter to analytics/conversations to allowing the inclusion of metadata
  • Add metadata response to analytics/conversations/{id} endpoint

21st January 2025

  • Add integration as a required query parameter to the analytics/conversations endpoint

4th Sep 2024

  • Added rate-limiting to all endpoints. Maximum is 100 requests per minute, 10,000 per day, per API key, per endpoint.

5th August 2024

  • Added ping endpoint for authentication details
  • Added support for bearer tokens

12th July 2024

  • Added endpoint to retrieve analytics for a single conversation

08th July 2024

  • Added conversational analytics reporting endpoint

14th March 2024

  • Added Levels Index, Abilities Index, Groups CUD, Roles CUD

30th August 2023

  • Added additional details on Authentication

28th March 2023

  • Added 'scorecard_id' to evaluations list and single evaluation endpoints

21st Feb 2023

  • Added the 'agent' relationship to evaluations in the 'List evaluations' endpoint

2nd February 2023

  • Imported Contacts endpoint: Added metadata array example

31st January 2023

  • Improved documentation content & layout.
  • Deprecated /quality/contacts endpoint.

13th December 2022

  • Imported Contacts endpoint: removed requirement for a responses array or audio file path.

2 December 2022

  • Added third_party_id property to the users endpoints

19th October 2022

  • New endpoint for generating an Imported Contact
  • New endpoint for uploading audio files

8th September 2022

  • On the List Groups endpoint, added an additional attribute to indicate if the group was a part of the "Custom Reporting Groups" feature.

3rd August 2022

  • Added the ability to import third-party contacts.

26th April 2022

  • Added the property 'started_at' to the Evaluation resource.

15th November 2021

  • The users endpoint can now return an individual user via filter search string.

13th October 2021

  • Added the US-East cluster endpoint

2nd March 2021

  • Added the outcome_name property to Evaluations. This will contain the manual outcome if manual outcomes are in use, otherwise it will contain the name of the outcome configured by the user in Quality Settings.

24th September 2020

  • Added the seconds_elapsed property to Evaluations

28th May 2020

  • Added required tags to appropriate attributes in Create a Contact

5th March 2020

  • Added new sorting options for evaluations
  • Root causes will now appear with evaluations if present
  • Data capture responses will now appear with evaluations if present
  • Adding a new metadata property to Contacts which can include additional, third party information

QuickStart

Learn how to get started with the Evaluagent API. This article describes how to quickly get started with the Evaluagent API using curl and Basic Authentication.

  1. Install curl if it isn't already installed on your machine. To check if curl is installed, execute curl --version in the command line. If the output is information about the version of curl, it is installed. If you get a message similar to command not found: curl, you need to download and install curl. More information can be found here.
  2. Create an Evaluagent API key in Conversations>>Integrations>>API. Take a note of the Access Key ID and Secret Key. Warning: Treat your API key like a password.
  3. Use the curl command to make your request. Pass your token in an Authorization header. Replace YOUR-ACCESS-KEY-ID and YOU-SECRET-KEY with your Access Key ID and Secret Key respectively. curl –request GET --url "https://YOUR-CLUSTER-REGION/v1/org/users" -u "YOUR-ACCESS-KEY-ID:YOUR-SECRET-KEY"

Overview

API version

Available resources may vary between REST API versions. The current version is V1.

Schema

All API access is over HTTPS and via regional clusters

All data is sent and received as JSON.

Blank fields are included as null instead of being omitted. All timestamps return as a String in UTC time, ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Guides

Using the API

About the Evaluagent API

When you make a request to the REST API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and potentially a response body. The REST API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation.

Making a request

To make a request, first find the HTTP method and the path for the operation that you want to use. For example, the "List users" operation uses the GET method and the /org/users path. Prepend the base URL for the Evaluagent API region (for example: https://api.evaluagent.com in Europe) and then the version (currently v1) to the path to get the full URL. For example: https://api.evaluagent.com/v1/org/users in Europe.

Basics of authentication

Evaluagent supports HTTP Basic authentication. API keys can be provisioned in the Evaluagent platform under Conversations>>Integrations>>API. These are needed to authenticate requests against the API.

You must pass your Access Key ID and Secret Key in an Authorization header with every request to the API in the format "Basic YOUR-ACCESS-KEY-ID:YOUR-SECRET-KEY", where YOUR-ACCESS-KEY-ID:YOUR-SECRET-KEY are Base64 encoded. Many HTTP clients will automatically format in this way for you.

Bearer Token Authentication

Alternatively, you can use the details above to generate a Bearer Token. These expire every 24 hours (+15 minutes) unless they are refreshed, providing a new token and invaliding the existing token. Once a token has been generated, Basic Authentication will be disabled for those credentials. Please note that you must use your Bearer Token when you request to refresh, and this must be done before the current Bearer Token expires. Once a Bearer Token has expired it cannot be used to gain a refreshed token, and Basic Authentication will not be available. After expiration (without refresh), you will need to generate new credentials.

Ping

Check authentication status

Ping

Ping our API to verify your current authentication details

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "ping": "2024-01-01 00:00:00",
  • "ip": "127.0.0.1",
  • "bearer": {
    }
}

Tokens

Create, refresh, or expire Bearer Tokens for authentication

Create Token

Authorizations:
Basic

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "expiration": "2024-01-01 00:00:00"
}

Revoke Token

Invalidate the bearer token used for authentication. Please be aware that the basic authentication details that worked to create this token will continue to be unusable. This is a destructive action which will prevent future API requests associated with this key

Authorizations:
Bearer

Responses

Refresh Token

This will issue a new bearer token associated with this API key, the bearer token used for authentication will be invalidated upon issue of the new token

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "expiration": "2024-01-01 00:00:00"
}

Users

Fetch, create and update users

Create a user

Use this endpoint to add a new user to your Evaluagent org.

Authorizations:
BasicBearer
Request Body schema: application/json
required

Add a user to your Evaluagent org.

Define the Roles for this User using the Roles relationship. This can include making the user an Agent, Quality Analyst or Administrator as well as granting login access to the EvaluAgent app. A list of role ids can be found in the Roles endpoint.

If the created user is an Agent then the optional 'agent-team' relationship can be used to specify the id of the Group that they belong to. The list of Groups can be fetched using the Groups endpoint.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List users

Fetch a list of all the users in this org. Filter by email address to search for a specific user.

Authorizations:
BasicBearer
query Parameters
filter[email]
string <string>
Example: filter[email]=user@company.com

Return a specific user by their email address.

filter[username]
string <string>
Example: filter[username]=user@company.com

Return a specific user by their username.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Fetch a user

Fetch a specific user by userid

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the user to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an existing user

Update a user's details

Toggle state between active/deactive setting the 'active' attribute.

Define the Roles for this User using the Roles relationship. This can include making the user an Agent, Quality Analyst or Administrator as well as granting login access to the EvaluAgent app. A list of role ids can be found in the Roles endpoint.

If the user is an Agent then the 'agent-team' relationship can be updated to move the Agent to a different group. The list of groups can be fetched using the Groups endpoint.

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the user to update

Request Body schema: application/json
required

Updated details for the user

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Groups

List your group hierarchy

Create a group

Use this endpoint to add a new group to your Evaluagent org.

Authorizations:
BasicBearer
Request Body schema: application/json
required

Add a group to your Evaluagent org. Levels can be grabbed from the org/levels endpoint.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List groups

Fetch a list of your groups and their hierarchy within EvaluAgent. Useful for compiling a list of groups and their ids for managing agents.

Authorizations:
BasicBearer
query Parameters
show_inactive
boolean

Whether inactive groups should be shown. Defaults to false.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update an existing group

Update a group's details

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the group to update

Request Body schema: application/json
required

Updated details for the group

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete group

Delete group

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the group to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": null
}

Roles

List user roles

Create a role

Use this endpoint to add a new Role to your Evaluagent org.

Authorizations:
BasicBearer
Request Body schema: application/json
required

Add a role to your Evaluagent org. Abilities can be grabbed from the org/abilities endpoint.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List roles

Fetch a list of your roles within EvaluAgent. Useful for assigning roles to users.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update an existing role

Update a role's details

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the role to update

Request Body schema: application/json
required

Updated details for the role

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete role

Delete role

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the role to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": null
}

Integrations

List all Integrations

List integrations

Fetch a list of your integrations within EvaluAgent.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Levels

List levels

Fetch a list of your levels within EvaluAgent. Useful for creating groups.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Abilities

List abilities

Fetch a list of your abilities within EvaluAgent. Useful for creating roles.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Evaluations

List and query evaluations

List evaluations

Fetch a list of your completed evaluations and their results. The request can be filtered by date, scorecard, evaluation mode (filter[mode]), the evaluated agent (filter[agent_id]) and status (filter[status]), and sorted by published_at, date_published, updated_at, deleted_at, reference, score, agent_name, evaluator_name. The endpoint also supports pagination, requests default to the first page. If you also need the related contacts for the evaluations then use include to also return those contacts with the request.

Deleted evaluations are excluded by default. Ask for them with filter[status]=deleted, or alongside live ones with filter[status]=published,published_edited,deleted. This is how you reconcile against the quality CSV export, which has always included them.

To sync deletions incrementally, ask for the window since your last run with filter[deleted_at;between] rather than pulling every deleted evaluation and comparing locally. A deletion date range returns deleted evaluations on its own, so naming filter[status]=deleted as well is optional.

Authorizations:
BasicBearer
query Parameters
filter[published_at;between]
string <date-time>
Example: filter[published_at;between]=2023-05-01T00:00:00.000Z, 2023-08-01T00:00:00.000Z

A date range to filter evaluations on their published_at date. Consists of a comma-separated start and end date in UTC format.

filter[deleted_at;between]
string <date-time>
Example: filter[deleted_at;between]=2026-09-01T00:00:00.000Z, 2026-09-08T00:00:00.000Z

A date range to filter deleted evaluations on their deleted_at date. Consists of a comma-separated start and end date in UTC format. Only deleted evaluations carry a deletion date, so a range returns them on its own; naming a filter[status] that leaves deleted out is rejected with a 400. Both ends are inclusive, so when syncing run consecutive windows half-open on your side, starting the next one at the previous end, or a deletion falling exactly on a boundary is returned twice.

sort
string
Example: sort=-published_at

An option to sort by order of choice. Adding a minus operator to the start of field you wish to sort on will return results descending order. List of sorting options - published_at, date_published, updated_at, deleted_at, reference, score, agent_name, evaluator_name

page[number]
number
Example: page[number]=1

When paginated, the page number that you would like to request. Defaults to 1.

include
string
Example: include=contacts

Request that contacts associated with the returned evaluations be included under the "included" key in the response.

filter[scorecard_id]
string <uuid>
Example: filter[scorecard_id]=e15b67e1-816b-456d-94d4-43d362a2b4a0

Filter evaluations by scorecard UUID. Exact match.

filter[scorecard]
string
Example: filter[scorecard]=Customer Support

Filter evaluations by scorecard name. Supports case-insensitive prefix matching (e.g., "Customer" matches "Customer Support", "Customer Service").

filter[agent_id]
string
Example: filter[agent_id]=9d2f1c4e-3b6a-4f81-8c2d-71e0a5b9c3d4

Filter evaluations by the evaluated agent's user UUID. Accepts a single UUID or a comma-separated list of UUIDs to match any of them.

filter[mode]
string
Example: filter[mode]=Manual,Calibration

Filter evaluations by evaluation mode name, as returned in the mode attribute. Case-insensitive exact match. Accepts a single name or a comma-separated list of names to match any of them.

filter[status]
string
Example: filter[status]=published,deleted

Filter evaluations by the status attribute. Accepts a single status or a comma-separated list to match any of them: published, published_edited, published_hidden, calibration_session_published, deleted. Omitting this returns the four published statuses, which is the existing behaviour. Name deleted to see deleted evaluations, or ask for a range of filter[deleted_at;between], which returns them on its own; an unrecognised status is rejected with a 400.

Responses

Response samples

Content type
application/json

Response when include=contacts parameter is used

{
  • "meta": {
    },
  • "data": [
    ],
  • "included": [
    ]
}

Fetch an evaluation

Fetch a detailed view of an evaluation, including feedback and individual line item scores. Use include to also return related contacts and evaluators or agents for this specific evaluation.

A deleted evaluation returns 404 unless you ask for it with filter[status]=deleted.

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the evaluation to retrieve

query Parameters
filter[status]
string
Example: filter[status]=deleted

Naming deleted here returns the evaluation even if it has been deleted. Omitting it leaves the 404 in place, so an integration polling for an id it no longer holds is unaffected.

include
Array of strings
Items Enum: "contact" "evaluator" "agent"
Example: include=contact&include=evaluator&include=agent

A comma-separated list of records associated with the evaluation to be included under the "included" key in the response. Available record types are contact, evaluator, and agent.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

View evaluation disputes

Retrieve the disputes for a specific evaluation. This is equivalent to calling /quality/disputes/{id} with the evaluation UUID.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>
Example: 43aea3f1-00aa-4b9f-8dc4-9f843788bf41

The evaluation UUID.

query Parameters
include
string
Example: include=stages,stages.line_items,stages.appealer,stages.reviewer

Comma-separated list of related resources to include.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Disputes

List and query evaluation disputes

View evaluation disputes

Retrieve the disputes for a specific evaluation. This is equivalent to calling /quality/disputes/{id} with the evaluation UUID.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>
Example: 43aea3f1-00aa-4b9f-8dc4-9f843788bf41

The evaluation UUID.

query Parameters
include
string
Example: include=stages,stages.line_items,stages.appealer,stages.reviewer

Comma-separated list of related resources to include.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

List disputes

Retrieve a paginated list of evaluation disputes with filtering and sorting. Use the include parameter to embed related resources.

The disputes endpoint aggregates disputes by evaluation. Each dispute in the response represents all dispute activity for a single evaluation, with individual dispute stages accessible via the stages relationship.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
query Parameters
filter[created_at;between]
string <date-time>
Example: filter[created_at;between]=2026-01-01T00:00:00.000Z,2026-01-31T23:59:59.000Z

Filter by when the first dispute was raised. Comma-separated start and end date in UTC format.

filter[resolved_at;between]
string <date-time>
Example: filter[resolved_at;between]=2026-01-01T00:00:00.000Z,2026-01-31T23:59:59.000Z

Filter by resolution date. Only includes disputes where all stages are resolved. Comma-separated start and end date in UTC format.

filter[status]
string
Enum: "pending" "changed" "unchanged"
Example: filter[status]=pending

Filter by overall dispute status.

filter[evaluation_id]
string <uuid>
Example: filter[evaluation_id]=43aea3f1-00aa-4b9f-8dc4-9f843788bf41

Filter by evaluation UUID.

filter[contact_id]
string <uuid>

Filter by contact UUID.

filter[agent_id]
string <uuid>

Filter by agent UUID (the assignee on the evaluation).

filter[appealer_id]
string <uuid>

Filter by any stage appealer UUID.

filter[reviewer_id]
string <uuid>

Filter by any stage reviewer UUID.

filter[scorecard_id]
string <uuid>

Filter by scorecard UUID.

filter[scorecard]
string
Example: filter[scorecard]=Customer Service

Filter by scorecard name (prefix match).

sort
string
Enum: "created_at" "-created_at" "resolved_at" "-resolved_at"
Example: sort=-created_at

Sort results. Use - prefix for descending order.

page[number]
integer
Example: page[number]=1

Page number (default 1).

page[size]
integer <= 100
Example: page[size]=50

Results per page (default 50, max 100).

include
string
Example: include=evaluation,stages,stages.line_items,stages.appealer,stages.reviewer

Comma-separated list of related resources to include.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ],
  • "included": [
    ]
}

View dispute

Retrieve a single dispute by its ID (evaluation UUID). Use the include parameter to embed related resources.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>
Example: 43aea3f1-00aa-4b9f-8dc4-9f843788bf41

The dispute ID (same as evaluation UUID).

query Parameters
include
string
Example: include=evaluation,stages,stages.line_items,stages.appealer,stages.reviewer

Comma-separated list of related resources to include.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Calibration Sessions

List and view calibration sessions

List calibration sessions

Fetch a list of calibration sessions with optional filtering, sorting, and pagination. Use include to return related resources such as facilitator, participants, scorecard, or calibrated evaluation.

Authorizations:
BasicBearer
query Parameters
filter[status]
string
Enum: "pending" "in_progress" "closed"
Example: filter[status]=pending

Filter sessions by status

filter[start_at;between]
string
Example: filter[start_at;between]=2025-01-01,2025-01-31

A date range to filter sessions on their scheduled start date. Consists of a comma-separated start and end date in YYYY-MM-DD format.

filter[facilitator]
string <uuid>
Example: filter[facilitator]=99abbc05-9535-4e20-84be-0d4e55bcd407

Filter sessions by facilitator user UUID

filter[participant]
string <uuid>
Example: filter[participant]=99abbc05-9535-4e20-84be-0d4e55bcd407

Filter sessions by participant user UUID

filter[scorecard]
string <uuid>
Example: filter[scorecard]=25eeba63-ffe8-4f88-aa96-a3ea3e38757f

Filter sessions by scorecard/quality form UUID

sort
string
Enum: "start_at" "-start_at" "reference" "-reference" "status" "-status"
Example: sort=-start_at

Sort the returned sessions. Adding a minus operator to the start will return results in descending order. Valid options: start_at, reference, status

page[size]
integer [ 1 .. 100 ]
Default: 100
Example: page[size]=20

Number of items per page. Maximum 100.

page[number]
integer >= 1
Default: 1
Example: page[number]=1

Page number to retrieve. Defaults to 1.

include
string
Example: include=facilitator,participants,scorecard

Comma-separated list of related resources to include. Available: facilitator, participants, scorecard, contact, evaluation

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Fetch a calibration session

Fetch details of a single calibration session by its UUID. Use include to return related resources such as facilitator, participants, scorecard, or calibrated evaluation.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the calibration session to retrieve

query Parameters
include
string
Example: include=facilitator,participants,scorecard,evaluation

Comma-separated list of related resources to include. Available: facilitator, participants, scorecard, evaluation

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [ ]
}

Imported Contacts

Import conversations and contacts from external platforms into EvaluAgent

Generate an imported contact

Use this endpoint to import conversations from other platforms into Evaluagent.

  • For text-only conversations use this endpoint as is.
  • For conversations that include a recorded audio file you will need to first use the /quality/imported-contacts/upload-audio endpoint to upload that audio file. Then using the returned path reference use this endpoint to import the related metadata for your conversation.

Conversation responses are processed asynchronously after the request returns: a successful response confirms the contact was created and its responses accepted for processing, and the responses will typically be visible on the contact shortly afterwards. A GET for the contact immediately after import may briefly return it without its responses.

Please note there is rate-limiting in place for this endpoint. Maximum 100 requests per-minute, based on API credentials.

Authorizations:
BasicBearer
Request Body schema: application/json
required

Contact to add to EvaluAgent.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Success",
  • "contact_reference": "a63e026f-50ea-42c8-9fa1-418b4427a10c",
  • "3rd_party_reference": "contact001"
}

Update imported contact metadata

Use this endpoint to correct or add custom metadata fields on a conversation you have already imported, without re-importing it. The conversation is identified by the reference it was imported under.

Only metadata is changed. To change any other attribute of the conversation, or to add responses, re-import it.

Fields you send are merged into the conversation's existing metadata.

  • A field you send with a value replaces that field, or creates it if the conversation did not have it.
  • A field you send as null is removed from the conversation.
  • A field you do not send is left exactly as it was.

Newly created fields become available as reporting and conversation filters automatically. Updated values are reflected in conversation filtering immediately, and in Conversation Insights reporting once the conversation has been re-aggregated.

Values are stored with the JSON type you send them as. Sending "22" where the field previously held 22 will store the field as text, which excludes it from numeric filters — send numbers as numbers.

Some field names are reserved by Evaluagent and are rejected. These are names we write or read ourselves — the audio and video pointers (audio_url, video_url, sample_rate), the external link (external_url, conversation_url, linkToThirdParty), transcription and analytics fields (transcription_provider, totalWords), fields mirroring a column (channel_name, handling_time), and any name beginning with __. Field names cannot contain a full stop, and metadata must be an object of named fields rather than a list.

If two requests update the same conversation at the same time, changes to different fields are both kept; if both change the same field, the last one to complete wins.

Please note there is rate-limiting in place for this endpoint. Maximum 100 requests per-minute, based on API credentials.

Authorizations:
BasicBearer
Request Body schema: application/json
required

The conversation reference, and the metadata fields to change.

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Success",
  • "contact_reference": "9a0dfef9-1f3b-4c16-b4d6-0c7d5a7db4f1",
  • "metadata": {
    }
}

Upload audio

Use this endpoint to import recorded audio file conversations from other platforms into Evaluagent.

Use the path reference in the response from this endpoint when importing the related metadata with the /quality/imported-contacts endpoint.

The Evaluagent platform supports all audio encoded in a format supported by HTML5

Authorizations:
BasicBearer
Request Body schema: multipart/form-data
audio_file
required
null <binary>

The audio file to upload. Must be an MP3, WAV, OGG, M4A, etc.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "Audio file uploaded successfully",
  • "path": "quality/fb2db7c0-de00-43ed-997d-f587eac8bdbb/55649393-f708-4ebf-a665-a39942c030f1.mp3"
}

Conversational Analytics

Retrieve analytics data for your conversations over a specified period

Get Conversational Analytics

Fetch conversational analytics for contacts between a specified time period. This endpoint is rate limited to 20 request per minute. This limit is shared with GET :/analytics/conversations/{id}

Authorizations:
BasicBearer
query Parameters
filter[integration]
required
string
Example: filter[integration]=8fa6239b-14a6-4d40-8afe-398312f779f6

The UUID of the integration to return

filter[contact_date;between]
required
string <date-time>
Example: filter[contact_date;between]=2023-05-01T00:00:00.000Z, 2023-05-31T00:00:00.000Z

A date range to filter conversations on their contact_date. Consists of a comma-separated start and end date in UTC format.

filter[insight_topics][]
Array of arrays
Example: filter[insight_topics][]=13686037-e52e-470a-966c-843437e7d422

An array of topic UUIDs to filter conversations by

filter[analytics_state]
string
Example: filter[analytics_state]=audio-too-short,too-few-responses

Restricts results by analytics_state. Accepts a comma-separated list of complete, audio-too-short, audio-too-long, audio-missing, too-few-responses, skipped and purged, the pseudo-state none for conversations that have not been processed, or all for every conversation regardless of state.

When omitted, only conversations with an analytics_state of complete are returned. That is the long-standing behaviour of this endpoint, so existing integrations are unaffected.

sort
string
Example: sort=-contact_date

An option to sort by order of choice. Adding a minus operator to the start of field you wish to sort on will return results descending order. List of sorting options - contact_date

page[number]
number
Example: page[number]=1

When paginated, the page number that you would like to request. Defaults to 1.

include
string
Example: include=metadata

A comma separated list of additional fields

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Conversation

Fetch conversational analytics for a specific contact. This endpoint is rate limited to 20 request per minute. This limit is shared with GET :/analytics/conversations

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the conversation to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "43aea3f1-00aa-4b9f-8dc4-9f843788bf41",
  • "type": "conversational_analytics",
  • "attributes": {
    }
}

Get Conversation Transcript

Fetch the transcript for a specific conversation. Returns all utterances with speaker labels. This endpoint is rate limited to 20 requests per minute. This limit is shared with other analytics/conversations endpoints.

Authorizations:
BasicBearer
path Parameters
id
required
string

The id of the conversation to retrieve the transcript for

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Knowledge Vault

Manage the documents and tags that ground Context Engine, so AutoQA and GenAI line items assess against your current policies rather than a snapshot someone uploaded by hand. Requires the Context Engine feature.

List documents

Fetch the documents in your Knowledge Vault.

Each document carries its line_items — the GenAI line item topics it is attached to — so a sync job can tell in one request whether a document is safe to delete before attempting it.

Requires the Context Engine feature. Supports pagination and defaults to the first page, 50 per page, most recently updated first.

Authorizations:
BasicBearer
query Parameters
filter[title]
string
Example: filter[title]=complaints

Partial, case-insensitive match on the document title.

filter[tag_id]
string <uuid>

Only documents carrying this tag. Repeatable, or comma-separated; matches any of them.

filter[tag_name]
string
Example: filter[tag_name]=Compliance

Only documents carrying this tag name. Repeatable, or comma-separated; matches any of them.

filter[indexing_status]
string
Enum: "pending" "processing" "complete" "failed"

Restrict to one or more indexing states. Comma-separated.

filter[linked_to_line_items]
boolean

true returns only documents attached to at least one line item topic — the ones a delete will be refused for. false returns only unattached documents. Omit the parameter to get both; passing it empty is rejected rather than read as false.

filter[created_from]
string <date-time>
Example: filter[created_from]=2026-01-01T00:00:00Z

Documents created on or after this point. Accepts YYYY-MM-DD, taken as the start of that day, or an ISO 8601 datetime. Both bounds are inclusive. An unreadable value is rejected with 400 rather than silently matching nothing.

filter[created_to]
string <date-time>

Documents created on or before this point. Accepts YYYY-MM-DD, taken as the end of that day so the whole day is included, or an ISO 8601 datetime, which is honoured exactly. Both bounds are inclusive.

filter[updated_from]
string <date-time>

Documents updated on or after this point. Same date handling as created_from. This is the filter to use for incremental syncs.

filter[updated_to]
string <date-time>

Documents updated on or before this point. Same date handling as created_to.

sort
string
Example: sort=title

Sort order. Prefix with - for descending. Options: title, created_at, updated_at. Defaults to -updated_at.

page[number]
number
Example: page[number]=1

When paginated, the page number to request. Defaults to 1.

filter[sync_state]
string
Enum: "synced" "stale" "failed" "removed_at_source" "orphaned"
Example: filter[sync_state]=stale

One or more sync states, comma-separated: synced, stale, failed, removed_at_source, orphaned. The counterpart of filter[indexing_status] — this is how you find the documents a source has moved on from, removed, or that someone has edited locally, without paging the whole Vault.

An unrecognised state is rejected with 400 rather than returning an empty set, because a filter you act on should not answer a typo with "none". Each value in the list is checked, so stale,removed_at_source is accepted and stale,stail is refused whole.

filter[connection]
string
Example: filter[connection]=none,7c9e6679-7425-40de-944b-e07fc1f90ae7

One or more connection ids, comma-separated — the documents belonging to those sources.

none selects the documents that belong to no source: the hand-uploaded ones, which a sync must never touch and which cannot be named with an id. It combines with ids rather than replacing them, so none,<id> returns the hand-uploaded documents and that source's.

A value that is neither none nor a well-formed id is rejected with 400. A well-formed id that names nothing — including one belonging to another account — is not an error: it simply matches no documents.

page[size]
number
Example: page[size]=50

Documents per page. Defaults to 50, maximum 250.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Upload a document

Upload a single document to the Knowledge Vault as multipart/form-data.

Accepted formats are PDF, DOC, DOCX, TXT, CSV and HTML (.html or .htm), up to 10 MB per file, and the file must not be empty. Titles must be unique within the account.

To attach the document to a source — closing the loop on a create from PUT /documents — pass connection and external_id together, optionally with external_version, external_url and content_hash. Omit them for an ordinary upload and nothing changes.

The document is queued for parsing and embedding on success, so the response returns indexing_status: pending. Poll the document, or list with filter[indexing_status]=failed, to confirm it became searchable.

Rate limited to 20 requests per minute per API key, separately from the standard tier, because each upload costs a file write, a parse and an embedding run.

Authorizations:
BasicBearer
Request Body schema: multipart/form-data
required
file
required
string <binary>

The document itself. PDF, DOC, DOCX, TXT, CSV or HTML (.html or .htm), maximum 10 MB, and not empty.

title
required
string <= 255 characters

The document's name in the Knowledge Vault. Must be unique within the account.

description
string <= 255 characters

Optional free-text description.

tags
Array of strings

Tag IDs or names. A name that does not already exist is created; a name that does exist resolves to the existing tag rather than duplicating it, matched case-insensitively. A value in UUID form is always read as an ID: if no tag in your account has it the request is rejected, rather than a tag being created under the ID as its name.

connection
string <uuid>

The source this document belongs to, from the connection.id returned by PUT /documents. Must be sent together with external_id; sending one without the other is refused (incomplete_sync_identity), because a document half-attached to a source is invisible to the sync that created it.

external_id
string

The document's stable id in your system. This is what the manifest matches on.

external_url
string <uri>

Deep link back to the document at the source.

external_version
string

Your version identifier for the content being uploaded.

content_hash
string^[a-f0-9]{64}$

Hex SHA-256 of the text you extracted. Recording it here is what marks the document in sync — without it the next manifest asks for the same content again.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace the document set

Reconcile one source's documents against a manifest of its desired end state, and get back a plan of what changed.

The manifest carries no file content, by design. A request body is capped well below the size of a real knowledge base, and a multipart request has an undocumented ceiling on how many files it may carry — one it enforces by silently discarding the rest. So this endpoint takes ids and content hashes, works out what needs to happen, and applies the half it can: reconciling metadata, and removing what the source no longer has. Content for the create and update buckets is then sent through POST /documents and PUT /documents/{id}/file, which already validate formats and enforce the size limit.

That split is what makes the endpoint safe to point at a live account. The destructive half — the part where a mistake costs you documents — is centralised here, behind dry_run.

Everything is scoped to source. "Documents not in the manifest are deleted" applies only to documents belonging to that source. Documents uploaded by hand, and documents belonging to another source, are never touched.

Matching is on external_id, never the title. A page renamed at the source updates the document it already has, rather than creating a second one beside it.

Always returns 207, because the answer is per item: a manifest can legitimately create some documents, leave others alone, and be blocked on one.

Authorizations:
BasicBearer
Request Body schema: application/json
required
mode
required
string
Value: "replace"

Only replace is supported. Required rather than defaulted, because a PUT to this path deletes the documents it does not mention.

dry_run
boolean
Default: false

Return the plan without applying any of it. Nothing is written — not the documents, not even the connection itself, if it does not exist yet.

on_missing
string
Default: "delete"
Enum: "delete" "archive"

What to do with a document this source holds that the manifest does not mention. delete removes it. archive keeps it and sets sync_state to removed_at_source, which is the safer choice for an unattended job: a source that briefly returns a short manifest cannot then empty your Vault.

required
object

The source this manifest describes. Resolved by name within your account, and created on first use — there is no separate call to make. Everything this endpoint reconciles is scoped to it, so a sync can never touch documents uploaded by hand or belonging to another source.

required
Array of objects <= 5000 items

The desired end state for this source. An empty array is valid and means the source now holds nothing — the most destructive request this endpoint accepts, and the reason dry_run exists.

Note that no file content is carried here. See the endpoint description.

Responses

Request samples

Content type
application/json
{
  • "mode": "replace",
  • "dry_run": false,
  • "on_missing": "delete",
  • "source": {
    },
  • "documents": []
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Fetch a document

Fetch a single Knowledge Vault document, including its tags and the line item topics it is attached to. Never returns the file's contents.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the document.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a document

Update a document's title, description or tags. The file itself is replaced through PUT /context-engine/knowledge-vault/documents/{id}/file, so a title edit can never change the content by accident.

Line item attachments are unaffected.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the document.

Request Body schema: application/json
required
title
string <= 255 characters

Must be unique within the account.

description
string or null <= 255 characters
tags
Array of strings

Replaces the document's entire tag set. Omit the field to leave tags untouched; pass an empty array to clear them. Names that do not exist are created.

Responses

Request samples

Content type
application/json
{
  • "title": "Complaints procedure v4",
  • "description": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a document

Delete a document, its embeddings and its tag associations.

A document attached to one or more GenAI line item topics cannot be deleted: deleting it would strip those line items of the content they assess against. The request is refused with 409 and the blocking line items are listed under errors[0].meta.line_items. Detach the document in the application first, then retry.

Rate limited to 20 requests per minute per API key, on the same meter as the other write endpoints: tearing down a document's embeddings costs as much per document as bulk-delete does. A per-item delete loop will hit this - use POST /context-engine/knowledge-vault/documents/bulk-delete for more than a handful.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the document.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Replace a document's file

Replace the file behind an existing document as multipart/form-data, keeping the document ID, title, description, tags and every line item attachment intact. This is how you keep a synced knowledge base current without breaking the links your scorecards depend on.

The previous embeddings are invalidated, the document is queued for re-indexing, and indexing_status returns to pending. Pass content_hash (and optionally external_version) to record which source version this file is — that is what marks the document back in sync after a manifest reported it as an update. Format and size validation is identical to upload, and an empty file is refused before anything is replaced - the old file and its embeddings are only torn down once a valid replacement has been accepted.

Rate limited to 20 requests per minute per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the document.

Request Body schema: multipart/form-data
required
file
required
string <binary>

The replacement document. PDF, DOC, DOCX, TXT, CSV or HTML (.html or .htm), maximum 10 MB, and not empty.

external_version
string

The source version this file is. Optional; recorded against the document.

content_hash
string^[a-f0-9]{64}$

Hex SHA-256 of the text in this file. Sending it moves the document's sync_state from stale to synced — the manifest deliberately withholds the hash until the content it describes has actually arrived, so without this the next PUT /documents asks for the same file again.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete many documents

Delete up to 200 documents in one request. Always returns 207 with a result per document, so a single blocked document does not stall the rest: documents attached to a line item topic come back as 409 while everything else is deleted.

Rate limited to 20 requests per minute per API key.

Authorizations:
BasicBearer
Request Body schema: application/json
required
ids
required
Array of strings <uuid> <= 200 items [ items <uuid > ]

Document IDs to delete. Maximum 200 per request.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Apply or remove tags in bulk

Add or remove one or more tags across up to 200 documents in a single request — the API equivalent of the application's multi-select Apply Tags, plus the removal it has no button for. Returns 207 with a result per document.

Rate limited to 20 requests per minute per API key.

Authorizations:
BasicBearer
Request Body schema: application/json
required
action
required
string
Enum: "apply" "remove"

Whether to add the tags to, or remove them from, the given documents.

document_ids
required
Array of strings <uuid> <= 200 items [ items <uuid > ]

Documents to change. Maximum 200 per request.

tags
required
Array of strings

Tag IDs or names. On apply, a name that does not exist is created. On remove, only existing tags are matched — a name that does not exist is a no-op, never a new tag.

Responses

Request samples

Content type
application/json
{
  • "action": "apply",
  • "document_ids": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List tags

Fetch the Knowledge Vault tags in your account, each with the number of documents carrying it and the line item topics reachable through those documents — matching the Tags table in the application.

Authorizations:
BasicBearer
query Parameters
page[number]
number
Example: page[number]=1

When paginated, the page number to request. Defaults to 1.

page[size]
number
Example: page[size]=50

Tags per page. Defaults to 50, maximum 250.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create a tag

Create a standalone tag. Tag names are unique within the account. Tags can also be created implicitly by naming them on upload.

Authorizations:
BasicBearer
Request Body schema: application/json
required
name
required
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "name": "Compliance"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Rename a tag

Rename an existing tag. Every document carrying it keeps the tag.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the tag.

Request Body schema: application/json
required
name
required
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "name": "Compliance"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a tag

Delete a tag and detach it from every document carrying it. The documents themselves, their files and their embeddings are untouched.

Unlike documents, a tag delete is never blocked by line items. A tag is never itself attached to a line item topic — the line_items on a tag are reached through its documents — so removing it takes no content away from any line item.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the tag.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Templates

List Work Queue Templates

Fetch a list of Work Queue Templates in this org.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Fetch a Work Queue Template

Fetch a specific Work Queue Template by ID

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch Agents assigned to a Work Queue Template

Fetch a specific Work Queue Template by the given ID

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update Agents assigned to a Work Queue Template

Sync Agents assigned to the given Work Queue Template. Agents assigned to the Work Queue Template will be updated to match the given data, removing any assigned agents if not included in the data.

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Add Agents assigned to a Work Queue Template

Add agents assigned to the Work Queue Template

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete Agents assigned to a Work Queue Template

Delete Agents assigned to the given Work Queue Template

Authorizations:
BasicBearer
path Parameters
id
required
string

The ID of the Work Queue Template to retrieve

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Actions

Manage actions assigned to users

List actions

Fetch a paginated list of actions with optional filtering, sorting, and includes. Use include to return related resources such as assignee, creator, evaluation, or messages.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
query Parameters
filter[status]
string
Enum: "open" "completed"
Example: filter[status]=open

Filter actions by status.

filter[created_at;between]
string <date-time>
Example: filter[created_at;between]=2026-01-01T00:00:00.000Z,2026-01-31T23:59:59.000Z

Filter by creation date. Comma-separated start and end date in UTC format.

filter[due_at;between]
string <date-time>
Example: filter[due_at;between]=2026-01-01T00:00:00.000Z,2026-01-31T23:59:59.000Z

Filter by due date. Comma-separated start and end date in UTC format.

filter[assignee]
string <uuid>

Filter by assignee user UUID.

filter[creator]
string <uuid>

Filter by creator user UUID.

filter[origination]
string
Example: filter[origination]=evaluation

Filter by origination type (e.g. impromptu, evaluation).

sort
string
Enum: "due_at" "-due_at" "created_at" "-created_at" "status" "-status"
Example: sort=-due_at

Sort results. Use - prefix for descending order.

page[number]
integer
Example: page[number]=1

Page number (default 1).

page[size]
integer <= 100
Example: page[size]=50

Results per page (default 50, max 100).

include
string
Example: include=assignee,creator,messages

Comma-separated list of related resources to include. Available: assignee, creator, evaluation, messages

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ],
  • "included": [
    ]
}

Create an action

Create a new action. The authenticated user is set as the creator. An assignee is required. Optionally link an evaluation.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
Request Body schema: application/json
required

The action to create

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Fetch an action

Retrieve a single action by its UUID. Use include to embed related resources.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the action to retrieve

query Parameters
include
string
Example: include=assignee,creator,messages

Comma-separated list of related resources to include. Available: assignee, creator, evaluation, messages

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Complete an action

Update an action's status to completed. Once completed, an action cannot be reopened (returns 422).

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the action to update

Request Body schema: application/json
required

Updated action details

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Delete an action

Delete the specified action.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the action to delete

Responses

Response samples

Content type
application/json
{
  • "data": null
}

List messages for an action

Retrieve all messages for a specific action, ordered chronologically.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the action

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "included": [
    ]
}

Create a message on an action

Create a new message on an action. The authenticated user is set as the author. The action's assignee is automatically set as the recipient.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the action

Request Body schema: application/json
required

The message to create

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Action Messages

Manage messages on actions

List messages for an action

Retrieve all messages for a specific action, ordered chronologically.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the action

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "included": [
    ]
}

Create a message on an action

Create a new message on an action. The authenticated user is set as the author. The action's assignee is automatically set as the recipient.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the action

Request Body schema: application/json
required

The message to create

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Update a message

Update a message's body and/or recipient_present status.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the message to update

Request Body schema: application/json
required

Updated message details

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Delete a message

Delete the specified message.

Rate limiting: Maximum 100 requests per minute, 10,000 requests per day per API key.

Authorizations:
BasicBearer
path Parameters
id
required
string <uuid>

The UUID of the message to delete

Responses

Response samples

Content type
application/json
{
  • "data": null
}

Topics

Manage 121 Topics

List 121 Topics

Fetch a list of 121 Topics specific to the API Key's contract.

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

One To Ones

View & manage your 121s

List 121s

Fetch a list of your 121s and associated details. The request can be filtered by date and sorted by published_at, date_published, created_at, updated_at, reference, score, agent_name, evaluator_name. The endpoint also supports pagination, requests default to the first page.

Authorizations:
BasicBearer
query Parameters
filter[created_at;between]
string <date-time>
Example: filter[created_at;between]=2023-05-01T00:00:00.000Z, 2023-08-01T00:00:00.000Z

A date range to filter 121s on their created_at date. Consists of a comma-separated start and end date in UTC format.

filter[scheduled_date;between]
string <date-time>
Example: filter[scheduled_date;between]=2023-05-01T00:00:00.000Z, 2023-08-01T00:00:00.000Z

A date range to filter 121s on their scheduled_date. Consists of a comma-separated start and end date in UTC format.

filter[completed_at;between]
string <date-time>
Example: filter[completed_at;between]=2023-05-01T00:00:00.000Z, 2023-08-01T00:00:00.000Z

A date range to filter 121s on their completed_at date. Consists of a comma-separated start and end date in UTC format.

filter[participant]
string
Example: filter[participant]=99abbc05-9535-4e20-84be-0d4e55bcd407

Unique user ID to filter 121 participants by

filter[facilitator]
string
Example: filter[facilitator]=99abbc05-9535-4e20-84be-0d4e55bcd407

Unique user ID to filter 121 facilitators by

sort
string
Enum: "scheduled_date" "started_at" "completed_at" "topic" "participant"
Example: sort=-scheduled_date

Sort the returned 121s. Adding a minus operator to the start of field you wish to sort on will return results descending order.

page[number]
number
Example: page[number]=1

When paginated, the page number that you would like to request. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create 121

Create a new 121

Authorizations:
BasicBearer
Request Body schema: application/json
required

Create a new 121

object (BaseOneToOneParameters)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "one-to-ones",
  • "attributes": {
    },
  • "relationships": {
    }
}

Fetch 121

Retrieve details for a single 121.

Authorizations:
BasicBearer
path Parameters
id
string
Example: 99abbc05-9535-4e20-84be-0d4e55bcd407

Unique identifier for a single 121 record

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "one-to-ones",
  • "attributes": {
    },
  • "relationships": {
    }
}

Update 121

Update the 121 with the specified details

Authorizations:
BasicBearer
Request Body schema: application/json
required

Updated details for the 121

object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "one-to-ones",
  • "attributes": {
    },
  • "relationships": {
    }
}

Delete 121

Delete the specified 121

Authorizations:
BasicBearer

Responses

Response samples

Content type
application/json
{
  • "data": null
}

Calibrations

View and manage calibration reports

Fetch Calibration Reports

Retrieve calibration reports for your organization.

Authorizations:
BasicBearer
query Parameters
filter[session_date;between]
required
string <date-time>
Example: filter[session_date;between]=2025-05-01T00:00:00.000Z, 2025-08-01T00:00:00.000Z

A date range to filter calibration reports on their session date. Must be a comma-separated start and end date in UTC format. Date range cannot exceed 1 year (365 days).

filter[facilitator]
string
Example: filter[facilitator]=99abbc05-9535-4e20-84be-0d4e55bcd407

Unique user ID to filter calibration reports by facilitator

filter[scorecard]
string
Example: filter[scorecard]=25eeba63-ffe8-4f88-aa96-a3ea3e38757f

Unique scorecard ID to filter calibration reports by scorecard

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}