ML Model APIs

Integrate Tellius ML Model APIs into external apps. Authenticate via OAuth2, submit prediction requests in JSON or file, and retrieve prediction results.

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.