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.

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.

A sync job is a diff on title. Titles are unique per account, which makes them the natural key:

1. List what is already there. GET /context-engine/knowledge-vault/documents — page through it and index the result by title. Each document carries its line_items, so you know up front which ones are in use by a scorecard.
2. Update what changed. For a document that already exists, replace the file with PUT /context-engine/knowledge-vault/documents/{id}/file. The document ID, title, description, tags and every line item attachment survive — which is the point: a naive delete-then-reupload would silently unhook your scorecards. The old embeddings are invalidated and indexing_status returns to pending.
3. Create what is new. POST /context-engine/knowledge-vault/documents, naming tags inline; names that do not exist yet are created for you.
4. Remove what is gone. POST /context-engine/knowledge-vault/documents/bulk-delete with up to 200 IDs. Expect partial success: documents attached to a line item topic come back as 409 in the 207 body while the rest are deleted. That is deliberate — deleting them would leave those line items with nothing to assess against. Log them for a human to detach, and carry on.
5. 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.

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.

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

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"

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

All API access is over HTTPS and via regional clusters

• Europe: https://api.evaluagent.com.
• North America: https://api.us-east.evaluagent.com.
• Australia: https://api.aus.evaluagent.com.

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

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.

Check authentication status

Create, refresh, or expire Bearer Tokens for authentication

Fetch, create and update users

List your group hierarchy

List user roles

List all Integrations

List and query evaluations

List and query evaluation disputes

List and view calibration sessions