Conversational AI API Reference
Sherpa.ai Conversational AI is a REST API that provides developers with a framework and toolbox to formulate any request for Sherpa.ai, by using standard syntax technologies like HTTP Rest Services with a predefined set of URLs. These URLs represent various resources, any information or content accessed at that location, which can be returned as JSON, HTML, audio (speech) files or text.
API Endpoints
Sherpa.ai Conversational AI is a set of HTTP endpoints that help your app integrate with Sherpa.ai. These endpoints accept arguments as JSON in the request body and return results as JSON in the response body.
All Sherpa.ai Conversational AI API endpoints will be served on https://api.sherpa.ai/v2
Name | Path | Description |
---|---|---|
Authentication | /auth | Authentication related functions |
Dialogue | /query | Dialogue system Q/A and request/response |
Dialogue endpoints will be user-tailored, making use of the RequestInfo header parametrization, prioritizing location over other results.
Header Parameters
All the API calls have common parameters in the header.
Request Header | Mandatory | Description |
---|---|---|
Accept-Language | ✓ | {lang}-{country} • lang: The ISO 639-1 language code in lowercase. • country: The country/region code as an uppercase ISO-3166 2-letter code. ex: en-GB, en-US, es-ES, es-MX |
Time-Zone | ✓ | User’s time zone, in GMT +/- time or long format. ex: GMT+1:00, Europe/Berlin |
Accept | The response format of the body In most cases, it will be application/json . Otherwise, it will be specified in each method description. | |
Content-Type | ✓ | The request format of the body. In most cases, it will be application/json . Otherwise, it will be specified in each method description. |
The specific header parameters will be defined on each API call.
Sherpa-Request-Info
Specific Sherpa.ai header where parameters are grouped in the form of a JSON object.
Besides the specific information to be sent to each endpoint, Sherpa-Request-Info will gather the request context as a request header field.
The fields in RequestInfo are optional. However, each additional piece of data helps Sherpa.ai fetch a more tailored response, so including as many fields as possible is recommended.
For some location-related requests (weather, restaurants, etc.), the latitude and longitude are required. If they are not included, no results will be returned.
For example, by setting the lat and lon fields to specify user location, Sherpa.ai can use that information to respond to queries such as "Where am I?" or "Recommend a restaurant near here."
Field | Type | Description |
---|---|---|
lat | Double | Latitude |
lon | Double | Longitude |
country_code | String | The country/region code as an uppercase ISO-3166 2-letter code |
ref | String | Reference ID data, from a previous query context |
Example
In order to make a text-based dialogue query regarding the weather, latitude and longitude parameters are mandatory in the RequestInformation data header.
Request:
curl -X POST "https://api.sherpa.ai/v2/query/text" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX" \
-H "Sherpa-Request-Info:{\"lat\":37.468319,\"lon\":-122.143936}" \
-H "Accept-Language: en-US" \
-H "Time-Zone: Europe/Madrid"
-H "accept: application/json" \
-H "content-type: application/json" \
-d "{\"q\":\"what's the weather like?\"}"
Be aware that if you are using a tool like POSTMAN or PAW, you don't need to escape the Sherpa-Request-Info JSON, as the tool does it for you.
Response:
{
"context": {"ref": 342673096},
"nextActions": [{"data": ""}],
"responses": {
"query": "what's the weather like?",
"text": "Right now, in East Palo Alto, it is 51 degrees and cloudy. The temperature will rise in the coming hours."
}
}
Parameters
Each endpoint method will have a parameter table with explanatory information, along with an example. In this table, information will be provided for each field, like 'source', 'mandatory', 'type', and 'description'.
- Field
Parameter field -
Source
Where the parameter has to be placed- Query
Parameter is part of the URL -
Body
The parameter is set inside the body payloads part of a POST/PUT type method request. These parameters will be in JSON format and will require the corresponding header to be set:-H "content-type: application/json"
- Query
- Mandatory
Whether parameter is mandatory or not - Type
Value type [String, Integer, etc.] - Description
Additional information