Limited access

This feature is only available to root and super_admin_domain profiles. Ask your administrator for proper user role profiling.

What a trainer is

A trainer is the instruction run this training plan, on this data, with this configuration, now and maybe again later. Creating one is the only step a person takes to obtain a model: everything after the 201 — the export, the training job, the model version, the inference image, the inferencer and its rule — happens on its own and is described in How it works.

To Call
Schedule a training POST /ai/organization/{organizationId}/trainer
List the organization’s trainers GET /ai/organization/{organizationId}/trainer
Remove a trainer and its schedule DELETE /ai/organization/{organizationId}/trainer/{trainerId}

Creating a trainer

curl --request POST \
     --header "X-ApiKey: <your-api-key>" \
     --header "Content-Type: application/json" \
     --data @trainer.json \
     https://api.opengate.es/ai/organization/acme/trainer

A trainer that learns the sessions of one APN from a time series and retrains every quarter:

{
  "name": "radius-orange-trainer",
  "description": "Anomalous sessions on the corporate APN",
  "imageExecution": {
    "model": { "name": "radius-orange" },
    "trainingPlan": { "identifier": "6f1c2a4e-…" },
    "configuration": { "apn": "corporate.example.apn" },
    "timeout": 1800
  },
  "source": {
    "timeserie": {
      "id": "683fee1f2b447a7318586445",
      "filter": { "gte": { "at": "2026-06-01T00:00:00Z" } },
      "columns": [
        { "column": "apn",           "output": { "name": "APN" } },
        { "column": "state",         "output": { "name": "SessionState" } },
        { "column": "ggsnIp",        "output": { "name": "IP_GGSN" } },
        { "column": "deviceIp",      "output": { "name": "IP_Device" } },
        { "column": "sentBytes",     "output": { "name": "sbytes", "parquet": { "type": "LONG" } } },
        { "column": "receivedBytes", "output": { "name": "dbytes", "parquet": { "type": "LONG" } } },
        { "column": "sentPackets",   "output": { "name": "spkts",  "parquet": { "type": "LONG" } } },
        { "column": "receivedPackets", "output": { "name": "dpkts", "parquet": { "type": "LONG" } } },
        { "column": "duration",      "output": { "name": "dur",    "parquet": { "type": "LONG" } } }
      ],
      "timeout": 6000
    }
  },
  "schedule": {
    "expression": "0 0 0 15 */3 ? *",
    "isImmediateExecution": true
  },
  "createRule": true
}

The response is 201 Created with a Location header holding the trainer’s identifier.

Field by field

Field Required Meaning
name yes The trainer’s name, unique in the organization. Names the Kubernetes secret that carries your credentials to the job
description no Free text
imageExecution.model.name yes The model name: ^[a-z0-9][a-z0-9-]*$. Only one trainer per model name per organization. It becomes the name of the inferencer, the rule and the scheduler entry — see the naming table
imageExecution.trainingPlan.identifier yes The plan to run, from the catalogue. Must exist
imageExecution.configuration per plan Key–value pairs, one per entry in the plan’s configFields. Handed to the job as environment variables
imageExecution.timeout yes Seconds the training job may run before it is killed. The autoencoder and the image plan need far more than the forest
source yes Exactly one of path or timeserie, below
schedule no When and how often to run. Absent: once, about a minute from now
createRule no Whether the first training should create the plan’s rule. Default true

Read-only fields come back on GET: identifier, orgName, hasRetraining and schedule.schedulerId — the identifier of the entry the scheduler created, which is also the model name.

Data sources

A file in your file space

"source": { "path": "radius/sessions-2026-q2.parquet" }

path is relative to the root of your organization’s file space, where you upload it beforehand. Inside the job the file space is mounted at /data, so the plan reads /data/radius/sessions-2026-q2.parquet. A path may also be a folder, which is what the image plan expects.

A file source schedules a single image execution in the scheduler.

A time series

"source": {
  "timeserie": {
    "id": "<time series identifier>",
    "filter": { "…": "…" },
    "columns": [ { "column": "<yours>", "output": { "name": "<the plan's>", "parquet": { "type": "LONG" } } } ],
    "timeout": 6000
  }
}
Field Meaning
id The time series to export, from the organization’s time series
filter Optional. A time series filter restricting the rows, for example to a date range
columns Which of your columns feed the plan, and under what name. output.name must be one of the names the plan lists in columnData; output.parquet.type fixes the Parquet type when the default is not right
timeout Seconds to wait for the export. The scheduler waits five seconds more than this for the export’s callback

A time-series source schedules a pipeline: first the platform’s own Parquet export of that time series, writing <model>-<plan>-<time series>.parquet into your file space, then the training image with dataSourcePath pointing at it. Each retraining exports again, so the model always learns from current data.

Schedules

"schedule": { "expression": "0 0 0 15 */3 ? *", "isImmediateExecution": true }
  • expression — a cron expression. Standard five fields work; the scheduler also accepts a leading seconds field and a trailing year field, and ? in the day fields. 0 0 0 15 */3 ? * is 00:00:00 on the 15th of every third month. Time zone is UTC.
  • isImmediateExecution — also run now, without waiting for the first tick. The console sets it, so a new trainer always produces a first version straight away.

No schedule at all means a single execution about one minute after creation, and hasRetraining: false. An expression that pins one instant — every field numeric, including the year — is treated the same way.

What the platform does with your request

Knowing this helps when something does not appear where you expect it.

  1. Rejects the request if another trainer in the organization has the same name or the same model name, or if the plan is not in the catalogue.
  2. Creates a Kubernetes secret named <organization>-<trainer name>-env-secret holding your API key and the organization name. The training job uses it to register the inferencer, create the rule and report back — everything the job does, it does as you.
  3. Asks the scheduler for an image execution (file source) or a pipeline (time-series source) named after the model, running the plan’s image with these environment variables: your configuration entries, modelName, createRule, minDataToTrain from the plan, and dataSourcePath; plus the secret above and the platform’s shared AI settings. The scheduler waits for the job’s callback for timeout + 5 seconds.
  4. Stores the trainer and answers 201.

The trainer record is a schedule, not a status: to know whether a training ran and how it went, read the scheduler’s history for schedulerId = model name, or open See history in the console.

Listing trainers

curl --request GET \
     --header "X-ApiKey: <your-api-key>" \
     https://api.opengate.es/ai/organization/acme/trainer

Returns every trainer of the organization, with the read-only fields filled in. An organization with no trainers gets an empty list, not an error.

Removing a trainer

curl --request DELETE \
     --header "X-ApiKey: <your-api-key>" \
     https://api.opengate.es/ai/organization/acme/trainer/<trainerId>

Removes the schedule from the scheduler, the credentials secret and the trainer record, and answers 204. A training that is running is not interrupted — cancel it through the scheduler if you need to. The inferencer, its model versions and its rule are not touched: they are separate resources, removed through the Inferencers API. Deleting the trainer only means no further version will be trained.

Errors

Errors follow the platform’s usual shape, a list of code, message and context:

Situation Status
A trainer with that name, or that model name, already exists in the organization 400
The training plan identifier is not in the catalogue 400
The body fails the specification — a model name with uppercase letters, both path and timeserie, a missing timeout 400
The organization does not exist, or the trainer to delete does not 404

API specification