Mito.ai API is easy to implement and combine.

Following is documentation for a subset of the Mito.ai API.

Run in Postman

Authorization

In order to use the API, you need a token which should be passed as a Bearer token in the Authorization header. This token is obtained from Auth0 with the following request:

POST https://mito.eu.auth0.com/oauth/token

with JSON encoded body on the format:

{
  "grant_type": "client_credentials",
  "client_id": "[[auth0-client-id]]",
  "client_secret": "[[auth0-client-secret]]",
  "audience": "https://api.mito.ai"
}

Example

curl -X POST \
  https://mito.eu.auth0.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "[[clientId]]",
    "client_secret": "[[clientSecret]]",
    "audience": "https://api.mito.ai"
  }'

yields

{
    "access_token": "[[token]]",
    "scope": "entities:list simple-entities:read news:list simple-news:read",
    "expires_in": 28800,
    "token_type": "Bearer"
}

Notice that the token is a JWT token which expires. Read more about JWT at jwt.io.

Before getting access to news for a company, cryptocurrency or any other of our 18 million entities, you need to find the corresponding entity id. This can be done with the search endpoint

GET https://prod.mito.ai/api/v2/entities?q=[[search-term]]&searchProfile=[[search-profile]]

where

search-profile =
 | 'tradable'
 | 'isin'
 | 'ticker'
 | 'country'
 | 'geographic'
 | 'human'
 | 'materialArts'
 | 'organization'
 | 'product'

Example

Searching for Nokia

curl -X GET \
  'https://prod.mito.ai/api/v2/entities?q=Nokia' \
  -H 'Authorization: Bearer [[token]]'

Produces

{
    "entities": [
        {
            "id": "Q1418",
            "href": "/api/v2/entities/Q1418"
        },
        {
            "id": "Q219691",
            "href": "/api/v2/entities/Q219691"
        },
        {
            "id": "Q25384984",
            "href": "/api/v2/entities/Q25384984"
        },
        {
            "id": "Q192870",
            "href": "/api/v2/entities/Q192870"
        },
        {
            "id": "Q28845574",
            "href": "/api/v2/entities/Q28845574"
        },
        {
            "id": "Q28150977",
            "href": "/api/v2/entities/Q28150977"
        },
        {
            "id": "Q913421",
            "href": "/api/v2/entities/Q913421"
        },
        {
            "id": "Q24033075",
            "href": "/api/v2/entities/Q24033075"
        },
        {
            "id": "Q33697438",
            "href": "/api/v2/entities/Q33697438"
        },
        {
            "id": "Q498806",
            "href": "/api/v2/entities/Q498806"
        }
    ]
}

Entity details

Given an entity ID you can fetch more details with the endpoint

GET https://prod.mito.ai/api/v2/entities/[[entity-id]]

Example

Fetching more details about the entity Q1418:

curl -X GET \
  https://prod.mito.ai/api/v2/entities/Q1418 \
  -H 'Authorization: Bearer [[token]]'

Produces

{
    "id": "Q1418",
    "href": "/api/v2/entities/Q1418",
    "name": "Nokia",
    "description": "Finnish technology corporation"
}

Entity news

Given the entity ID you can fetch news related to the entity with:

GET https://prod.mito.ai/api/v2/news?entityIds=[[entity-id]]&filterOverlapping=[[filter-overlapping]]&since=[[since]]&selection=[[selection]]&size=[[size]]&categories=[[category]],[[category]],...

where

since              = 'hour' | 'h12' | 'day' | 'week' | 'month' | 'year'
filter-overlapping = true | false
selection          = 'relevant' | 'recent'
category           =
  | 'arts_culture_and_entertainment'
  | 'crime_law_and_justice'
  | 'disaster_accident_and_emergency_incident'
  | 'economy_business_and_finance'
  | 'education'
  | 'environment'
  | 'health'
  | 'human_interest'
  | 'labour'
  | 'lifestyle_and_leisure'
  | 'politics'
  | 'religion_and_belief'
  | 'science_and_technology'
  | 'society'
  | 'sport'
  | 'conflicts_war_and_peace'
  | 'weather'
size               =  [0;100]

here since is the time interval for the search, filterOverlapping decides if duplicate articles should be filtered wrt. clustering, selection is different method for selecting the articles, impactful selcting the articles that are gaining the highest tracktion globally and recency is the most recent articles, size is the maximun output size, and categories is a comma seperated list of categories.

Example

Searching for recent articles to entity ID Q1418 (Nokia):

curl -X GET \
  'https://prod.mito.ai/api/v2/news?entityIds=Q1418&filterOverlapping=true&since=day&selection=balanced&size=10' \
  -H 'Authorization: Bearer [[token]]'

yields

{
  "articles": [
    {
      "id": "aHR0cDovL2NvbXB1dGVyc3dlZGVuLmlkZy5zZS8yLjI2ODMvMS42OTc4MzQvbm9raWEtbW9iaWxtYXJrbmFkZW4",
      "href": "/api/v2/news/aHR0cDovL2NvbXB1dGVyc3dlZGVuLmlkZy5zZS8yLjI2ODMvMS42OTc4MzQvbm9raWEtbW9iaWxtYXJrbmFkZW4"
    },
    {
      "id": "aHR0cHM6Ly93d3cuaGluZHVzdGFudGltZXMuY29tL3RlY2gvb25lLWJyb2FkYmFuZC1wYXJ0bmVycy1ub2tpYS10by1pbXByb3ZlLWhpZ2gtc3BlZWQtYnJvYWRiYW5kLXNlcnZpY2VzL3N0b3J5LUwxZmtid2R0a2lLMWliUVNrVUdCa0wuaHRtbA",
      "href": "/api/v2/news/aHR0cHM6Ly93d3cuaGluZHVzdGFudGltZXMuY29tL3RlY2gvb25lLWJyb2FkYmFuZC1wYXJ0bmVycy1ub2tpYS10by1pbXByb3ZlLWhpZ2gtc3BlZWQtYnJvYWRiYW5kLXNlcnZpY2VzL3N0b3J5LUwxZmtid2R0a2lLMWliUVNrVUdCa0wuaHRtbA"
    },
    {
      "id": "aHR0cHM6Ly93d3cubWFya2V0d2F0Y2guY29tL3N0b3J5L2x0ZS1lcXVpcG1lbnQtbWFya2V0LXNwZWFyaGVhZGVkLWJ5LW1hc3NpdmUtZXhwYW5zaW9uLWluLWFzaWEtcGFjaWZpYy1tYXJrZXQtdG8td2l0bmVzcy1oZWFsdGh5LWdyb3d0aC1zYXlzLXRtci0yMDE4LTAyLTE0",
      "href": "/api/v2/news/aHR0cHM6Ly93d3cubWFya2V0d2F0Y2guY29tL3N0b3J5L2x0ZS1lcXVpcG1lbnQtbWFya2V0LXNwZWFyaGVhZGVkLWJ5LW1hc3NpdmUtZXhwYW5zaW9uLWluLWFzaWEtcGFjaWZpYy1tYXJrZXQtdG8td2l0bmVzcy1oZWFsdGh5LWdyb3d0aC1zYXlzLXRtci0yMDE4LTAyLTE0"
    },
    {
      "id": "aHR0cDovL3d3dy5nbG9iZW5ld3N3aXJlLmNvbS9uZXdzLXJlbGVhc2UvMjAxOC8wMi8xNC8xMzQ3ODgxLzAvZW4vTFRFLUVxdWlwbWVudC1NYXJrZXQtU3BlYXJoZWFkZWQtYnktTWFzc2l2ZS1FeHBhbnNpb24taW4tQXNpYS1QYWNpZmljLU1hcmtldC10by1XaXRuZXNzLUhlYWx0aHktR3Jvd3RoLXNheXMtVE1SLmh0bWw",
      "href": "/api/v2/news/aHR0cDovL3d3dy5nbG9iZW5ld3N3aXJlLmNvbS9uZXdzLXJlbGVhc2UvMjAxOC8wMi8xNC8xMzQ3ODgxLzAvZW4vTFRFLUVxdWlwbWVudC1NYXJrZXQtU3BlYXJoZWFkZWQtYnktTWFzc2l2ZS1FeHBhbnNpb24taW4tQXNpYS1QYWNpZmljLU1hcmtldC10by1XaXRuZXNzLUhlYWx0aHktR3Jvd3RoLXNheXMtVE1SLmh0bWw"
    },
    {
      "id": "aHR0cHM6Ly93d3cuam9oYW5zZW4uc2UvYmxvZy8yMDE4LzAyLzE0L25va2lhLTgtaGFyLWZhdHQtYW5kcm9pZC04LTEv",
      "href": "/api/v2/news/aHR0cHM6Ly93d3cuam9oYW5zZW4uc2UvYmxvZy8yMDE4LzAyLzE0L25va2lhLTgtaGFyLWZhdHQtYW5kcm9pZC04LTEv"
    },
    {
      "id": "aHR0cHM6Ly93d3cubWFya2V0d2F0Y2guY29tL3N0b3J5L2NoYW5nZXMtaW4tbm9raWEtY29ycG9yYXRpb25zLW93bi1zaGFyZXMtMjAxOC0wMi0xNA",
      "href": "/api/v2/news/aHR0cHM6Ly93d3cubWFya2V0d2F0Y2guY29tL3N0b3J5L2NoYW5nZXMtaW4tbm9raWEtY29ycG9yYXRpb25zLW93bi1zaGFyZXMtMjAxOC0wMi0xNA"
    },
    {
      "id": "aHR0cDovL3d3dy5jaGluYWRhaWx5LmNvbS5jbi9hLzIwMTgwMi8xNC9XUzVhODNhYjU3YTMxMDZlN2RjYzEzY2I4NS5odG1s",
      "href": "/api/v2/news/aHR0cDovL3d3dy5jaGluYWRhaWx5LmNvbS5jbi9hLzIwMTgwMi8xNC9XUzVhODNhYjU3YTMxMDZlN2RjYzEzY2I4NS5odG1s"
    },
    {
      "id": "aHR0cHM6Ly93d3cudGhlc2NvdHRpc2hzdW4uY28udWsvdGVjaC8yMjI2Nzg0L2Jlc3QtaXBob25lLWdhbWVzLTIwMTgtdGhlLXVsdGltYXRlLWxpc3Qtb2YtaW9zLWdhbWVzLXlvdS1uZWVkLXRvLXBsYXktcmlnaHQtbm93Lw",
      "href": "/api/v2/news/aHR0cHM6Ly93d3cudGhlc2NvdHRpc2hzdW4uY28udWsvdGVjaC8yMjI2Nzg0L2Jlc3QtaXBob25lLWdhbWVzLTIwMTgtdGhlLXVsdGltYXRlLWxpc3Qtb2YtaW9zLWdhbWVzLXlvdS1uZWVkLXRvLXBsYXktcmlnaHQtbm93Lw"
    },
    {
      "id": "aHR0cDovL3d3dy5yZWNvcmRlcmUuZGsvMjAxOC8wMi9ub2tpYS1zb2xndGUtZmxlcmUtdGVsZWZvbmVyLWdvb2dsZS1odGMtb25lcGx1cy1zaWRzdGUta3ZhcnRhbC8",
      "href": "/api/v2/news/aHR0cDovL3d3dy5yZWNvcmRlcmUuZGsvMjAxOC8wMi9ub2tpYS1zb2xndGUtZmxlcmUtdGVsZWZvbmVyLWdvb2dsZS1odGMtb25lcGx1cy1zaWRzdGUta3ZhcnRhbC8"
    },
    {
      "id": "aHR0cHM6Ly93d3cuam9oYW5zZW4uc2UvYmxvZy8yMDE4LzAyLzEzL2FuYWx5dGlrZXItbm9raWEtc2FsamVyLW1lci1hbi1zb255LWdvb2dsZS1vY2gtb25lcGx1cy8",
      "href": "/api/v2/news/aHR0cHM6Ly93d3cuam9oYW5zZW4uc2UvYmxvZy8yMDE4LzAyLzEzL2FuYWx5dGlrZXItbm9raWEtc2FsamVyLW1lci1hbi1zb255LWdvb2dsZS1vY2gtb25lcGx1cy8"
    }
  ]
}

Article details

Given an article ID you can fetch more details with the endpoint

GET https://prod.mito.ai/api/v2/news/[[article-id]]

Example

Fetching more details about the article aHR0cDovL2NvbXB1dGVyc3dlZGVuLmlkZy5zZS8yLjI2ODMvMS42OTc4MzQvbm9raWEtbW9iaWxtYXJrbmFkZW4:

curl -X GET \
  https://prod.mito.ai/api/v2/news/aHR0cDovL2NvbXB1dGVyc3dlZGVuLmlkZy5zZS8yLjI2ODMvMS42OTc4MzQvbm9raWEtbW9iaWxtYXJrbmFkZW4 \
  -H 'Authorization: Bearer [[token]]'

Produces

{
    "title": "Nokias mobiltelefoner återuppstår - nu storsatsar telekomjätten på smartphones",
    "url": "https://www.va.se/nyheter/2018/02/13/nokias-mobiltelefoner-ateruppstar---nu-storsatsar-telekomjatten-pa-smartphones/",
    "publisher": "va.se",
    "published": "2018-02-14T12:13:29.000Z",
    "bodyText": "Some body text ...",
    "entities": [
    ],
    "id": "aHR0cHM6Ly93d3cudmEuc2UvbnloZXRlci8yMDE4LzAyLzEzL25va2lhcy1tb2JpbHRlbGVmb25lci1hdGVydXBwc3Rhci0tLW51LXN0b3JzYXRzYXItdGVsZWtvbWphdHRlbi1wYS1zbWFydHBob25lcy8",
    "href": "/api/v2/newsaHR0cHM6Ly93d3cudmEuc2UvbnloZXRlci8yMDE4LzAyLzEzL25va2lhcy1tb2JpbHRlbGVmb25lci1hdGVydXBwc3Rhci0tLW51LXN0b3JzYXRzYXItdGVsZWtvbWphdHRlbi1wYS1zbWFydHBob25lcy8"
}

This endpoint allows you to find trending entities.

GET https://prod.mito.ai/api/v2/entities/trending?entityProfile=[[profile]],[[profile]]...&contextEntities=[[entity-id]],[[entity-id]]...&categories=[[category]],[[category]]...
  • contextEntities is a list of entities that allows you to define a context for your entities, the results will then be entities which are trending wrt. the context-entities.
  • categories is a commas separated list of categories, just as on the news search
  • since is one of hour|day|week|month
  • entityProfile is a list of constrains on the following format entityProfile=<relation>:<entity-id> where
relation =
   | 'country'
   | 'country_of_citizenship'
   | 'developer'
   | 'founded_by'
   | 'headquarters_location'
   | 'instance_of'
   | 'location'
   | 'manufacturer'
   | 'occupation'
   | 'owned_by'
   | 'place_of_birth'
   | 'stock_exchange'

The output of all trending queries is on the following format

{
    "entities": [
        {
            "id": "Q1063818",
            "href": "/api/v2/entities/Q1063818",
            "trendingScore": 8.184439514574015,
            "normalizedMentionScore": 0.55,
            "normalizedMaxMentionScore": 0.83,
            "subsetMentionCount": 12,
            "subsetArticleCount": 3018,
            "supersetMentionCount": 14,
            "supersetArticleCount": 7251100
        },
        {
            "id": "Q13799874",
            "href": "/api/v2/entities/Q13799874",
            "trendingScore": 7.406171507766707,
            "normalizedMentionScore": 0.44,
            "normalizedMaxMentionScore": 0.88,
            "subsetMentionCount": 11,
            "subsetArticleCount": 3018,
            "supersetMentionCount": 13,
            "supersetArticleCount": 7251100
        },
        {
            "id": "Q24090301",
            "href": "/api/v2/entities/Q24090301",
            "trendingScore": 7.003232342142439,
            "normalizedMentionScore": 0.12,
            "normalizedMaxMentionScore": 0.71,
            "subsetMentionCount": 19,
            "subsetArticleCount": 3018,
            "supersetMentionCount": 41,
            "supersetArticleCount": 7251100
        }
    ]
}

where notable fields are

  • trendingScore: local trending score, primarily used for sorting
  • normalizedMentionScore: Normalized score for how many times this Entity was mentioned with respect to the sum of all mentioned Entitys
  • normalizedMaxMentionScore: Normalized score for how many times this Entity was mentioned with respect to the most mentioned Entity
  • subsetMentionCount: Number of mentions in period
  • subsetArticleCount: Number of articles containing Entity
Example queries

Fetch entities trending in the context of Nokia (Q1418):

curl -X GET \
  'https://prod.mito.ai/api/v2/entities/trending?contextEntities=Q1418' \
  -H 'Authorization: Bearer [[token]]'

Fetch trending entities with products developed by Apple (Q312):

curl -X GET \
  'https://prod.mito.ai/api/v2/entities/trending?entityProfile=developed_by:Q312' \
  -H 'Authorization: Bearer [[token]]'

Fetch trending entities for companies "located in Finland (Q33)" and "traded on the Frankfurt stock exchange (Q151139)" the past week you can do:

curl -X GET \
  'https://prod.mito.ai/api/v2/entities/trending?since=week&entityProfile=country:Q33,stock_exchange:Q151139' \
  -H 'Authorization: Bearer [[token]]'

Fetch trending humans together wit Apple (Q312):

curl -X GET \
  'https://prod.mito.ai/api/v2/entities/trending?contextEntities=Q312,entityProfile=instance_of:human' \
  -H 'Authorization: Bearer [[token]]'
Get access