# Authentication

### Getting your API key <a href="#getting-your-api-key" id="getting-your-api-key"></a>

To use our APIs, you need to get an API key. You can get your API key from the API Keys section of your dashboard profile. This is the key associated with your user account. You can create or delete your API key at any time throw this section. When you change, delete or update your key, all previous API requests will stop working until you configure them to use the new key.

### Authenticating Request

Owlbot.ai for all its RESP APIs uses the standard "Authorization" header to authenticate requests with a Header token. You can authenticate requests by including your API key in the \`Authorization\` header in all your requests to the API.

For example, if your API token is "abcdefgh", you will have to put in your header the following code :

```javascript
"Authorization" : "abcdefgh"
```

#### Some Examples :

with cURL

```javascript
curl --request GET 'https://www.owlbot.ai/api/endpoint' \
--header 'Authorization: abcdefghf'
```

with Javascript Fetch

```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "abcdefghf");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://www.owlbot.ai/api/endpoint", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

with PHP cURL

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://www.owlbot.ai/api/endpoint',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 1,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: abcdefghj'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

with Python

```python
import requests

url = "https://www.owlbot.ai/api/endpoint"

payload={}
headers = {
  'Authorization': 'abcdefghj'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```


# API Erros

Learn about the errors you might encounter when authenticate

## Error Codes

We use standard HTTP status codes to indicate the success or failure of an API request. In general: Codes in the `200`range indicate success. Codes in the `400`range indicate an error that failed given the information provided (e.g., a token is false, missing or invalid.). Codes in the `500`range indicate an error with our servers (these are rare).

## No token (status 400)

Token is missing, please provide one.

## No verify (status 400)

Token is present but invalid because not correct or desactivated by Team Admin.


# Adding Sources

Sources are the data with whom you will train your bots. The amount of data you can use (in terms of words) depends on your account Plan.

## Data Types

For now, you can use data's coming from website (URLs) or documents (pdf, doc, docx...).

For PDFs, even scanned files can be used thanks to a solution called **tesseract**.

> Tesseract OCR is an open-source optical character recognition engine that is widely used for converting images of text into editable and searchable documents

## Web sources (links)

The endpoint to add Links as sources is : `https://www.owlbot.ai/api/weblinks/learn`

This endpoint only accept POST Request with the good authentication token as explained in the [dedidcated section](/).

Here is the parameters you have to provided :

| Property      | Type  | Description                                                                                  |
| ------------- | ----- | -------------------------------------------------------------------------------------------- |
| **links**     | array | Required. like `` `["link1", "link2"]` ``                                                    |
| **chatbotId** | uuid  | Required. It's defined the chatbot `UUID` of the chatbot you want to feed with thoses links. |

Remember that the method used to extract data from the links you provide is called scrapping.

As per the general rules of internet etiquette and legal standard, you are only allowed to scrape data from websites that you own or for which you have explicit written permission from the owner. The unauthorized scraping of data from a website that you do not own is considered a violation of copyright laws and the website's Terms of Service.

Web scraping may seem harmless, but it can have serious consequences. Unauthorized web scraping can lead to legal repercussions, including potential lawsuits for copyright infringement and privacy violations. Moreover, it can burden the web servers, leading to performance issues and even outages, which negatively impact all users.

## Adding File / Document

The endpoint to add Links as sources is : `https://www.owlbot.ai/api/upload`

We do support POSTing binary files directly to our storage space. You have to use `formData` to do so.

| Property    | Type   | Description                                                                                |
| ----------- | ------ | ------------------------------------------------------------------------------------------ |
| **file**    | binary | Required.  As to be 20 MegaBytes maximum.                                                  |
| **name**    | string | Required. the filename that identify this file.                                            |
| **type**    | string | Required. FOr now the supported file type are listed below                                 |
| **chatbot** | uuid   | Required. It's the chatbot `UUID` of chatbot you want to feed with thoses documents.       |
| **storage** | string | Required. as to be "private" because your uploaded files are not available for other users |

## Response

Response is a HTTP 200 with a JSON source object :&#x20;

```javascript
{ "uuid" : "dc94a8c3-7cab-4452-be1e-f2c029132216" }
```

Where **uuid** is the unique identifier of the uploaded file.

## Some examples :&#x20;

### In Javascript / Fetch

```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "abcdefghf");

var requestOptions = {
    method : "POST",
    headers : myHeaders,
    redirect : 'follow'
};

const fileForm = new FormData();
 fileForm .append("file", _file);
 fileForm .append("type", _file.type);
 fileForm .append("name", _file.name);
 fileForm .append("storage", "private");
   
 fetch("https://www.owlbot.ai/api/endpoint", fileForm ,requestOptions)
  .then(response => response.text())
  .then(result => console.log(result)
  .catch(error => console.log('error', error));
```

## Supported File Type

| Supported file | MIME Type                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Word File      | "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/wps-office.docx", "application/msword" |
| PDF File       | "application/pdf"                                                                                                              |
|                |                                                                                                                                |


# List Bots

This endpoint lists all bots for a specific user. It accepts a POST request with the right Token :

`https://www.owlbot.ai/api/login/checkToken`

### Response

Response is a JSON with 2 json :

```json
{
   "user":{
      "id":38,
      "created_at":"2023-06-04T19:24:59.695527+00:00",
      "Phone":null,
      "status":1,
      "Email":"John@doe.com",
      "uuid":"3c895cd5-1298-4f30-8417-XXXX",
      "plan_period_end":"1691658041",
      "actual_subscription":{
         "id":1,
         "price":1900,
         "doc_limit":null,
         "plan_Name":"Starter",
         "api_access":false,
         "link_limit":null,
         "white_label":false,
         "chatbot_limit":10,
         "word_db_limitation":"500000",
         "conversations_limit":null,
         "messages_limitation":"2000"
      },
      "user_avatar":null,
      "word_count":60667,
      "messages_count":426,
      "doc_count":11,
      "link_count":83,
      "affiliate":null
   },
   "chatbot":[
      {
         "id":91,
         "created_at":"2023-06-28T07:01:58.308677+00:00",
         "bot_title":"Chatbot1",
         "bot_footer":"Powered by Owlbot",
         "bot_user_icon":"https://owlbot.ai/assets/chatbot/user.png",
         "bot_assistant_icon":"https://hrfaciqawmkslnzhtrpe.supabase.co/storage/v1/object/public/public/3c895cd5-1298-4f30-8417-044e2633293c/5ae2b602-bca9-4623-bf51-bf50b055a0c5.png",
         "bot_primary_color":"#f702af",
         "uuid":"694f0f35-a082-41a8-85d5-XXX",
         "owner":"3c895cd5-1298-4f30-8417-XXXX",
         "visibility":1,
         "welcome_message":"Welcome Message",
         "bot_input_placeholder":"Type a message",
         "bot_footer_text":"Powered by Owlbot",
         "bot_secondary_color":"#6366F1",
         "PLACEHOLDER_IFRAME_POSITION_BOTTOM":"16px",
         "PLACEHOLDER_IFRAME_POSITION_RIGHT":"16px",
         "PLACEHOLDER_TOOLTIP_WELCOMME_MESSAGE":"Hello ! How can I help you ?",
         "PLACEHOLDER_TOOLTIP_MAIN_COLOR":"#8B5CF6",
         "PLACEHOLDER_TOOGLE_BUTTON_IMG_OPEN":"https://iframe.gptyourdata.ai/assets/logo-white.svg",
         "PLACEHOLDER_TOOGLE_BUTTON_IMG_CLOSE":"https://iframe.gptyourdata.ai/assets/x.svg",
         "js_script_name":null,
         "active":1,
         "word_count":2106,
         "messages_count":37,
         "bot_error_message":"Désolé, je ne comprends pas la question.",
         "doc_count":2,
         "link_count":0,
         "show_doc":0,
         "bot_agent_icon":"https://owlbot.ai/assets/chatbot/agent.png",
         "bot_agent_color":null,
         "secure":0,
         "is_working":0
      },
      {
         "id":84,
         "created_at":"2023-06-20T20:57:17.890246+00:00",
         "bot_title":"Pigment Chatbot",
         "bot_footer":"Powered by Owlbot",
         "bot_user_icon":"https://hrfaciqawmkslnzhtrpe.supabase.co/storage/v1/object/public/public/3c895cd5-1298-4f30-8417-044e2633293c/6ec380c7-6e06-414f-8db2-54074e544697.pdf",
         "bot_assistant_icon":"https://owlbot.ai/assets/chatbot/robot.png",
         "bot_primary_color":"#6366F1",
         "uuid":"20fefe38-1ee2-4d45-9ebe-2e9ec5a99136",
         "owner":"3c895cd5-1298-4f30-8417-044e2633293c",
         "visibility":1,
         "welcome_message":"Ask anything about Pigment",
         "bot_input_placeholder":"Type a message",
         "bot_footer_text":"Powered by Owlbot",
         "bot_secondary_color":"#8B5CF6",
         "PLACEHOLDER_IFRAME_POSITION_BOTTOM":"16px",
         "PLACEHOLDER_IFRAME_POSITION_RIGHT":"16px",
         "PLACEHOLDER_TOOLTIP_WELCOMME_MESSAGE":"Hello ! How can I help you ?",
         "PLACEHOLDER_TOOLTIP_MAIN_COLOR":"#6366F1",
         "PLACEHOLDER_TOOGLE_BUTTON_IMG_OPEN":"https://iframe.gptyourdata.ai/assets/logo-white.svg",
         "PLACEHOLDER_TOOGLE_BUTTON_IMG_CLOSE":"https://iframe.gptyourdata.ai/assets/x.svg",
         "js_script_name":null,
         "active":1,
         "word_count":6637,
         "messages_count":42,
         "bot_error_message":"Sorry, I didn't understand your question",
         "doc_count":2,
         "link_count":10,
         "show_doc":0,
         "bot_agent_icon":null,
         "bot_agent_color":null,
         "secure":0,
         "is_working":0
      },
   ]
}
```

The main parameter to update, delete or add data to your chatbot is your chatbot `UUID.`


# Chatbot Appearance and message

Update appearance of the chatbot with this endpoint :

`https://www.owlbot.ai/api/bot/[id]/update/`

Where \[id] is the chatbot *uuid* of the chatbot you want to update.

in terms of design, there is a lot of parameters you can play with :&#x20;

### For Chatbot Window

| Property                    | Type   | Description |
| --------------------------- | ------ | ----------- |
| **bot\_primary\_color**     | string | Optional.   |
| **bot\_secondary\_color**   | string | Optional.   |
| **bot\_user\_icon**         | string | Optional.   |
| **bot\_assistant\_icon**    | string | Optional.   |
| **bot\_title**              | string | Optional.   |
| **welcome\_message**        | string | Optional.   |
| **bot\_input\_placeholder** | string | Optional.   |
| **bot\_footer\_text**       | string | Optional.   |

### For Chatbot Bubble

The chatbot bubble is the always visible bubble (often placed at the bottom left of the screen).

If your using it, it can be useful to customise it to match the colours and design of your site.

Here is the parameters you can play with :

| Property                                | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| PLACEHOLDER\_IFRAME\_POSITION\_BOTTOM   | string | Optional.   |
| PLACEHOLDER\_IFRAME\_POSITION\_RIGHT    | string | Optional.   |
| PLACEHOLDER\_TOOLTIP\_WELCOMME\_MESSAGE | string | Optional.   |
| PLACEHOLDER\_TOOLTIP\_MAIN\_COLOR       | string | Optional.   |
| PLACEHOLDER\_TOOGLE\_BUTTON\_IMG\_OPEN  | string | Optional.   |
| PLACEHOLDER\_TOOGLE\_BUTTON\_IMG\_CLOSE | string | Optional.   |

## Some Example :

If you want to update the primary Color to Red Color. (`#FF0000`) and the bot Title to "test".

#### In Javascript / Fetch

dont forget to change \[id] by your chatbot `UUID`.

```javascript

let dataToUpdate = {
bot_primary_color : "#FF0000",
bot_title : "test"
}


fetch('https://www.owlbot.ai/api/bot/[id]/update/', {
  method: 'POST',
  headers: {
    'Authorization': 'abcdefghj',
  },
  body: JSON.stringify({
  dataToUpdate : dataToUpdate,
  botId : [id]
  })
}).then(res => res.json())
  .then(res => console.log(res));
```

## Response

response is a HTTP 200 with the newly updated chatbot property as JSON.&#x20;

<pre class="language-json"><code class="lang-json"> {
         "id":91,
         "created_at":"2023-06-28T07:01:58.308677+00:00",
         "bot_title":"test", <a data-footnote-ref href="#user-content-fn-1">&#x3C;== updated property</a>
         "bot_footer":"Powered by Owlbot",
         "bot_user_icon":"https://owlbot.ai/assets/chatbot/user.png",
         "bot_assistant_icon":"https://hrfaciqawmkslnzhtrpe.supabase.co/storage/v1/object/public/public/3c895cd5-1298-4f30-8417-044e2633293c/5ae2b602-bca9-4623-bf51-bf50b055a0c5.png",
         "bot_primary_color":"#FF0000",
         "uuid":[id],
         "owner":test user, 
         "visibility":1,
         "welcome_message":"Welcome Message",
         "bot_input_placeholder":"Type a message",
         "bot_footer_text":"Powered by Owlbot",
         "bot_secondary_color":"#6366F1",
         "PLACEHOLDER_IFRAME_POSITION_BOTTOM":"16px",
         "PLACEHOLDER_IFRAME_POSITION_RIGHT":"16px",
         "PLACEHOLDER_TOOLTIP_WELCOMME_MESSAGE":"Hello ! How can I help you ?",
         "PLACEHOLDER_TOOLTIP_MAIN_COLOR":"#8B5CF6",
         "PLACEHOLDER_TOOGLE_BUTTON_IMG_OPEN":"https://iframe.gptyourdata.ai/assets/logo-white.svg",
         "PLACEHOLDER_TOOGLE_BUTTON_IMG_CLOSE":"https://iframe.gptyourdata.ai/assets/x.svg",
         "js_script_name":null,
         "active":1,
         "word_count":2106,
         "messages_count":37,
         "bot_error_message":"Désolé, je ne comprends pas la question.",
         "doc_count":2,
         "link_count":0,
         "show_doc":0,
         "bot_agent_icon":"https://owlbot.ai/assets/chatbot/agent.png",
         "bot_agent_color":null,
         "secure":0,
         "is_working":0
      },
</code></pre>

[^1]:


# History Summary

Once you've deployed your bot to production, you can view the questions and answers that your users are asking.

### Endpoint

The endpoint to access this history summary is working with a GET request :

```url
https://www.owlbot.ai/api/chatbot/[id]/conversation
```

Remember to use the **API Token** in the headers as show in the [Authentication section](/).

The required parameters are :&#x20;

| Property  | Type | Description                                       |
| --------- | ---- | ------------------------------------------------- |
| **\[id]** | uuid | Chatbot `UUID` you want to have chat history from |

{% hint style="info" %}
remember to find your chatbot UUID after listing all your chatbot as shown in [previous section](/bot-customisation/list-bots).
{% endhint %}

## Example of Response

Response is a HTTP 200 Array with a list of JSON source object :&#x20;

{% code overflow="wrap" %}

```json
[
   {
      "id":629,
      "created_at":"2023-07-31T04:46:01.920296+00:00",
      "user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 16_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/114.0.5735.124 Mobile/15E148 Safari/604.1",
      "uuid":"e659d963-8412-4fce-b0ee-XXXXX",
      "visibility":1,
      "ip":"XX.136.66.XX",
      "geo":{
         "city":"Paris",
         "region":"cdg1",
         "country":"FR",
         "latitude":"XX.8323",
         "longitude":"XX.4075",
         "countryRegion":"XXX"
      },
      "chatbot_uuid":"694f0f35-a082-41a8-85d5-XXXX",
      "session_uuid":"d48a5374-e952-4c5f-8c0f-XXXXXXX",
      "messagenbr":5
   },
   {///},
   {///}

]
```

{% endcode %}

Here as the description of the details provided :&#x20;

| Property          | Type                          | Description                                                                                                                          |
| ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **id**            | number                        | unique identifier                                                                                                                    |
| **created\_at**   | timestamp                     | Timedate creation of the user session                                                                                                |
| **user\_agent**   | json                          | This typically includes the type and version of browser, operating system, and sometimes other information such as default language. |
| **uuid**          | Universally Unique Identifier | 128-bit number used to uniquely identify some object or entity on the internet.                                                      |
| **visibility**    | number (0, 1, 2)              | usefull to filter message you have seen, archive or delete                                                                           |
| **ip**            | IPV4 or IPV6 Address          | IP of the user who initiate the session                                                                                              |
| **geo**           | json                          | a JSON giving you information about the user location                                                                                |
| **chatbot\_uuid** | Universally Unique Identifier | UUID of corresponding chatbot                                                                                                        |
| **session\_uuid** | Universally Unique Identifier | uuid to identiy this session                                                                                                         |
| **messagenbr**    | number                        | Number of message the user sent (message from Ai chatbot are not count)                                                              |

{% hint style="info" %}
the usefull parameters is the "**session\_uuid**", you can use it to retreive all the message from a given session
{% endhint %}


# One Conversation Details

## Endpoint

The endpoint to access this history summary is working with a GET request :

```
https://www.owlbot.ai/api/chatbot/[id]/[session]
```

Remember to use the **API Token** in the headers as show in the [Authentication section](/).

The required parameters are :&#x20;

| Property       | Type | Description                                       |
| -------------- | ---- | ------------------------------------------------- |
| **\[id]**      | uuid | Chatbot `UUID` you want to have chat history from |
| **\[session]** | uuid | Session `UUID` you want to have the details from  |

## Example of Response

Response is a HTTP 200 Array with a list of JSON source object :&#x20;

```json5
{
   "messageArr":[
      {
         "id":2080,
         "created_at":"2023-07-29T13:21:25.036589+00:00",
         "chatbot_uuid":"694f0f35-a082-41a8-XXXX",
         "user":"user",
         "content":"Quels sont les valeurs de l'entreprise ?",
         "doc_vector_id":null,
         "user_session":"86f122cc-5709-4004-XXXX"
      },
      {
         "id":2081,
         "created_at":"2023-07-29T13:21:25.036589+00:00",
         "chatbot_uuid":"694f0f35-a082-41a8-XXXX",
         "user":"assistant",
         "content":"Les valeurs de l'entreprise sont la bienveillance et le travail.",
         "doc_vector_id":[
            3652,
            3654,
            3692,
            3664,
            3669
         ],
         "user_session":"86f122cc-5709-4004-a26f-117978b5cc3b"
      },
    {
    ////
    }
   ],
   "botPreferences":{
  ////
   }
}
```

Here as the description of the details provided :&#x20;

| Property          | Type          | Description                                                                                                                  |
| ----------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **id**            | unique number | unique id                                                                                                                    |
| **created\_at**   | timestamp     | Timedate creation of the user message                                                                                        |
| **chatbot\_uuid** | uuid          | chatbot UUID of the chatbot having the conversation                                                                          |
| **user**          | string        | can be **user, assistant or agent.** user is a real person chatting with the assistant (ie AI Chatbot). Agent is coming soon |
| **content**       | string        | user or chatbot message                                                                                                      |
| **doc\_vector**   | array         | array containing the ID of the sources used (weblink, doc) to answer the question                                            |
| **user\_session** | uuid          | session uuid of the given conversation                                                                                       |


# Stream Conversation (REST)

For now, the endpoint only accept POST request to chat with your bot. Websocket Request is coming soon.

## Endpoint

The endpoint to access this history summary is working with a POST request, this time the API Token is not necessary.

```url
https://www.owlbot.ai/api/chatbot/ask
```

## Parameters needed

This post request required at least 3 parameters :

| Property        | Type   | Description                                                                |
| --------------- | ------ | -------------------------------------------------------------------------- |
| **prompt**      | string | Required. The question ask to the chatbot (can not exceed 3000 characters) |
| **chatbotUuid** | uuid   | Required. The `UUID` of the chatbot your speaking with.                    |
| **session**     | uuid   | Required. The `UUID` of the session your in.                               |

The `session` parameter can be :&#x20;

* "anonymous" : in this case, you will not be able to manage user conversation history and to get sources from the answer provided by chatbot. Each question asked by users are treated separately and user can not see his own history when ending session.
* `uuid` :  in this case, you have to provide a *valid and unique UUID* to distinguish every users. In this case, you will be able to recover each user history and to get sources.

## Examples

### In Vanilla Javascript&#x20;

```javascript
 async function _sendMessage(message) {
   
    let post = { prompt: message, chatbotUuid: "3c895cd5-1298-4f30-8417-XXXX", 
    session: "d48a5374-e952-4c5f-8c0f-XXXXXXX"}
    
    const response = await fetch(`https://www.owlbot.ai/api/chatbot/ask`, {
      method: 'POST',
      body: JSON.stringify(post),
    })

    if (!response.ok) {
      throw new Error(response.statusText)
    }

    const data = response.body
    if (!data) {
      return
    }

    const reader = data.getReader()
    const decoder = new TextDecoder()
    let done = false

     let answer = "";

    while (!done) {
      const { value, done: doneReading } = await reader.read()
      done = doneReading
      const chunkValue = decoder.decode(value)
      answer  += chunkValue 
        return answer  
      })

    }

    if (done) {
      answer   = ''

      console.log('done')
    }
  }
```