Getting Started

The API follows a REST API architecture with JSON data formats using:

  • GET to access resources and perform queries. This method does not allow modifications.
  • POST to create or update resources. Creation is mostly performed by POSTing to a collections resource endpoint, e.g. https://api.mercury.ai/v1/library/
  • DELETE to delete resources.

Important: API requests must be made over HTTPS. Plain HTTP requests are unsupported and will fail as well as requests without a valid authentication key.

Setup

Before you can start using the Mercury.ai API, you must perform some preliminary steps to setup your account and create an API access token.

  1. Create your account on the Mercury.ai platform.
  2. Set up a bot project within your account.
  3. Create an API access token for your project on the Integrations page of your project's configuration settings.

Base URL

The current version of the API endpoints are accessible through a common base URL:

https://api.mercury.ai/v1

Responses

If a request was successful, the response indicates this by means of a HTTP status 200 and a field "success": true in the response body. In addition, the response may contain a data field with the requested data.

In case of API errors, we use the corresponding HTTP response codes (e.g. 404 NOT FOUND) to indicate the error class and additionally provide a developerInfo field (indicating what the problem with the request was) and a messages field (a non-technical error message that can be handed to the user).

The general structure of the response body thus is as follows:

{
    "success": true,
    "data": {
        <JSON_RESPONSE>
    },
    "message": "A message that can be presented to a user",
    "developerInfo": "A message added in case of errors with technical details for debugging"
}