Yookr Logo

API Reference

Detailed technical reference for all endpoints in the Prediction System.

API Reference

This document provides detailed information about the endpoints available in the Prediction API.

Table of Contents

Core Endpoints

Predictions

Used by workers to submit new data and by dashboards to delete erroneous entries.

POST /api/v1/predictions

Submit a batch of prediction values for one or more targets.

  • Description: Create new predictions in batch.
  • Auth: Required (Bearer Token).
  • Body Structure:
json
{
  "job_id": "UUID",
  "service_id": "UUID",
  "run_at": "ISO8601 (UTC)", // Optional
  "predictions": [
    {
      "stage": "forecast | actual", // Optional, defaults to 'forecast'
      "datetime_measure": "ISO8601",
      "targets": [
        {
          "target_id": "UUID",
          "value_num": 12.3, // Optional
          "value_text": "optional description", // Optional
          "confidence": 0.95, // Optional
          "meta": { "extra": "data" } // Optional
        }
      ]
    }
  ]
}

DELETE /api/v1/predictions/{id}

  • Description: Permanently delete a prediction record by its UUID.
  • Path Parameters: id (UUID) - The unique identifier of the prediction record.
  • Example: DELETE /api/v1/predictions/a1b2c3d4-e5f6-7890-abcd-ef1234567890

POST /api/v1/predictions/cleanup

  • Description: Trigger a background cleanup of stale prediction data based on retention policies.
  • Auth: Required (System Admin privileges).

Jobs Dashboard

Used to manage the life cycle of background workloads.

GET /api/v1/jobs

  • Description: List all jobs across all organisations. Requires system-level permissions.

GET /api/v1/jobs/customer/{organisation_id}

  • Description: List all jobs belonging to a specific organisation.
  • Path Parameters: organisation_id (UUID).
  • Example: GET /api/v1/jobs/customer/f47ac10b-58cc-4372-a567-0e02b2c3d479

GET /api/v1/jobs/{id}/setup-payload

  • Description: Reconstructs the full setup request payload for an existing job.
  • Usage: Useful for "cloning" a job or auditing the exact configuration used during its creation.
  • Example: GET /api/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/setup-payload

POST /api/v1/jobs/setup

  • Description: Comprehensive "Golden Path" endpoint. Creates Source, Version, and Job in one atomic transaction.
  • Request Body:
json
{
  "organisation_id": "UUID",
  "source": { // Optional if using existing source_id in job
    "id": "UUID", // Optional
    "name": "Model Name", // Required if source is provided
    "description": "Optional model description", // Optional
    "expected_interval_minutes": 60, // Optional
    "retention_hours": 720 // Optional
  },
  "source_version": { // Optional if using existing version_id in job
    "id": "UUID", // Optional
    "version": "1.0.0", // Required if source_version is provided
    "description": "Release notes" // Optional
  },
  "input_roles": [ // Optional (if version exists, roles are fetched from DB)
    { 
      "role": "temp", // Required if input_roles is provided
      "input_kind": "sensor", // Optional, defaults to "sensor"
      "metric": "celsius", // Required if input_roles is provided
      "required": true // Optional, defaults to true
    }
  ],
  "output_roles": [ // Optional (if version exists, roles are fetched from DB)
    { 
      "role": "prediction", // Required if output_roles is provided
      "metric": "celsius", // Required if output_roles is provided
      "unit": "°C", // Optional
      "required": true // Optional, defaults to true
    }
  ],
  "job": {
    "id": "UUID", // Optional
    "name": "My Prediction Job",
    "notes": "Runs every hour", // Optional
    "active": true, // Optional, defaults to true
    "organisation_id": "UUID", // Optional
    "source_id": "UUID", // Optional, required if 'source' object is omitted
    "version_id": "UUID" // Optional, required if 'source_version' object is omitted
  },
  "role_bindings": [ // Optional mathematically, but usually required to satisfy required input_roles
    { 
      "role": "temp",
      "input_id": "hardware-uuid",
      "input_type": "sensor", // Optional, defaults to "sensor"
      "aggregation_method": "mean" // Optional, defaults to "none"
    }
  ],
  "job_targets": [ // Optional mathematically, but usually required to satisfy required output_roles
    { 
      "output_role": "prediction",
      "tags": [{ "category": "Type", "name": "Forecast" }] // Optional, defaults to []
    }
  ]
}

PUT /api/v1/jobs/{id}

  • Description: Update metadata like name or notes.
  • Request Body:
json
{
  "name": "Updated Name",
  "notes": "Updated notes", // Optional
  "active": true // Optional, defaults to true
}

PATCH /api/v1/jobs/{id}/active

  • Description: Lightweight toggle to start or stop a job.
  • Request Body: true | false.

DELETE /api/v1/jobs/{id}

  • Description: Deletes a job and its associated bindings.
  • Constraint: Active jobs cannot be deleted. Deactivate the job first.

Authentication

POST /serviceLogin

  • Description: Machine-to-machine login for workers. Returns an access token.
  • Body:
json
{
  "service_id": "UUID (Source Version ID)",
  "password": "GENERATED_PASSWORD"
}

POST /login

  • Description: Standard user login for the dashboard.
  • Body:
json
{
  "email": "user@example.com",
  "password": "password"
}

Resources

Sources

Management of prediction sources (e.g., specific models or external providers).

GET /api/v1/sources

  • Description: List all registered sources.
  • Example: GET /api/v1/sources

GET /api/v1/sources/{id}

  • Description: Retrieve details for a specific source.
  • Path Parameters: id (UUID).
  • Example: GET /api/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890

GET /api/v1/sources/{id}/status

  • Description: Get the last activity timestamp for a source.
  • Example: GET /api/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status

GET /api/v1/sources/jobs/{source_id}

  • Description: List all jobs associated with a specific source.
  • Example: GET /api/v1/sources/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Source Versions

Specific releases or iterations of a prediction source.

GET /api/v1/source_versions/{id}

  • Description: Get details for a specific source version.
  • Path Parameters: id (UUID).
  • Example: GET /api/v1/source_versions/b2c3d4e5-f6a7-8901-bcde-f1234567890a

GET /api/v1/source_versions/source/{source_id}

  • Description: List all versions belonging to a specific source.
  • Example: GET /api/v1/source_versions/source/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Targets

Virtual Sensors that store prediction results.

GET /api/v1/targets/{target_id}/predictions

Fetch historical time-series for a target.

  • Query Parameters:
  • gt (optional): Filter by datetime strictly greater than (ISO8601).
  • gte (optional): Filter by datetime greater than or equal to (ISO8601).
  • lt (optional): Filter by datetime strictly less than (ISO8601).
  • lte (optional): Filter by datetime less than or equal to (ISO8601).
  • limit (optional): Maximum number of results.
  • order (optional): asc or desc (default: desc).
  • include_meta (optional): true to include extra metadata from the prediction_meta table.
  • Example:
GET /api/v1/targets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/predictions
  ?gte=2024-01-01T00:00:00Z
  &lte=2024-01-07T23:59:59Z
  &order=asc
  &limit=100

GET /api/v1/targets/{target_id}/predictions/aggregate

Fetch aggregated predictions (e.g., hourly/daily averages).

  • Query Parameters:
  • aggregation: daily | hourly | weekly | monthly.
  • agg_functions: Comma-separated list of functions (e.g. mean,max,min).
  • gt (optional): Filter by datetime strictly greater than (ISO8601).
  • gte (optional): Filter by datetime greater than or equal to (ISO8601).
  • lt (optional): Filter by datetime strictly less than (ISO8601).
  • lte (optional): Filter by datetime less than or equal to (ISO8601).
  • limit (optional): Maximum number of buckets to return.
  • order (optional): asc or desc (default: desc).
  • Example:
GET /api/v1/targets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/predictions/aggregate
  ?aggregation=daily
  &agg_functions=mean,min,max
  &gte=2024-01-01T00:00:00Z
  &lte=2024-01-31T23:59:59Z
  &order=asc

Utility

Locations

Geospatial anchors for jobs and predictions.

  • POST /api/v1/locations:
json
{
  "id": "UUID", // Optional
  "name": "Office", // Optional
  "latitude": 52.3676, // Optional
  "longitude": 4.9041 // Optional
}

Health & System

  • GET /health: Validates database connectivity and service uptime. Returns JSON status.