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
:
1
2
3
4
5
6
7
# 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.
1
2
3
4
5
6
7
8
9
# 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.
1
2
3
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"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: |
:agent
required
|
The name of the agent.
Example: time
|
sentence
required
|
The sentence to be processed by the AI.
Example: |
language |
The language code in which the sentence is written. This parameter is inspired from the HTTP Header Accept-Language conventions.
Examples:
|
spellchecking |
How wide the spellchecking is run.
Possible values are :
Default value is |
now |
The user current time with the UTC offset.
Example: |
context |
A custom JSON hash for statistics purpose.
Example: |