Skip to main content

Automation

Use this page when you need to drive recorded-file inspection from an external tool instead of the desktop UI.

The local REST API now supports two different automation needs:

  • control: open a file and run inspection to completion
  • export: retrieve the stored analysis, ingest, process, and raw DB-backed datasets for external analysis

The general endpoint inventory still lives on API. This page explains how the automation flow works, what identifiers matter, how OpenAPI fits into the workflow, and how to combine the control and export endpoints into one repeatable process.

The first machine-readable contract for this surface is available at:

  • GET /api/v1/openapi.json

That document currently covers the stable recorded-file automation and DB-backed export subset of the API. It does not yet attempt to describe every historical endpoint in the application.

What The Automation Flow Owns​

The first automation-control slice is server-owned for recorded files.

That means an external client no longer has to:

  • create a session separately
  • start analyze, ingest, and process jobs one at a time
  • poll each job individually
  • call POST /api/v1/sessions/active/stage/complete after every stage

Instead, the backend can now:

  • open the file session
  • run the remaining workflow stages
  • advance the active session internally
  • return when the workspace reaches report

This matters because the session stage is still the source of truth for the desktop workflow. By moving stage progression into the backend, automation clients no longer need to reproduce frontend behavior.

Current Scope​

The current automation implementation covers recorded-file inspection only.

It supports:

  • opening a file session under the automation namespace
  • running the remaining file workflow stages to report
  • reusing cached stage outputs when they are valid for the current compatibility key
  • returning stable identifiers for later DB-backed export
  • publishing an initial OpenAPI document for this stable subset

It does not yet introduce:

  • a persistent automation run resource
  • a cancel endpoint for the full automation control flow
  • forced rerun options for already cached stages
  • live inspection automation orchestration
  • a full OpenAPI description of every endpoint in the local REST API
  • a Swagger UI surface on top of the OpenAPI document

Authentication And Base URL​

Automation uses the same local loopback API and auth model as the rest of the manual.

  • Base URL: http://127.0.0.1:38180/api/v1
  • Header: X-API-Key: <token>

The API is loopback-only. It is intended for local scripts, test harnesses, and desktop-adjacent tooling on the same machine.

OpenAPI​

The automation/export subset now has a machine-readable OpenAPI document at GET /api/v1/openapi.json.

Use it when you need to:

  • inspect the stable automation path and query contracts programmatically
  • generate a client for the current automation subset
  • validate that an external tool is calling the supported automation endpoints correctly

Current OpenAPI scope:

  • POST /api/v1/automation/file-session
  • POST /api/v1/automation/file-session/inspect
  • file-hash discovery endpoints
  • ingest-run discovery endpoints
  • raw MPEG-TS and KLV dataset export endpoints

Current OpenAPI limitations:

  • it is intentionally limited to the stable automation/export subset
  • raw dataset endpoints are described with stable path and response-envelope contracts first, with more detailed row schemas to follow
  • the older frontend-driven session workflow is not the primary focus of this first contract

The OpenAPI document should be treated as the machine-readable contract for external tooling. This manual page remains the source for workflow semantics, operational caveats, and sequence guidance.

Core Concepts​

File Path​

The starting point is always a local filePath. The automation control endpoints accept the same path the desktop application would open.

File Hash​

The file hash identifies the cached file record in the analysis archive. It is the stable identifier used by the stage-cache and ingest-run discovery endpoints.

Ingest Run ID​

Each completed ingest pass creates a persisted ingest-run row. The ingest-run id is the stable key for the raw MPEG-TS and KLV tables stored in SQLite.

Compatibility Key​

Cached stage reuse is guarded by the current workflow compatibility key. If validation rules change in a way that invalidates previously cached stage outputs, the automation flow starts again from the earlier stage instead of trusting stale cached data.

Control Endpoints​

Open A File Session​

POST /api/v1/automation/file-session

Request:

{
  "filePath": "C:\\media\\example.ts"
}

Behavior:

  • opens or replaces the active file session
  • returns the current workspace immediately
  • may start at analyze, ingest, process, or report

The returned stage depends on which cached workflow stages are already reusable for the current compatibility key.

Use this endpoint when you want server-owned session opening but still want to control subsequent actions yourself.

Open And Inspect Until Report​

POST /api/v1/automation/file-session/inspect

Request:

{
  "filePath": "C:\\media\\example.ts"
}

Behavior:

  • opens or replaces the active file session
  • checks the current active stage
  • runs analyze if needed
  • runs ingest if needed and waits for completion
  • runs process if needed and waits for completion
  • advances the session after each completed stage
  • returns only after the workspace reaches report

Response shape:

  • workspace: the active file workspace at report
  • completed: true when the session reached report
  • fileHash: the cached file identifier for follow-up export calls
  • latestIngestRunId: the most recent completed ingest run for this file

The same response is the anchor point for OpenAPI-generated clients: one control call returns the two stable identifiers needed for the export side of the workflow.

Example:

{
  "workspace": {
    "session": {
      "mode": "file",
      "stage": "report"
    }
  },
  "fileHash": "2f8d2c...",
  "latestIngestRunId": 17,
  "completed": true
}

Use this endpoint when the requirement is simply "open the file, run inspection, and wait until it is complete."

Waiting Semantics​

The inspect endpoint is intentionally synchronous.

Internally it reuses the same backend implementations used elsewhere in the application:

  • synchronous analysis
  • background ingest job plus polling
  • background process job plus polling

That means the request remains open until one of these happens:

  • the session reaches report
  • a stage fails
  • the caller cancels the request

Current cancellation behavior:

  • ingest waiting attempts to cancel the ingest job if the request context ends
  • process waiting stops waiting if the request is canceled, but the current process job implementation can continue in the background because there is not yet a dedicated process-job cancel endpoint

Cache Reuse Behavior​

The automation controller does not blindly rerun every stage.

When a file session is opened, the recorded-file service inspects the stored workflow-stage cache for the current compatibility key:

  • if no reusable stage output exists, the session starts at analyze
  • if analyze is reusable, the session can start at ingest
  • if analyze and ingest are reusable, the session can start at process
  • if analyze, ingest, and process are all reusable, the session starts directly at report

This makes automation deterministic while still preserving the existing cache benefits of the desktop workflow.

Real Application Verification​

There is also a repository utility for checking the automation flow against the real desktop application and the real SQLite database:

  • scripts/run_real_automation_check.py

The script:

  • checks whether the local API is already running
  • starts stinspector.exe if it is not
  • calls POST /api/v1/automation/file-session/inspect
  • checks GET /api/v1/analysis/archive
  • inspects the real SQLite DB directly

This is useful when you need to validate that automation is writing the same file-analysis artifacts as a normal desktop run, rather than only passing an isolated test harness.

Because the script talks to the running desktop application and its configured SQLite database, a successful run should also appear in the application's Archive view after the UI refreshes that list. This is the practical difference from the contract-test harness, which writes into a temporary test database that is discarded after the test process exits.

Typical usage:

python scripts\run_real_automation_check.py testassets\mpegts-cc-error.ts --pretty

The script currently verifies persisted file-analysis artifacts such as:

  • sources
  • analyzed_files
  • file_ingest_runs
  • file_workflow_stage_cache
  • session_workflow_steps

It also reports whether a persisted inspection_sessions table and row exist in the current backend build.

Export And Dataset Retrieval​

After control reaches report, external tooling usually needs one of two things:

  • the stage outputs that the desktop workflow would reuse
  • the raw database rows captured during ingest

The fileHash and latestIngestRunId returned by the control endpoint are the bridge to those exports.

Stage-Cache Export​

Use the fileHash with:

  • GET /api/v1/automation/files/{hash}/stages/analyze
  • GET /api/v1/automation/files/{hash}/stages/ingest
  • GET /api/v1/automation/files/{hash}/stages/process

These endpoints return the cached JSON payloads for the corresponding workflow stages.

Ingest-Run Discovery​

Use the fileHash with:

  • GET /api/v1/automation/files/{hash}/ingest-runs
  • GET /api/v1/automation/files/{hash}/ingest-runs/latest

Use these when you need to confirm which ingest run to analyze instead of assuming the newest row is always correct.

Raw MPEG-TS Datasets​

Use the latestIngestRunId or another selected ingest-run id with:

  • GET /api/v1/automation/ingest-runs/{id}/mpegts/pid-stats
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/pcr-values
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/table-positions
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/pes-timestamps
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/discontinuity-indicators
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/errors

These endpoints expose raw persisted rows rather than chart-ready frontend projections. They are intended for external analytics, custom diagnostics, and offline investigation.

Raw KLV Datasets​

Use the ingest-run id with:

  • GET /api/v1/automation/ingest-runs/{id}/klv/packets
  • GET /api/v1/automation/ingest-runs/{id}/klv/metadata-packets
  • GET /api/v1/automation/ingest-runs/{id}/klv/fields

These endpoints expose the stored KLV packet rows, decoded metadata packets, and normalized field-value rows.

Typical End-To-End Sequence​

For most external tools, the simplest sequence is:

  1. Call POST /api/v1/automation/file-session/inspect with filePath.
  2. Read fileHash and latestIngestRunId from the response.
  3. Optionally validate the path contracts against GET /api/v1/openapi.json.
  4. Fetch cached stage outputs if you need the application's stage summaries.
  5. Fetch raw ingest datasets if you need external analysis over the stored DB rows.

That gives one control call followed by as many export calls as needed.

Example Script Flow​

POST /api/v1/automation/file-session/inspect
  -> returns report workspace, fileHash, latestIngestRunId

GET /api/v1/automation/files/{fileHash}/stages/process
  -> returns processed rule results

GET /api/v1/automation/ingest-runs/{latestIngestRunId}/mpegts/errors
  -> returns raw MPEG-TS error rows

GET /api/v1/automation/ingest-runs/{latestIngestRunId}/klv/fields
  -> returns normalized KLV field rows

Relationship To The General API Page​

Use API when you need the full endpoint list across health, licensing, validation rules, sessions, archive, and automation.

Use this Automation page when you need:

  • the intended control flow
  • the meaning of fileHash and ingestRunId
  • the waiting and cache-reuse semantics
  • the scope and intended use of the OpenAPI document
  • guidance on which endpoints to call next for external analysis

Current Limitations​

  • Automation control currently covers recorded files only.
  • The main control flow is synchronous and request-scoped.
  • There is no persisted automation run history yet.
  • Process-job cancellation is not implemented yet.
  • The API does not yet expose a canonical backend-generated report artifact.
  • The current OpenAPI document is intentionally partial and focuses on the stable automation/export subset first.

Those are reasonable next steps if automation needs to support retries, cancel/resume, scheduling, or long-running external orchestration.