# ML Model APIs

The following guide can be used when integrating Tellius ML models into external applications or data pipelines. It includes:

* Authentication via OAuth2
* Submitting data for prediction (JSON or file)
* Retrieving and viewing prediction results

## **Authentication & Access Tokens**

To interact with ML APIs, you must first obtain an OAuth2 access token using your client credentials.

### Get access token

* **URL**: `/oauth/client_credentials_token`
* **Method**: `POST`
* **Content-Type**: `application/x-www-form-urlencoded`

**Request Parameters**

| Parameter       | Description                                | Required |
| --------------- | ------------------------------------------ | -------- |
| `client_id`     | Unique client ID created in Tellius        | ✅        |
| `client_secret` | Client secret associated with the above ID | ✅        |
| `grant_type`    | Must be set to `client_credentials`        | ✅        |

**Example Request** 

```bash
curl -X POST http://uat1.app.tellius.com/oauth/client_credentials_token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'client_id=your-client-id&client_secret=your-secret&grant_type=client_credentials'
```

**Example Response** 

```json
{
  "access_token": "your-access-token",
  "refresh_token": "your-refresh-token",
  "token_type": "bearer"
}
```

### Refresh access token

* **URL**: `/oauth/refresh_token`
* **Method**: `POST`
* **Content-Type**: `application/x-www-form-urlencoded`

**Request Parameters**

| Parameter       | Description                              | Required |
| --------------- | ---------------------------------------- | -------- |
| `refresh_token` | Token obtained from the initial response | ✅        |
| `secret`        | Client secret                            | ✅        |
| `grant_type`    | Must be `refresh_token`                  | ✅        |

**Example Request**

```bash
curl -X POST http://uat1.app.tellius.com/oauth/refresh_token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'refresh_token=your-refresh-token&secret=your-secret&grant_type=refresh_token'
```

**Example Response**

```json
{
  "access_token": "new-access-token",
  "refresh_token": "new-refresh-token",
  "token_type": "bearer"
}
```

## **Submitting Prediction Requests**

Once you have an `access_token`, you can call the ML prediction endpoints.

Predict API (JSON Data Payload)

* **URL**: `/proxy/ml/external/predict`
* **Method**: `POST`
* **Content-Type**: `application/json`
* **Authorization**: `Bearer {access_token}`

**Request Body Parameters**

| Parameter | Description                          | Required |
| --------- | ------------------------------------ | -------- |
| `modelId` | ID of the trained model in Tellius   | ✅        |
| `data`    | Array of JSON records for prediction | ✅        |

**Example Request**

```json
{
  "modelId": "externalMLApiTestModelId",
  "data": [
    {
      "age": 39,
      "workclass": "State-gov",
      "education_num": 13,
      "sex": "Male",
      "capital_gain": 2174,
      "capital_loss": 0
    },
    {
      "age": 42,
      "workclass": "Private",
      "education_num": 13,
      "sex": "Male",
      "capital_gain": 5178,
      "capital_loss": 0
    }
  ]
}
```

**Example Response**

```json
{
  "data": [
    {
      "salary_prediction": " >50K",
      "salary_probability": "0.5741"
    },
    {
      "salary_prediction": " >50K",
      "salary_probability": "0.8135"
    }
  ]
}
```

### Predict API (File Upload)

For real-time predictions using inline JSON data (ideal for smaller or interactive inputs).

* **URL**: `/proxy/ml/external/predict/file`
* **Method**: `POST`
* **Content-Type**: `multipart/form-data`
* **Authorization**: `Bearer {access_token}`

**Form Parameters**

| Parameter  | Type | Description                               | Required |
| ---------- | ---- | ----------------------------------------- | -------- |
| `metadata` | Text | JSON string with file type and `modelId`  | ✅        |
| `content`  | File | Data file (CSV or newline-delimited JSON) | ✅        |

**Metadata Structure**

```json
{
  "sourceType": "csv", // or "json"
  "modelId": "externalMLApiTestModelId",
  "options": {
    "header": "true",
    "delimiter": "," // optional
  }
}
```

{% hint style="warning" %}
The maximum file size is 250 MB.
{% endhint %}

**Example CURL**

```bash
curl -X POST http://uat1.app.tellius.com/proxy/ml/external/predict/file \
  -H 'Authorization: Bearer your-access-token' \
  -F 'metadata={"sourceType":"csv","modelId":"externalMLApiTestModelId","options":{"header":"true"}}' \
  -F content=@adult_salary_train.csv
```

**Example Response**

```json
{
  "predictedDataId": "externalPredict_9c09cc3c-f670-4839-9ec6-7b778a68"
}
```

## **Retrieving prediction results**

After prediction is complete (especially in file-based cases), these APIs let you download or view the results.

### Download prediction file

Streams the predicted output as a CSV file.

* **URL**: `/proxy/ml/external/predict/download`
* **Method**: `GET`
* **Authorization**: `Bearer {access_token}`
* **Content-Type**: `text/csv`

**URL Parameters**

| Parameter         | Description                              | Required |
| ----------------- | ---------------------------------------- | -------- |
| `predictedDataId` | ID returned from the file prediction API | ✅        |

**Example Request**

```bash
curl -X GET \
  'http://uat1.app.tellius.com/proxy/ml/external/predict/download?predictedDataId=your-id' \
  -H 'Authorization: Bearer your-access-token'
```

### View predicted data (Paginated)

Lets you inspect the predicted output row by row.

* **URL**: `/proxy/ml/external/predict/view`
* **Method**: `GET`
* **Authorization**: `Bearer {access_token}`

**URL Parameters**

| Parameter         | Description                              | Required | Default |
| ----------------- | ---------------------------------------- | -------- | ------- |
| `predictedDataId` | ID returned from the file prediction API | ✅        | -       |
| `nrows`           | Number of rows to return                 | ❌        | 200     |
| `rowoffset`       | Offset (for pagination)                  | ❌        | 0       |

**Example Request**

```bash
curl -X GET \
  'http://uat1.app.tellius.com/proxy/ml/external/predict/view?predictedDataId=your-id&nrows=200&rowoffset=0' \
  -H 'Authorization: Bearer your-access-token'
```

**Example Response**

```json
{
  "data": [
    {
      "age": "39.0",
      "capital_gain": "2174.0",
      "salary_prediction": " >50K",
      "salary_probability": "0.5741"
    },
    {
      "age": "42.0",
      "capital_gain": "5178.0",
      "salary_prediction": " >50K",
      "salary_probability": "0.8135"
    }
  ]
}
```

{% hint style="success" %}

* Classification models return prediction and probability.
* Regression models return prediction and residual.
* All APIs require a valid Bearer token in the `Authorization` header.
  {% endhint %}