Menu
Sign up Log in

Tutorials

Topic guides

How-to guides

Reference guides

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:

    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: 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' }

    On this page

      Close
      Home Pricing Open Source Blog Documentation