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

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

{
  "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

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

{
  "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

{
  "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

{
  "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

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

The maximum file size is 250 MB.

Example CURL

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

{
  "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

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

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

{
  "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"
    }
  ]
}

• Classification models return prediction and probability.

• Regression models return prediction and residual.

• All APIs require a valid Bearer token in the Authorization header.