# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.tellius.com/tellius-6.3/api/ml-model-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.