NAV Navbar
shell
  • Introduction
  • Authentication
  • SentinoAPI
  • Errors
  • Introduction

    Welcome to Sentino API! You can use SentinoAPI to access the endpoints on its various functions. We have a language binding in Shell - you can view code examples in the dark area to the right. Binding for Python is coming soon.

    SentinoAPI service provides an application programming interface (API) in a form of a general psychology tool. The service uses Natural Language Processing algorithms to understand the written input of human language and analyze it in accordance with various psychological inventories.

    Sentino API provides a great flexibility to fit many domains. Based on the API an AI-powered chatting bot was built that leverages all API’s functions. One can see Sentino API in action by chatting with the bot on the website sentino.org/bot or via Facebook Messenger facebook.com/sentinobot.

    The analysis is based on such core personality models, as:

    A more detailed information on psychological inventories you can learn by proceeding to the description of a “Get inventories” function.

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl "api_endpoint_here"
      -H "Authorization: sentino_api_key"
    

    Make sure to replace sentino_api_key with your API key.

    SentinoAPI uses keys to allow access to the API. Sentino is still in developmental stage, so you can request the key by contacting us by e-mail: info@sentino.org

    SentinoAPI expects for the key to be included in all API requests to the server in a header that looks like the following:

    Authorization: sentino_api_key

    SentinoAPI

    Functions Summary SentinoAPI can provide you with the following functions’ opportunities:

    Function Description
    closest_items The closest items* to the given one
    similarity Similarity between two given items
    similarity_many Similarity between the given item and others
    classify Classify the given item according to classifications
    projection Projection of the given item on the specified psychological inventory**
    inventories Get the list of all psychological inventories
    inventories/<inventory> Get the list of indices*** for a given psychological inventory
    inventories/<inventory>/<index> Get the list of items (with their correlation sign) for a given index and inventory
    items Get main items used
    items/<inventory> Get all items for a given inventory
    items/<inventory>/<index> Get all items for a given index and inventory

    *an item - a self-statement (should start with I...)

    **an inventory - a type of a psychological questionnaire in which a person answers (agrees or disagrees with) self-statements

    ***an index - a particular trait that is being evaluated with the help of a questionnaire

    Items proximity

    The Service allows to analyze a given self-statement (item)(should start with “I...”) by finding linguistically closest statements; compare two items and find their correlation factor* or compare an item and many other items.

    The Service finds linguistically closest statements/compares two or more self-statements, following specific commands with specific attributes. You can find detailed explanations in the subcategories of each function below.

    Closest items

    curl "https://sentino.org/api/v1/closest_items"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
      {
        "include_adjectives": false,
        "include_items": true,
        "text": "I am smart",
        "n": 2,
        "prioritize": true,
        "closest_items": [
            [
                "I use my brain.",
                0.7824043035507202
            ],
            [
                "I am well-informed.",
                0.7432236075401306
            ],
      }
    ]
    

    This endpoint retrieves all the closest items to the given one.

    HTTP Request POST https://sentino.org/api/v1/item/closest_items

    Query Parameters

    Parameter Default Description
    include_items true If set to true, the result will include items
    prioritize true If set to true, the result will prioritize items
    include_adjectives false If set to false, the result will not include adjectives
    text If set to true, the result will be based on the item given
    n If set to true, the number of closest items will be limited to n

    Similarity item vs item

    curl "https://sentino.org/api/v1/item/similarity"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
      {
        "text_to": "I am intelligent",
        "similarity": 0.9865415096282959,
        "text": "I am smart"
      }
    ]
    

    This endpoint shows the similarity between two items.

    HTTP Request POST https://sentino.org/api/v1/item/similarity

    Query Parameters

    Parameter Default Description
    text If set to true, the result will be based on the item given
    text_to If set to true, the given item will be compared with the second given one

    Similarity item vs others

    curl "https://sentino.org/api/v1/item/similarity_many" 
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
      {
        "texts": [
            "I am intelligent",
            "I am stupid",
            "I am curious"
        ],
        "similarity_many": [
            0.9865415096282959,
            -0.49402618408203125,
            0.7824224233627319
        ],
        "text": "I am smart"
      }
    ]
    

    This endpoint shows the similarity between the given item and others.

    HTTP Request POST https://sentino.org/api/v1/item/similarity_many

    Query Parameters

    Parameter Default Description
    text If set to true, the result will be based on the item given
    texts If set to true, the given item will be compared with many other items

    Item classification

    The Service allows to analyze a given self-statement (an item that starts with “I...”) by classifying it according to specific classifications.

    curl "https://sentino.org/api/v1/item/classify"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
      {
        "text": "I am smart",
        "basics": {
            "is_neutral": false,
            "is_psy": 0.9878731111277546,
            "is_item": 0.9085067968467878,
            "is_positive": true,
            "is_negative": false
         },
        "classify": {
            "age": 0.012038968341877312,
            "sibling_status": 0.00021086952966029363,
            "education_status": 0.015688905902744587,
            "gender": 0.0030971928952797426,
            "parental_status": 0.0016620463384642151,
            "marital_status": 0.030845599569901454,
            "appearance": 0.6165219049303399,
            "family_status": 0.00018607097710675316,
            "orientation": 0.00020928383038939602,
            "name": 0.03186717969140328,
            "skill": 0.1151760161148173,
            "food_preference": 0.012583380677582396,
            "religion": 0.00016829460217090335,
            "ethnicity": 0.006827873939135297,
            "location_origin": 0.0008027117479613173,
            "language": 0.0006399161559379098,
            "health_status": 0.009739340343614978,
            "location_residence": 0.0011186231865793217
         }
      }
    ]
    

    This endpoint classifies the given item according to the following classifications:

    Basic categories Typical item
    is_psy An item with a psychological meaning -- I am an extrovert
    is_item Any meaningful item about a person -- I am ambitious
    is_neutral Neutral valence -- I am an average person
    is_positive Positive valence -- I am a good person
    is_negative Negative valence -- I am a bad person
    Categories Typical item
    location_residence I live in Great Britain
    health_status I suffer from migraines
    sibling_status I am an only child
    religion I am a committed atheist
    food_preference I like pizza
    age I am 45 years old
    family_status I have adopted children
    parental_status I am a single dad
    appearance I am good-looking
    orientation I am a straight man
    ethnicity I am Asian
    gender I am a guy
    name I am Benedict Timothy Carlton Cumberbatch
    education_status I have a higher education
    location_origin I came from Atlantis
    language I speak Klingon
    skill I am a good cook
    marital_status I am married

    HTTP Request POST https://sentino.org/api/v1/item/classify

    Query Parameters

    Parameter Default Description
    text If set to true, the result will be based on the item given

    Item projection

    The Service allows to analyze a given self-statement (an item that starts with “I...”) by projecting it on a specified psychological inventory. You should choose a particular inventory from the list of psychological inventories. You can check the list at https://sentino.org/api/v1/inventories.

    curl "https://sentino.org/api/v1/item/projection"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
      {
        "is_neutral": false,
        "is_negative": false,
        "is_item": 0.9085067968467878,
        "is_psy": 0.9878731111277546,
        "inventory": "neo",
        "projection": {
            "altruism": 0.17900752429084468,
            "liberalism": 0.21198500692956374,
            "orderliness": 0.07070029477189974,
            "cautiousness": 0.302416465883721,
            "anxiety": -0.28512836282774356,
            "activity level": 0.2950789243517695,
            "emotionality": 0.19575248727935962,
            "modesty": -0.3404318258683371,
            "cooperation": 0.050226117762244976,
            "intellect": 0.748110828892317,
            "self-discipline": 0.31637817909927696,
            "sympathy": 0.10482461187638382,
            "self-efficacy": 0.6072337896623207,
            "imagination": 0.3597621309848465,
            "anger": -0.24591729721755703,
            "excitement-seeking": 0.0600540165146256,
            "achievement": 0.4924563594263276,
            "adventurousness": 0.44614988973283143,
            "vulnerability": -0.5138821886249736,
            "trust": 0.13648896673986274,
            "immoderation": -0.23810308295744756,
            "cheerfulness": 0.22035710104493345,
            "dutifulness": 0.23405066865084048,
            "artistic interests": 0.3515507332835389,
            "depression": -0.35883854843243884,
            "self-consciousness": -0.4115042795390079,
            "friendliness": 0.24695844985934873,
            "morality": 0.12518488721162868,
            "assertiveness": 0.38555110371792295,
            "gregariousness": 0.01366071233466303
        },
        "is_positive": true,
        "text": "I am smart"
      }
    ]
    

    This endpoint shows the projection of the given item on a specified psychological inventory.

    HTTP Request POST https://sentino.org/api/v1/item/projection

    Query Parameters

    Parameter Default Description
    text If set to true, the result will be based on the item given
    inventory If set to true, the item is projected on the given inventory

    Personality inventories

    The Service allows to see all the psychological inventories used for analyzing self-statements, in addition to all the facets of the inventories (indices) and the items that correspond to a particular inventory and/or index. You can find detailed explanations in the subcategories of each function below.

    Get inventories

    curl "https://sentino.org/api/v1/inventories"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
      {
        "inventories": [
            "6fpq",
            "8ics",
            "ab5c",
            "adjectives",
            "bfas",
            "big5",
            "big7",
            "bisbas",
            "cat-pd-sf",
            "cpi",
            "emoint",
            "epq",
            "hexaco",
            "jpi",
            "mpq",
            "neo",
            "orvis",
            "ps",
            "qb6",
            "tci",
            "via"
        ]
      }
    ]
    

    This endpoint shows all psychological inventories.

    List of inventories

    Inventory Description
    6fpq Six Factor Personality Questionnaire
    8ics 8 IPIP Interpersonal Circumplex Scales
    ab5c 45 AB5C facets

    HTTP Request GET https://sentino.org/api/v1/inventories

    Get inventory indices

    curl "https://sentino.org/api/v1/inventories/bfas"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
     {
        "indices": [
            "agreeableness",
            "conscientiousness",
            "extraversion",
            "neurotism",
            "openness"
        ],
        "inventory": "big5"
      }
    ]
    

    This endpoint shows all indices for a given psychological inventory.

    HTTP Request GET https://sentino.org/api/v1/inventories/<inventory>

    Instead of <inventory> you should choose a particular inventory from the list of psychological inventories. You can check the list at https://sentino.org/api/v1/inventories.

    Get index items

    curl "https://sentino.org/api/v1/inventories/bfas/intellect"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
     {
        "item_signs": [
            [
                "I avoid difficult reading material.",
                -1
            ],
            [
                "I avoid philosophical discussions.",
                -1
            ],
            [
                "I have difficulty understanding abstract ideas.",
                -1
            ]
    ...
      }
    ]
    

    This endpoint shows 10 items (with their correlation sign) for a given index and inventory.

    HTTP Request GET https://sentino.org/api/v1/inventories/<inventory>/<index>

    Instead of <inventory> you should choose a particular inventory from the list of psychological inventories. You can check the list at https://sentino.org/api/v1/inventories.

    Instead of <inventory> you should choose a particular index of the inventory. You can see them at https://sentino.org/api/v1/inventories/ (mention the previously chosen inventory).

    Items retrieval

    The Service allows to see the lists of all the main items used by the Service, all the items for a given inventory and for a particular index. You can find detailed explanations in the subcategories of each function below.

    Main items

    curl "https://sentino.org/api/v1/items"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
      {
        "items": [
            "I abuse people's confidences.",
            "I accept apologies easily.",
            "I accept challenging tasks.",
            "I accept little from others.",
            "I accept others' weaknesses.",
            "I accept people as they are.",
            "I accept the consequences of my actions.",
             
      }
    ]
    

    This endpoint retrieves all main items used.

    HTTP Request GET https://sentino.org/api/v1/items

    Inventory items

    curl "https://sentino.org/api/v1/items/neo"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
      {
        "items": [
            "I act comfortably with others.",
            "I act wild and crazy.",
            "I act without thinking.",
            "I adapt easily to new situations.",
            "I am a creature of habit.",
            "I am able to control my cravings.",
            "I am able to stand up for myself.",
            "I am afraid of many things.",
             
       }
    ]
    

    This endpoint retrieves all the items for a given inventory.

    HTTP Request GET https://sentino.org/api/v1/items/<inventory>

    Instead of <inventory> you should choose a particular inventory from the list of psychological inventories. You can check the list at https://sentino.org/api/v1/inventories.

    Index items

    curl "https://sentino.org/api/v1/items/neo/anger"
      -H "Authorization: sentino_api_key"
    

    The above command returns JSON structured like this:

    [
     {
        "items": [
            "I am not easily annoyed.",
            "I am often in a bad mood.",
            "I get angry easily.",
            "I get irritated easily.",
            "I get upset easily.",
            "I keep my cool.",
            "I lose my temper.",
            "I rarely complain.",
            "I rarely get irritated.",
            "I seldom get mad."
        ],
        "inventory": "neo",
        "index": "anger"
       }
    ]
    

    This endpoint retrieves 10 items for a given index and inventory.

    HTTP Request* GET https://sentino.org/api/v1/items/<inventory>/<index>

    Instead of you should choose a particular inventory from the list of psychological inventories. You can check the list at https://sentino.org/api/v1/inventories.

    Instead of you should choose a particular index of the inventory. You can see them at https://sentino.org/api/v1/inventories/ (mention the previously chosen inventory).

    Errors

    The Kittn API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The kitten requested is hidden for administrators only.
    404 Not Found -- The specified kitten could not be found.
    405 Method Not Allowed -- You tried to access a kitten with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    410 Gone -- The kitten requested has been removed from our servers.
    418 I'm a teapot.
    429 Too Many Requests -- You're requesting too many kittens! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.