Prediction API

Train and publish a model in Model Builder first. Prediction requests use https://api.onyx.dev, the database API origin. Authenticate with x-onyx-key and x-onyx-secret, or a supported bearer token in Authorization. Database read access is sufficient to call prediction endpoints.

Keep API key secrets in your server environment. The examples use the same ONYX_DATABASE_ID, ONYX_DATABASE_API_KEY, and ONYX_DATABASE_API_SECRET variables as the client quickstarts. Replace churn-model with your published model key and match the example fields to its feature mappings.

Copy the published model key from Model Builder, or list the published models available in the selected database's organization. Use a returned record's id as publishedModelId; modelId identifies the source definition. URL-encode database and model IDs when constructing paths.

curl --fail-with-body "https://api.onyx.dev/data/$ONYX_DATABASE_ID/model-builder/published-model" \
  -H "x-onyx-key: $ONYX_DATABASE_API_KEY" \
  -H "x-onyx-secret: $ONYX_DATABASE_API_SECRET"

The response is a list envelope with records and meta. Each model includes its id, name, version, modelId, trainingRunId, and mapping metadata.

Send a JSON body with an inputs property containing one object or a non-empty array of objects. The TypeScript helper accepts those objects directly and adds the inputs wrapper for you.

curl --fail-with-body -X POST \
  "https://api.onyx.dev/data/$ONYX_DATABASE_ID/model-builder/published-model/churn-model/predict" \
  -H "Content-Type: application/json" \
  -H "x-onyx-key: $ONYX_DATABASE_API_KEY" \
  -H "x-onyx-secret: $ONYX_DATABASE_API_SECRET" \
  --data '{"inputs":[{"accountAgeDays":420,"usageScore":0.87},{"accountAgeDays":90,"usageScore":0.42}]}'

These example rows assume feature paths accountAgeDays and usageScore. If your model maps row.accountAgeDays, send a nested row object. The published model applies its saved feature mappings and transforms to these values.

For a sequence model, supply ordered rows with enough context for its configured window. Windowing can reduce the number of predictions. Match results to the returned inputsor records, rather than assuming every submitted row produces an output.

Send scriptId and optional scriptParameters to /predict/script. Parameters are a map of strings to strings, including values representing numbers or booleans. The script must already be saved in the selected database.

curl --fail-with-body -X POST \
  "https://api.onyx.dev/data/$ONYX_DATABASE_ID/model-builder/published-model/churn-model/predict/script" \
  -H "Content-Type: application/json" \
  -H "x-onyx-key: $ONYX_DATABASE_API_KEY" \
  -H "x-onyx-secret: $ONYX_DATABASE_API_SECRET" \
  --data '{"scriptId":"score-active-customers","scriptParameters":{"segment":"enterprise","limit":"50"}}'

Save score-active-customers with the parameters used above, or substitute your own script ID and parameters. It should return an object, an array of objects, or an object containing a row array under records, items, results, or data. Empty results cannot be used for prediction. Rows must match the published feature mappings.

Script execution forwards your credentials. Any operations performed by the script remain subject to those credentials' permissions. Use a script that reads and prepares the input rows.

Both prediction endpoints return HTTP 200 with the same response shape. This illustrative single-row response assumes an output mapping named churnRisk:

{
  "publishedModelId": "churn-model",
  "modelId": "model-abc",
  "inputCount": 1,
  "inputs": [{ "accountAgeDays": 420, "usageScore": 0.87 }],
  "predictions": [{ "churnRisk": 0.1875 }],
  "records": [{
    "input": { "accountAgeDays": 420, "usageScore": 0.87 },
    "prediction": { "churnRisk": 0.1875 }
  }],
  "rawPredictions": [[0.1875]],
  "scriptId": null,
  "scriptParameters": {}
}

Use decoded predictions for application output and rawPredictions to inspect the model's numeric output. Field names and shapes depend on the published mappings. For script predictions, the response also identifies the script and parameters used.

TypeScript exposes db.predict(publishedModelId, inputs) and db.predictFromScript(publishedModelId, scriptId, scriptParameters?). These use the database client's base URL and credentials.

import { onyx } from "@onyx.dev/onyx-database";

// Uses ONYX_DATABASE_ID, ONYX_DATABASE_API_KEY, and
// ONYX_DATABASE_API_SECRET from your server environment.
const db = onyx.init();

const single = await db.predict("churn-model", {
  accountAgeDays: 420,
  usageScore: 0.87,
});

const batch = await db.predict("churn-model", [
  { accountAgeDays: 420, usageScore: 0.87 },
  { accountAgeDays: 90, usageScore: 0.42 },
]);

console.log(single.predictions);
console.log(batch.inputCount, batch.predictions);
console.log(batch.inputs, batch.rawPredictions);

const result = await db.predictFromScript(
  "churn-model",
  "score-active-customers",
  { segment: "enterprise", limit: "50" },
);

// Match predictions to the returned inputs, including for sequence models.
for (let index = 0; index < result.inputCount; index++) {
  console.log(result.inputs[index], result.predictions[index]);
}
console.log(result.scriptId, result.scriptParameters);

The Python, Go, and Kotlin examples use standard HTTP clients to call the same REST endpoints. They are standalone request examples, not methods on those SDKs. Each example demonstrates both raw input and saved script predictions.

• Authentication or access failure: verify the database ID, credentials, and database read access.
• Model not found: use the published model key from the listing or Model Builder and verify that it belongs to the selected organization.
• Invalid inputs: check object shape, nested paths, feature types, and sequence context against the published snapshot.
• Script failure: check the saved script ID, string parameter values, execution permissions, and returned row objects. Empty script results are rejected.
• Unexpected output: inspect the returned inputs, decoded predictions, raw outputs, and the published output mappings.
• Service failure: check the HTTP status and error body. If inference is unavailable, retry after the service recovers.

Explicit validation errors, such as a blank scriptId, return HTTP 400. Model service errors preserve their HTTP status. Script execution and unexpected server failures can return HTTP 500; inspect the failing script and inputs before retrying.