Introduction

Welcome to the Thadeus API docs. You can use our API to access Thadeus.AI features. Please mind that you need to register an account to obtain valid API keys and secrets.

Thaudeus is a customly built AI API that combines the features provided by Google's DialogFlow and IBM's Watson in one tool. Currently the API is free to use with a cap at 10k calls per month.

If you need any more details, please do not hesitate to contact us on hi@thadeus.ai. Happy AI-ing.

Version history

Version 0.1 - 04.01.2020 - Init. Open the API to the public.
Version 0.1.1 - 06.07.2020 - Auth updates
Version 0.1.2 - 19.08.2020 - Copy updates
Version 0.2.0 - 10.10.2020 - Pre-defined entities introduces to predict endpoint
Version 0.3.0 - 20.11.2020 - Added thadeus npm library examples

Authorization

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

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });

Thadeus uses API keys to allow access to the API. You can register a new Thadeus API key at our developer portal.

Before making any requestes to Thadeus API, you should prepare an AUTHORIZATION_STRING. Create a JSON object like below and encode it into base64 format.


    {
        "key": API_KEY,
        "secret": API_SECRET
    }

You must replace the API_KEY & API_SECRET with your personal keys.

Thadeus API expects an AUTHORIZATION_STRING to be included in HEADERS in all API requests to the server. It should look as following:

Authorization: AUTHORIZATION_STRING

Workspaces

Get a specific Workspace

curl "https://api.thadeus.ai/workspaces/<ID>"
  -H "Authorization: ijajosg4as9jgasjoeoaisbvxzncvaseoiuohrienb..."

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
const result = await client.getWorkspace();

{
  "intents": [],
  "_id": "5dfba1a47a16b90011fb68d2",
  "name": "demo2",
  "createdAt": "2019-12-19T16:13:24.858Z",
  "updatedAt": "2020-03-20T18:39:39.836Z",
  "__v": 0,
  "owner": "5e4d69bc1c1dfe0011d09e35"
}

Use this endpoint to retrieve information about a specific workspace.

HTTP Request (with ID)

GET https://api.thadeus.ai/workspaces/<ID>

URL Parameters

Parameter	Description
ID	The ID of the workspace to retrieve

Errors

Error Code	Meaning
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
500	Internal Server Error -- We had a problem with our server. Try again later.

Update a specific Workspace

curl "https://api.thadeus.ai/workspaces/<ID>"
  -X PATCH
  -H "Authorization: ijajosg4as9jgasjoeoaisbvxzncvaseoiuohrienb..."
  -H "Content-Type: application/json"
  --data '{"name":"New workspace name" }'

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
await client.updateWorkspace(fieldsToUpdate);

{
  "intents": [],
  "_id": "5dfba1a47a16b90011fb68d2",
  "name": "New workspace name",
  "createdAt": "2019-12-19T16:13:24.858Z",
  "updatedAt": "2020-05-04T14:41:46.644Z",
  "__v": 0,
  "owner": "5e4d69bc1c1dfe0011d09e35"
}

Use this endpoint to update a specific workspace.

HTTP Request (with ID)

PATCH https://api.thadeus.ai/workspaces/<ID>

URL Parameters

Parameter	Description
ID	The ID of the workspace to patch

Body

Parameter	Description
name	New workspace name

Errors

Error Code	Meaning
400	Something went wrong when updating workspace.
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
500	Internal Server Error -- We had a problem with our server. Try again later.

Teach a specific Workspace

curl "https://api.thadeus.ai/workspaces/<ID>/
teach"
-X POST
  -H "Authorization: ijajosg4as9jgasjoeoaisbvxzncvaseoiuohrienb..."

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
await client.teachWorkspace(fieldToUpdate);

{
  "success": true
}

Use this endpoint to start teaching your Thadeus.AI model. Please note that teaching needs to be actioned everytime you finish updating intents and examples. There is NO automatic re-teaching.

HTTP Request (with ID)

POST https://api.thadeus.ai/workspaces/<ID>/teach

URL Parameters

Parameter	Description
ID	The ID of the workspace to teach

Errors

Error Code	Meaning
400	Something went wrong when teaching workspace.
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
500	Internal Server Error -- We had a problem with our server. Try again later.

Predict / Test intents

curl "https://api.thadeus.ai/workspaces/<ID>/predict/intents"
-X POST
  -H "Authorization: ijajosg4as9jgasjoeoaisbvxzncvaseoiuohrienb..."
  -H "Content-Type: application/json"
  --data '{"message":"I have a really bad headache" }'

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
const result = await client.predictIntents(message);

[
  {
    "intent": "headache",
    "probability": 0.8319551845634167
  },
  {
    "intent": "pills",
    "probability": 0.3319551845634167
  },
  {
    "intent": "sickness",
    "probability": 0.2219551845634167
  }
]

This endpoint returns predicted intents for a requested message.

HTTP Request (with ID)

POST https://api.thadeus.ai/workspaces/<ID>/predict/intents

URL Parameters

Parameter	Description
ID	The ID of the workspace to retrieve from

Body

Parameter	Description
message	Message to be checked against the model and its taught intents

Errors

Error Code	Meaning
400	Something went wrong when returning intents for provided message.
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
500	Internal Server Error -- We had a problem with our server. Try again later.

Predict pre-defined entities

curl "https://api.thadeus.ai/workspaces/<ID>/
predict/common_entities"
-X POST
  -H "Authorization: eyJrZXkiOiJlMGM0Mjc1Ny1jN2ZmLTQ3..."
  -H "Content-Type: application/json"
  --data '{"message":"Coca Cola costs 2$ at MacDonald restaurant" }'

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
const result = await client.predictCommonEntities(message);

[
    {
        "char_end": 9,
        "char_start": 0,
        "slot": "ORG",
        "text": "Coca Cola"
    },
    {
        "char_end": 18,
        "char_start": 16,
        "slot": "MONEY",
        "text": "2$"
    },
    {
        "char_end": 31,
        "char_start": 22,
        "slot": "ORG",
        "text": "MacDonald"
    }
]

This endpoint returns detected pre-defined entities for a requested message. List of all pre-defined entities can be found here.

HTTP Request (with ID)

POST https://api.thadeus.ai/workspaces/<ID>/predict/common_entities

URL Parameters

Parameter	Description
ID	The ID of the workspace to retrieve from

Body

Parameter	Description
message	Message to be checked against the pre-defined entities

Errors

Error Code	Meaning
400	Something went wrong when returning intents for provided message.
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
500	Internal Server Error -- We had a problem with our server. Try again later.

Intents

Get all intents for a specific workspace

curl "https://api.thadeus.ai/workspaces/<ID>/intents"
  -H "Authorization: eyJrZXkiOiJlMGM0Mjc1Ny1jN2ZmLTQ3..."

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
const result = await client.getIntents();

[
  {
    "examples": [
      {
        "text": "bye"
      },
      {
        "text": "cya"
      },
      {
        "text": "goodbye"
      },
      {
        "text": "see you later"
      },
      {
        "text": "ciao"
      }
    ],
    "_id": "5e750deb2d6a4500110610ac",
    "workspaceId": "5dfba1a47a16b90011fb68d2",
    "name": "goodbye",
    "slug": "goodbye",
    "createdAt": "2020-03-20T18:39:39.820Z",
    "updatedAt": "2020-03-20T18:39:39.820Z",
    "__v": 0
  },
  {
    "examples": [
      {
        "text": "hi"
      },
      {
        "text": "whatsup"
      },
      {
        "text": "hello"
      },
      {
        "text": "good morning"
      },
      {
        "text": "good evening"
      }
    ],
    "_id": "5e750deb2d6a4500110610ad",
    "workspaceId": "5dfba1a47a16b90011fb68d2",
    "name": "hello",
    "slug": "hello",
    "createdAt": "2020-03-20T18:39:39.833Z",
    "updatedAt": "2020-03-20T18:39:39.833Z",
    "__v": 0
  }
]

Use this endpoint to retrieve all intents for a specific workspace.

HTTP Request (with ID)

GET https://api.thadeus.ai/workspaces/<ID>/intents

URL Parameters

Parameter	Description
ID	The ID of the workspace to retrieve from

Errors

Error Code	Meaning
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
500	Internal Server Error -- We had a problem with our server. Try again later.

Add an intent

curl "https://api.thadeus.ai/workspaces/<ID>/intents"
  -X POST
  -H "Authorization: eyJrZXkiOiJlMGM0Mjc1Ny1jN2ZmLTQ3..."
  --data '{"name":"headache",    "examples": "["I have a really bad headache", "My head is going to explode", "Please help me, this pain is so bad", "HEEEELP", "Give me some meds for my headache"]"
   }'

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
const result = await client.createIntent({ name, examples });

{
  "examples": [
    "I have a really bad headache",
    "My head is going to explode",
    "Please help me, this pain is so bad",
    "HEEEELP",
    "Give me some meds for my headache"
  ],
  "_id": "5eb02ff82bf35e001748389d",
  "workspaceId": "5dfba1a47a16b90011fb68d2",
  "name": "headache",
  "slug": "headache",
  "createdAt": "2020-05-04T15:08:40.268Z",
  "updatedAt": "2020-05-04T15:08:40.268Z",
  "__v": 0
}

Use this endpoint to create a new intent.

HTTP Request (with ID)

POST https://api.thadeus.ai/workspaces/<ID>/intents

URL Parameters

Parameter	Description
ID	The ID of the workspace to post to

Body

Parameter	Description	type
name	New intent name	string
examples	Array of examples	string[] min.5

Errors

Error Code	Meaning
400	Something went wrong when creating intent.
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
500	Internal Server Error -- We had a problem with our server. Try again later.

Get a specific intent

curl "https://api.thadeus.ai/workspaces/<ID>/intents/<INTENT_ID>"
  -H "Authorization: eyJrZXkiOiJlMGM0Mjc1Ny1jN2ZmLTQ3..."

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
const result = await client.getIntent(intentId);

{
  "examples": [
    "I have a really bad headache",
    "My head is going to explode",
    "Please help me, pain is so bad",
    "HEEEELP",
    "Give me some pills for my headache"
  ],
  "_id": "5eb02ff82bf35e001748389d",
  "workspaceId": "5dfba1a47a16b90011fb68d2",
  "name": "headache",
  "slug": "headache",
  "createdAt": "2020-05-04T15:08:40.268Z",
  "updatedAt": "2020-05-04T15:08:40.268Z",
  "__v": 0
}

Use this endpoint to retrieve information about a specific intent.

HTTP Request (with ID)

GET https://api.thadeus.ai/workspaces/<ID>/intents/<INTENT_ID>

URL Parameters

Parameter	Description
ID	The ID of the workspace to retrieve from
INTENT_ID	The ID of the intent to retrieve

Errors

Error Code	Meaning
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
404	Intent not found.
500	Internal Server Error -- We had a problem with our server. Try again later.

Update a specific intent

curl "https://api.thadeus.ai/workspaces/<ID>/intents/<INTENT_ID>"
  -X PATCH
  -H "Authorization: eyJrZXkiOiJlMGM0Mjc1Ny1jN2ZmLTQ3..."
  -H "Content-Type: application/json"
  --data '{    "examples": "["I have a really bad headache", "My head is going to explode", "Please help me, pain is so bad", "HEEEELP", "I want to buy some pills"]"
 }'

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
const result = await client.updateIntent({ intentId, name, examples });

{
  "examples": [
    "I have a really bad headache",
    "My head is going to explode",
    "Please help me, pain is so bad",
    "HEEEELP",
    "I want to buy some pills"
  ],
  "_id": "5eb02ff82bf35e001748389d",
  "workspaceId": "5dfba1a47a16b90011fb68d2",
  "name": "headache",
  "slug": "headache",
  "createdAt": "2020-05-04T15:08:40.268Z",
  "updatedAt": "2020-05-04T15:24:19.168Z",
  "__v": 0
}

Use this endpoint to update a specific intent.

HTTP Request (with ID)

PATCH https://api.thadeus.ai/workspaces/<ID>/intents/<INTENT_ID>

URL Parameters

Parameter	Description
ID	The ID of the workspace that requires an intent update
INTENT_ID	The ID of the intent to update

Body

Parameter	Description	type
name	New intent name	string
examples	Array of examples	string[] min.5

Errors

Error Code	Meaning
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
404	Intent not found.
404	Something went wrong when updating intent.
500	Internal Server Error -- We had a problem with our server. Try again later.

Delete a specific intent

curl "https://api.thadeus.ai/workspaces/<ID>/intents/<INTENT_ID>"
  -X DELETE
  -H "Authorization: eyJrZXkiOiJlMGM0Mjc1Ny1jN2ZmLTQ3..."
 }'

const { Thadeus } = require('thadeus');
const client = new Thadeus({ apiSecret, apiKey, workspaceId });
const result = await client.deleteIntent(intentId);

{
  "examples": [
    "I have a really bad headache",
    "My head is going to explode",
    "Please help me, pain is so bad",
    "HEEEELP",
    "I want to buy some pills"
  ],
  "_id": "5eb02ff82bf35e001748389d",
  "workspaceId": "5dfba1a47a16b90011fb68d2",
  "name": "headache",
  "slug": "headache",
  "createdAt": "2020-05-04T15:08:40.268Z",
  "updatedAt": "2020-05-04T15:24:19.168Z",
  "__v": 0
}

Use this endpoint to delete a specific intent.

HTTP Request (with ID)

DELETE https://api.thadeus.ai/workspaces/<ID>/intents/<INTENT_ID>

URL Parameters

Parameter	Description
ID	The ID of the workspace to delete intent from
INTENT_ID	The ID of the intent to delete

Errors

Error Code	Meaning
401	Unauthorized -- Your API key is wrong.
404	Workspace not found.
404	Intent not found.
404	Something went wrong with deleting intent.
500	Internal Server Error -- We had a problem with our server. Try again later.

Pre-defined entities

The below list represents the current entities types Thadeus API detects and returns. There is no need to teach any of the models for the "basic" entities to work.

List of entities

Type Description

PERSON People, including fictional.

NORP Nationalities or religious or political groups.

FACss Buildings, airports, highways, bridges, etc.

ORG Companies, agencies, institutions, etc.

GPE Countries, cities, states.

LOC Non-GPE locations, mountain ranges, bodies of water.

PRODUCT Objects, vehicles, foods, etc. (Not services.)

EVENT Named hurricanes, battles, wars, sports events, etc.

WORK_OF_ART Titles of books, songs, etc.

LAW Named documents made into laws.

LANGUAGE Any named language.

DATE Absolute or relative dates or periods.

TIME Times smaller than a day.

PERCENT Percentage, including ”%“.

MONEY Monetary values, including unit.

QUANTITY Measurements, as of weight or distance.

ORDINAL “first”, “second”, etc.

CARDINAL Numerals that do not fall under another type.