Yookr prediction dashboard

This tutorial will guide you through setting up and managing jobs using the Prediction API.

## Introduction to Jobs

In the Prediction API, a Job represents a configured instance of a predictive model (called a Source) that runs for a specific organisation. It connects a specific version of a model with the necessary inputs it needs to run.

## Setting up a Job

Setting up a job involves several steps. You need to define the source, its version, and its input roles. Then you can create a job and bind its roles.

If you only need to set up a job, you can jump to step 4 below.

### Step 1: Create a Source

First, you need a source to create a job for. A source represents a runnable prediction model.

`POST /api/v1/sources`

This endpoint registers a new predictive model in the system.

Request Body:

- `name` (string, required): A unique, human-friendly name for the source (e.g., "mildew-predictor"). - `description` (string, optional): A brief explanation of what the model does. - `expectedintervalminutes` (integer, optional): A monitoring hint for how often the model is expected to run. - `retention_hours` (integer, optional): How long the predictions from this source should be stored.

Example Request:

bash

curl -X POST http://localhost:8000/api/v1/sources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{
  "name": "mildew-predictor",
  /* Lines 41-43 omitted */
  "retention_hours": 720
}'

### Step 2: Create a Source Version

Once a source is created, you need to define a version for it. This ensures that jobs are pinned to a specific, immutable version of a model, which is crucial for reproducibility.

`POST /api/v1/source_versions`

Request Body:

- `source_id` (UUID string, required): The ID of the source. - `version` (string, required): The version identifier (e.g., "v1.0.0"). - `description` (string, optional): Release notes. - `input_roles` (array, required): Definitions of inputs. - `output_roles` (array, required): Definitions of outputs.

Example Request:

bash

curl -X POST http://localhost:8000/api/v1/source_versions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{
  "source_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "version": "1.0.0",
  "input_roles": [
    { "role": "temperature", "input_kind": "sensor", "metric": "celsius", "required": true }
  ],
  "output_roles": [
    { "role": "prediction", "metric": "celsius", "unit": "°C", "required": true }
  ]
}'

### Step 3: Define Roles

Roles are now defined as part of the Source Version creation in Step 2.

### Step 4: Setup a Job (POST /api/v1/jobs/setup)

This API uses the setup endpoint. It registers the job, binds roles and creates any ancillary records.

Endpoint - POST /api/v1/jobs/setup - Authorization: Bearer <token> - Content-Type: application/json

JobSetupRequest — expected JSON shape:

- organisation_id (string, required) — UUID of the Organisation (Customer) - source (object, optional) — New source details if creating on the fly (or use source_id in job) - source_version (object, optional) — New version details if creating on the fly - job (object, required) - name (string) - active (boolean) - organisation_id (null) — leave null as it's passed at top level - role_bindings (array) — maps roles to input UUIDs

Example request (curl)

bash

curl -X POST http://localhost:8000/api/v1/jobs/setup \
  -H "Content-Type: application/json" \
  -d '{
  "organisation_id": "77777777-7777-7777-7777-777777777777",
  "source": { "id": "...", ... },
  "job": { "name": "Job A" },
  "role_bindings": [
    { "role": "temp", "input_id": "...", "input_type": "sensor" }
  ]
}'

## Managing Jobs with API Endpoints

### Get All Jobs

`GET /api/v1/jobs`

Retrieves a list of all jobs associated with the authenticated user's scope.

### Get a Specific Job

`GET /api/v1/jobs/{job_id}`

### Update a Job

`PUT /api/v1/jobs/{job_id}`

### Delete a Job

`DELETE /api/v1/jobs/{job_id}`

Jobs Tutorial