> For the complete documentation index, see [llms.txt](https://obx-organization.gitbook.io/obx-r3-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://obx-organization.gitbook.io/obx-r3-manual/api-documentation.md).
# API Documentation
## Pre-Requisites
1. The ObX Historian Server has API License.
You can check if you have API license using ObX Admin Tools, from the Main page, click on the **Check License Info**
Click on the Check License info
This will open a **License Viewer** dialog in which you can see all list of features license to you ObX Historian Server. Make sure the API license is checked, it means you have API license.
2. Create an API User
Open ObX Admin Tools and from the left pane **Go to -> Users -> API**
Right-click on the **API -> Add User** , this will open a new window for creating a User in the ObX historian.
Add User Window
Fill in all the fields:
**Username** (required) - the username used by the 3rd party software to connect.
**Password** (required) - the password used by the 3rd party software to connect.
Confirm (required) - for password confirmation.
**Description** (optional)
**Grant -** Check this where you want to give this API user an access to specific datasource.
**Privilege** - Select what type of privilege this API user will have to specific datasource, for example READ - for read only, WRITE - for write only, ALL - for both read and write.
Sample configuration
Click on **CREATE** button to finish.
## API Configuration
{% hint style="info" %}
The API uses basic authentication, which uses a username and password created in the ObX Admin Tools.
{% endhint %}
### API Endpoint
```javascript
https://{IP Address}/db/
/** https for secured connections
*Take note that the certificate used is a self-signed certificate
*/
/*Example use when IP Address = 172.17.1.64
endpoint will be https://172.17.1.64/db/
*/
```
***
```javascript
http://{IP Address}/db
/**
* http for insecure connections
*/
```
**IP Address** - the IP address where the ObX WebUI component is installed. It could also be a valid FQDN e.g. [www.domain.com](http://www.domain.com)
### Query Paremeters
* **q :** The query (SQL like) to fetch data in the ObX Historian.
```javascript
SELECT mean("value") FROM "Tag1" WHERE time >=now()-5m GROUP BY time(1m) tz('Asia/Singapore');
// This query return the average/mean value of Tag1 for the last 5minutes sampled every 1 minute of data.
// The tz is your current timezone, this is necessary to avoid time region confusion.
```
```javascript
SELECT "value" FROM "Tag1" WHERE time >=now()-1m ORDER BY time DESC LIMIT 1;
// This query return the last or current value of the Tag.
```
```javascript
SELECT "value" FROM "Tag1" WHERE time >=now()-1m
/* This query returns all the values - raw value without sampling for the last 1 minute of data*/
```
```javascript
SELECT mean("value") FROM "Tag1" WHERE time >=1726651500000ms and time <=1726652100000ms GROUP BY time(1m) tz('Asia/Singapore)
/*This query return average/mean value of Tag1 between 2024-09-18 17:25:00 and 2024-09-18 17:35:00
Notice that the time accepted by the API is a milliseconds Unix epoch timestamp, so
you need to convert your time in ms. */
/*Using nodeJS or Javascript you can simply */
startTime = new Date('2024-09-18 17:25:00).getTime() // to get the Unix epoch timestamp
```
* **db:** The datasource name in the ObX Historian.
### Example Using Postman
Postman Settings
URL:
```url
https://localhost/db/
```
Query Parameters:
| Query Parameters | Value |
| ---------------- | --------------------------------------------------------------------------- |
| q | SELECT mean("value") FROM "Counter" WHERE time >=now()-1h GROUP BY time(1m) |
| db | Energy |
| | |
#### Authentication:
{% hint style="info" %}
Note that in Authentication, you have to use the Basic Auth and use the credentials created in the ObX Admin Tools.
{% endhint %}
#### Output Response:
```json
{
"results": [
{
"statement_id": 0,
"series": [
{
"name": "Counter",
"columns": [
"time",
"mean"
],
"values": [
[
"2024-09-18T09:25:00Z",
98.11111111111111
],
[
"2024-09-18T09:26:00Z",
29.5
],
[
"2024-09-18T09:27:00Z",
57.857142857142854
],
[
"2024-09-18T09:28:00Z",
48.5
],
[
"2024-09-18T09:29:00Z",
44.621848739495796
],
[
"2024-09-18T09:30:00Z",
67.5
],
[
"2024-09-18T09:31:00Z",
31.403361344537814
],
[
"2024-09-18T09:32:00Z",
59.49579831932773
],
[
"2024-09-18T09:33:00Z",
45.30252100840336
],
[
"2024-09-18T09:34:00Z",
46.583333333333336
],
[
"2024-09-18T09:35:00Z",
64.34453781512605
],
[
"2024-09-18T09:36:00Z",
33.6
],
[
"2024-09-18T09:37:00Z",
61.33613445378151
],
[
"2024-09-18T09:38:00Z",
42.5
],
[
"2024-09-18T09:39:00Z",
48.94117647058823
],
[
"2024-09-18T09:40:00Z",
61.5
],
[
"2024-09-18T09:41:00Z",
35.80672268907563
],
[
"2024-09-18T09:42:00Z",
63.666666666666664
],
[
"2024-09-18T09:43:00Z",
39.61344537815126
],
[
"2024-09-18T09:44:00Z",
50.68333333333333
],
[
"2024-09-18T09:45:00Z",
58.67226890756302
],
[
"2024-09-18T09:46:00Z",
37.7
],
[
"2024-09-18T09:47:00Z",
65.6218487394958
],
[
"2024-09-18T09:48:00Z",
36.5
],
[
"2024-09-18T09:49:00Z",
53.03361344537815
],
[
"2024-09-18T09:50:00Z",
55.5
],
[
"2024-09-18T09:51:00Z",
39.75
],
[
"2024-09-18T09:52:00Z",
67.94957983193277
],
[
"2024-09-18T09:53:00Z",
33.5
],
[
"2024-09-18T09:54:00Z",
54.529411764705884
],
[
"2024-09-18T09:55:00Z",
52.5
],
[
"2024-09-18T09:56:00Z",
42.04201680672269
],
[
"2024-09-18T09:57:00Z",
69.81666666666666
],
[
"2024-09-18T09:58:00Z",
30.3781512605042
],
[
"2024-09-18T09:59:00Z",
56.833333333333336
],
[
"2024-09-18T10:00:00Z",
49.35294117647059
],
[
"2024-09-18T10:01:00Z",
43.85
],
[
"2024-09-18T10:02:00Z",
68.5
],
[
"2024-09-18T10:03:00Z",
31.092436974789916
],
[
"2024-09-18T10:04:00Z",
58.88333333333333
],
[
"2024-09-18T10:05:00Z",
46.563025210084035
],
[
"2024-09-18T10:06:00Z",
45.9
],
[
"2024-09-18T10:07:00Z",
65.4873949579832
],
[
"2024-09-18T10:08:00Z",
32.916666666666664
],
[
"2024-09-18T10:09:00Z",
60.621848739495796
],
[
"2024-09-18T10:10:00Z",
43.5
],
[
"2024-09-18T10:11:00Z",
48.09243697478992
],
[
"2024-09-18T10:12:00Z",
62.5
],
[
"2024-09-18T10:13:00Z",
34.96666666666667
],
[
"2024-09-18T10:14:00Z",
62.94117647058823
],
[
"2024-09-18T10:15:00Z",
40.5
],
[
"2024-09-18T10:16:00Z",
49.99152542372882
],
[
"2024-09-18T10:17:00Z",
59.5
],
[
"2024-09-18T10:18:00Z",
36.97478991596638
],
[
"2024-09-18T10:19:00Z",
65.03333333333333
],
[
"2024-09-18T10:20:00Z",
37.5
],
[
"2024-09-18T10:21:00Z",
51.80672268907563
],
[
"2024-09-18T10:22:00Z",
56.5
],
[
"2024-09-18T10:23:00Z",
38.08474576271186
],
[
"2024-09-18T10:24:00Z",
67.08333333333333
],
[
"2024-09-18T10:25:00Z",
31.038095238095238
]
]
}
]
}
]
}
```
The output response is in **JSON** format.
{% hint style="info" %}
Notice the timestamp format is in ISO806.
{% endhint %}
You can also simply use a web browser and type in directly into URL
```
https://localhost/db?q=SELECT mean("value") FROM "Counter" WHERE time >=now()-1h GROUP BY time(1m)&db=Energy
```
{% hint style="warning" %}
If you are using a NodeJS or any framework to connect to the API, make sure the disable the **tls** verification, the API uses a self-signed-certificates, by default all frameworks verifies this and interrupts all connection with a self-signed-certificates.
{% endhint %}
### Example Using NodeJS
Using **axios** library (but you can use any libraries)
```javascript
const axios = require('axios');
const https = require('https');
// Disable TLS verification
const agent = new https.Agent({
rejectUnauthorized: false,
});
// Send the GET request
axios.get('https://localhost/db', {
params: {
q: 'select "value" from "Counter" Where time >=now()-1m',
db: 'Energy',
},
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic ' + Buffer.from('your-username:your-password').toString('base64'), // Replace with your credentials
},
httpsAgent: agent, // Set the custom HTTPS agent
})
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error('Error:', error);
});
```