API

We provide a REST API to interact with our services. The API is open and can be used by anyone with an account and a payment method.

A quick overview of things you can do with the API:

• Request a response from one of your agents to a set of messages in realtime
• Request a response from one of your agents to be delivered to one of your webhooks

In the future we will add these additional features to the API:

• Generate a batch of agents using AI and some data from your end
• Use contexts with the API

Attention: We do not save messages from your requests or your agents. We are currently completely stateless in the sense of messages and chats. This means you need to handle storage of your messages yourself and provide the message context.

You can find the Open API specification for the API at https://api.novaro.ai/openapi.json (opens in a new tab) and the Scalar UI for it at https://api.novaro.ai/scalar (opens in a new tab).

Authentication

All requests to the API need to be authenticated. You can authenticate by sending a Bearer token in the Authorization header. The token needs to be a valid token that you can find in the dashboard.

Verifying Authentication

To verify that you are authenticated, you can send a GET request to the /api/v1/auth/verify endpoint. This will return a 200 status code if the authentication is valid and appropriate error messages if it is not. This endpoint is solely used for debugging purposes.

Realtime Messages

The messages API is mainly used to request a response from one of your agents. You can use it to send a set of messages to your agent and receive a response in realtime.

Asynchronous Message Requests

The asynchronous message requests API is used to request an asynchronous response from one of your agents. Different to the realtime messages API, this API does not return a response immediately. Instead, it schedules the message to be sent to one of your webhooks in the future.

Webhook Data

When the Webhook of your application is triggered, the content of the request will be the following:

{
  "messages": [
    {
      "role": "user",
      "createdAt": 1679553200,
      "content": "Hello, how are you?"
    },
  ],
  "reference": "INTERNAL_REFERENCE",
  "secret": "WEBHOOK_SECRET_HASH",
}

The reference property is the same as in the request. The secret property is the SHA256 hash of the secret you received when you created the webhook in the dashboard. Using this you can verify that the request is actually from us.

Response Timings

To make response times of asynchronous message requests realistic as in humans, we determine a response time based on two factors:

• The location or time zone of the agent
• Probabilities of the agent being online/available

The probablilites table is as follows:

This means that it's most likely that a response will be delivered to your webhook within less than 5 minutes. However, it can be after up to 24 hours.