REST API

POST /v1/uploads                 → upload plan
PUT  <signed-upload-url>         → upload data
POST /v1/predictions             → prediction job
GET  /v1/predictions/{jobId}     → job status
GET  /v1/predictions/{jobId}/result → predictions

The REST API uses a shared job lifecycle: upload data, submit work, poll its status, and read the result. A fit ends with a reusable context instead of a separate result.

In Python, use the Python SDK. It handles compression, uploads, polling, retries, and large results automatically.

Configure

Use your deployment origin as the base URL:

curl https://hollerith.monarcha.ai/v1/model-limits

Send your API key as a bearer token:

Authorization: Bearer hk_live_...

Every /v1 endpoint requires a key except GET /v1/model-limits. See Get your API key for issuing and rotating keys. Requests are limited to 60 per minute per user, shared across that user’s keys. A rate-limited response includes Retry-After. See Limits and quotas for every ceiling.

Choose a workflow

Task	Submit	Poll	Read
Predict rows	`POST /v1/predictions`	`GET /v1/predictions/{jobId}`	`GET /v1/predictions/{jobId}/result`
Fit a table	`POST /v1/fits`	`GET /v1/fits/{contextId}`	The ready context
Evaluate a fit	`POST /v1/evaluations`	`GET /v1/predictions/{jobId}`	`GET /v1/evaluations/{jobId}/result`
Forecast a series	`POST /v1/forecasts`	`GET /v1/predictions/{jobId}`	`GET /v1/predictions/{jobId}/result`

Each workflow starts by uploading its data through POST /v1/uploads.

Endpoints

Method	Path	Authentication	Returns
GET	`/v1/model-limits`	none	Published limits
POST	`/v1/warm`	key	Requested GPU size class
POST	`/v1/uploads`	key	Upload plan
POST	`/v1/fits`	key	A job and context
GET	`/v1/fits/{contextId}`	key	Fitted context
POST	`/v1/predictions`	key	Prediction job
GET	`/v1/predictions/{jobId}`	key	Job status
GET	`/v1/predictions/{jobId}/result`	key	Prediction or forecast result
POST	`/v1/evaluations`	key	Evaluation job
GET	`/v1/evaluations/{jobId}/result`	key	Evaluation result
POST	`/v1/forecasts`	key	Forecast job

Wire fields use camelCase and IDs are opaque strings. Submission endpoints return 200 with a job whose status is queued; subsequent progress is reported through the job status.

Upload data

Serialize the payload as JSON, gzip it, and hash the exact gzipped bytes you will upload:

import gzip
import hashlib
import json

payload = {
  "task": "classification",
  "targetColumn": "species",
  "featureColumns": ["sepal_length", "sepal_width", "petal_length", "petal_width"],
  "trainingFeatures": [
    {"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2},
    {"sepal_length": 7.0, "sepal_width": 3.2, "petal_length": 4.7, "petal_width": 1.4}
  ],
  "trainingTarget": ["setosa", "versicolor"],
  "rows": [
    {"sepal_length": 5.0, "sepal_width": 3.4, "petal_length": 1.5, "petal_width": 0.2}
  ]
}

body = gzip.compress(json.dumps(payload, separators=(",", ":")).encode(), mtime=0)
content_hash = "sha256:" + hashlib.sha256(body).hexdigest()

with open("payload.json.gz", "wb") as file:
    file.write(body)

Request an upload plan. contentHash accepts sha256:<hex> or bare hex. bytes is the exact gzipped length.

curl -X POST https://hollerith.monarcha.ai/v1/uploads \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"contentHash":"sha256:c723441a...","bytes":233,"rows":3,"columns":4}'

{
  "kind": "single",
  "key": "<object-key>",
  "url": "<signed-upload-url>"
}

Upload the same gzipped bytes. The signed URL does not use your API key and expires after 1 hour.

curl -X PUT --data-binary @payload.json.gz "<signed-upload-url>"

rows and columns are optional, but must be sent together. They let Hollerith begin warming the appropriate worker while the upload completes. You can also send the same values directly to POST /v1/warm before the payload is ready.

Multipart uploads

Payloads over 64 MiB return kind: "multipart" with uploadId, partSize, partUrls, and completeUrl.Upload each part in order, retain its ETag, then POST this manifest to completeUrl with Content-Type: application/xml:

<CompleteMultipartUpload>
  <Part><PartNumber>1</PartNumber><ETag>"a1b2c3..."</ETag></Part>
  <Part><PartNumber>2</PartNumber><ETag>"d4e5f6..."</ETag></Part>
</CompleteMultipartUpload>

Part numbers start at 1 and ETags retain their quotes. Payloads above the upload limit return payload_too_large (413).

Predict rows

Submit the upload reference and row counts:

curl -X POST https://hollerith.monarcha.ai/v1/predictions \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "objectKey": "<object-key>",
    "contentHash": "sha256:c723441a...",
    "task": "classification",
    "targetColumn": "species",
    "featureColumns": ["sepal_length","sepal_width","petal_length","petal_width"],
    "trainRowCount": 2,
    "outputRowCount": 1,
    "classCount": 2,
    "idempotencyKey": "predict:iris-v1:2026-08-07"
  }'

Field	Required	What it does
`objectKey`, `contentHash`	yes	Identifies the uploaded payload. The hash must match its bytes.
`task`	yes	Sets `"classification"` or `"regression"`.
`targetColumn`	yes	Names the target column in the payload.
`featureColumns`	yes	Lists feature columns in their model input order.
`trainRowCount`, `outputRowCount`	yes	Declares the uploaded row counts.
`classCount`	classification only	Checks the class limit before the job starts.
`idempotencyKey`	no	Prevents duplicate jobs when a request is retried.

See Limits and quotas for row, column, cell, and class limits.

Poll and read results

Poll the job status endpoint until status is succeeded or failed:

curl https://hollerith.monarcha.ai/v1/predictions/jd7f2m9k4x1c8b3n5q0v6t2w \
  -H "Authorization: Bearer hk_live_..."

{
  "id": "jd7f2m9k4x1c8b3n5q0v6t2w",
  "status": "succeeded",
  "kind": "predict",
  "trainRows": 2,
  "outputRows": 1,
  "engineVersion": "eng_4b1c90fa72d5e836",
  "durationMs": 2841,
  "error": null
}

A failed job includes its typed error in error. Request /result only after the job succeeds:

curl https://hollerith.monarcha.ai/v1/predictions/jd7f2m9k4x1c8b3n5q0v6t2w/result \
  -H "Authorization: Bearer hk_live_..."

{
  "predictions": ["setosa"],
  "classes": ["setosa", "versicolor"],
  "probabilities": [[0.981, 0.019]],
  "quantiles": null,
  "quantileLevels": null
}

predictions follows the order of the uploaded rows. classes defines the probability column order, and quantiles follows quantileLevels. Results remain available for 1 hour. For a result over 512 KiB, the response contains resultUrl and resultContentHash instead of inline arrays. Download the signed URL within 5 minutes, gunzip its contents, and verify its SHA-256 hash.

Reuse a fitted context

POST /v1/fits accepts the prediction fields without outputRowCount. It also accepts forceRefit; set it to true to skip reuse of an identical active fit. The response returns a job, context, and reused flag:

{
  "job": {
    "id": "<job-id>",
    "status": "queued",
    "kind": "fit"
  },
  "context": {
    "id": "<context-id>",
    "status": "creating",
    "expiresAt": "<timestamp>"
  },
  "reused": false
}

Poll GET /v1/fits/{contextId} until the context is ready. Its status is one of creating, ready, failed, expired, or deleted. To predict with the context, upload only the rows to score. Set kind to "contextPrediction" in the uploaded payload, then submit:

Field	Required	What it does
`fittedContextId`	yes	Identifies the ready context.
`objectKey`, `contentHash`	yes	Identifies the uploaded prediction rows.
`outputRowCount`	yes	Declares the number of prediction rows.
`idempotencyKey`	no	Prevents duplicate jobs when a request is retried.

Contexts expire after 30 days of inactivity and after 90 days at the latest. Successful predictions extend the inactivity deadline.

Evaluate a fit

POST /v1/evaluations accepts the fit fields with rowCount instead of outputRowCount. Poll the shared job status endpoint, then read the evaluation result:

curl https://hollerith.monarcha.ai/v1/evaluations/<job-id>/result \
  -H "Authorization: Bearer hk_live_..."

{
  "metric": "accuracy",
  "value": 0.9733,
  "method": "kfold",
  "folds": 5,
  "rows": 150
}

method is selected by row count. folds is omitted for a holdout evaluation. See Evaluating accuracy for interpreting the result.

Forecast a time series

POST /v1/forecasts accepts objectKey, contentHash, covariateColumns, contextRowCount, outputRowCount, and an optional idempotencyKey. Set kind to "forecast" in the uploaded payload. Poll the shared job status endpoint and read the result from GET /v1/predictions/{jobId}/result. Each prediction contains item_id, timestamp, mean, and one field per quantile level. GET /v1/forecasts/{id} returns 404. Poll forecasts through the shared prediction-job route.

outputRowCount equals the number of future rows, or the horizon multiplied by the number of distinct item_id values.
covariateColumns lists the covariate keys in the payload.

Forecasting is Beta and does not use a fitted context.

Payload shapes

Uploaded data is gzipped JSON. Required keys depend on the job:

Job	Payload keys
Fit	`task`, `targetColumn`, `featureColumns`, `trainingFeatures`, `trainingTarget`, `rows: []`
Inline prediction	Fit keys, `rows`, and optional `quantiles`
Context prediction	`kind: "contextPrediction"`, `rows`, and optional `quantiles`
Evaluation	`task`, `targetColumn`, `featureColumns`, `trainingFeatures`, `trainingTarget`, `rows: []`
Forecast	`kind: "forecast"`, `context`, `future`, `predictionLength`, `quantiles`

trainingFeatures, rows, context, and future are arrays of objects keyed by column name. trainingTarget is a flat array aligned with trainingFeatures. A forecast payload includes all four forecast keys and sets exactly one of future and predictionLength.

Use idempotency keys

Every job submission accepts an optional idempotencyKey, such as predict:churn-v3:batch-0912. Reusing a key with the same payload returns the original job. Reusing it with a different payload returns idempotency_conflict (409). Send an idempotency key with every submission. Without one, retrying after a network timeout can create a second billed job.

Handle errors

Typed errors include code, category, problem, cause, fix, docUrl, retryable, and requestId. Branch on code. See Errors for every code, HTTP status, and retry rule. Invalid JSON returns 400 {"error":"invalid_json"}. A request that matches no accepted shape returns 400 {"error":"invalid_request"}.

What the SDK handles

quantiles, predictionLength, and future belong in the uploaded payload rather than the submission body. REST integrations can use all three. The Python SDK builds, compresses, hashes, and uploads payloads. It also handles multipart uploads, status polling, cold-worker retries, and large-result downloads.

Python SDK — use Hollerith from Python
Get your API key — issue and rotate keys
Errors — handle every error code
Limits and quotas — check every model and account limit

Get started

Guides

Reference

Account

Help

Configure

Choose a workflow

Endpoints

Upload data

Predict rows

Poll and read results

Reuse a fitted context

Evaluate a fit

Forecast a time series

Payload shapes

Use idempotency keys

Handle errors

What the SDK handles

Next

​Configure

​Choose a workflow

​Endpoints

​Upload data

​Predict rows

​Poll and read results

​Reuse a fitted context

​Evaluate a fit

​Forecast a time series

​Payload shapes

​Use idempotency keys

​Handle errors

​What the SDK handles

​Next

Configure

Choose a workflow

Endpoints

Upload data

Predict rows

Poll and read results

Reuse a fitted context

Evaluate a fit

Forecast a time series

Payload shapes

Use idempotency keys

Handle errors

What the SDK handles

Next