Requests & responses

Requests

The API server speaks JSON. It's recommended that every request to our API includes a ContentType header set to application/json; charset=utf-8;. Requests that manipulate data (POST or PATCH) must send data as application/json. If the incoming request includes files, the content type should be set as multipart/form-data.

Authentication

The API is private and restricts public access, so every request sent to the API should be authenticated. Authenticated request should have x-api-key header present and its value should be a valid API key. Users can generate new API keys in the chatbot API keys management section on the murai platform.

$ curl -X 'POST' 'https://api.murai.ai/chats' \
       -H 'x-api-key: {API_KEY}' \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{}'

Responses

Query requests through GET method can return status codes 200, 400, 401, 403 or 500. Mutations through POST, PATCH and DELETE can also return status codes 201 and 422. Invalid routes or if the queried entity is not found the status code in the response object will be 404. Overall our API can return the following status codes:

• 200: Success.
• 201: Successfully created.
• 400: Bad request.
• 401: Unauthenticated access.
• 403: Unauthorized access.
• 404: Path not found.
• 422: Data validation failed.
• 500: System error.

Every API response includes a status code that can help identifying the cause of a potential problem. Successful requests include a data key, which hold a valid response object or array of objects. Response can also include a meta key, which holds additional information about the result (ex. count of queried entities).

{
  "status": ...,
  "data": { ... } || [ ... ],
  "meta": { ... },
}

In case of failure (status is different from 200 or 201), the server can respond with three different types of exceptions:

General exception

Most common errors are the general exceptions. They can include the following error statuses: 400, 401, 403, 404 and 500. In case of error with status 404 that means that the queried resource was not found. Errors include a unique code number, an error status, and the error message. The code number helps identify potential issues and points to their exact position in the system.

Fields in general exception:

Field	Description
status	The status of the returned error.
code	murai internal error code pointing to the exact position in the system.
message	Message describing the error.

{
  "status": 404,
  "code": 404011,
  "message": "CHAT_DOES_NOT_EXISTS",
}

Validation exception

Validation exception usually occurs when the received request data (body or query parameters) is invalid (i. e., it has invalid types or missing values). The status of the error will always be 422 and the error itself includes the entity name that caused the error and errors array which includes a list of error objects.

Fields in validation exception:

Field	Description
status	The status of the returned error - 422.
errors	Array of error objects.

And the errors field objects have the following properties:

Field	Description
code	murai internal error code pointing to the exact position in the system.
message	Message describing the error.
path	Array with field path in the received request data that triggered the error.

{
  "status": 422,
  "errors": [
    {
      "code": 4222055,
      "message": "ASK_DTO_QUERY_NOT_PRESENT",
      "path": [
        "query"
      ],
    }
  ],
}

Endpoint not found exception

If the requested endpoint doesn't exists the API will serve the endpoint not found exception. The status of the error will always be 404 and the error itself includes the same fields as general exception with addition of the HTTP method field and the URL path field.

Fields in not found exception:

Field	Description
status	The status of the returned error - 404.
code	murai internal error code pointing to the exact position in the system.
message	Message describing the error.
method	HTTP method of the received request.
path	Path/endpoint of the received request that triggered the error.

{
  "status": 404,
  "code": 400001,
  "message": "INVALID_PATH",
  "method": "GET",
  "path": "/info"
}