Agents API

3 min read.

On this page

Welcome to the viky.ai API. You can use viky.ai API to extract information from unstructured contents or create virtual assistants to converse with your data.

Authentication

To access viky.ai resources, e.g. the agent endpoint for interpretation, you must specify the resource specific api token:

• in the request header: Agent-Token: my-agent-api-token,
• or as a URL parameter: ?agent_token=my-agent-api-token.

Here is an example for the agent viky/time:

# With shell, you can just pass the correct resource token header
# with each request
curl "https://viky-beta.viky.ai/api/v1/agents/viky/time/:action" \
  -H "Agent-Token: viky-time-api-token"

# or pass the token as a parameter in the URL
curl "https://viky-beta.viky.ai/api/v1/agents/viky/time/:action?agent_token=viky-time-api-token"

Errors

The viky.ai API uses the following error codes:

Error Code	Meaning
401	Unauthorized: Agent API token is wrong.
404	Not Found: The specified agent could not be found.
406	Not Acceptable: You requested a format that isn't json.
422	Unprocessable Entity: Parameters are not consistent.
429	Too Many Requests: Rate Limit Exceeded.
500	Internal Server Error: We had a problem with our server. Try again later.
503	Service Unavailable: We had a problem with our NLP server. Try again later.

Error responses always have a message associated within the errors array.

# Run that command:
curl "https://viky-beta.viky.ai/api/v1/agents/viky/time/interpret.json"

# Will return an 422 HTTP code with the following body:
{
  "errors":[
    "Access denied: wrong token."
  ]
}

GET /agents/:owner/:agent/interpret.json

Presentation

This endpoint retrieves all the interpretations extracted from a sentence passed as parameter.

Request example:

Get structured data from sentence “three quarters of an hour and 5 minutes” with available agent viky/time interpretations.

curl -G "https://viky-beta.viky.ai/api/v1/agents/viky/time/interpret.json?" \
     --data-urlencode "sentence=three quarters of an hour and 5 minutes" \
     -H "Agent-Token: the-agent-token"

JSON response:

{
  "interpretations": [
    {
      "id": "dd3ae8d2-812d-42ca-a551-b9219dd047ce",
      "slug": "viky/time/interpretations/duration_time",
      "name": "duration_time",
      "score": 0.99,
      "solution": {
        "duration": "PT50M"
      }
    }
  ]
}

Available query parameters

Parameter	Description
:owner required	The username of the agent's owner. Example: viky
:agent required	The name of the agent. Example: time
sentence required	The sentence to be processed by the AI. Example: three quarters of an hour and 5 minutes
language	The language code in which the sentence is written. This parameter is inspired from the HTTP Header Accept-Language conventions. Examples: *, all languages can be interpreted (default value). fr, only french language will be interpreted. en,fr;q=0.5, favor english over french languages. But no other languages will be interpreted.
spellchecking	How wide the spellchecking is run. Possible values are : inactive, low, medium or high. Default value is low.
now	The user current time with the UTC offset. Example: 2017-12-20T08:30:20+01:00
context	A custom JSON hash for statistics purpose. Example: { session_id: '0112f97b', bot_version: '1.2' }