Skip to main content

Local REST API

The application exposes a loopback-only REST interface for local automation, status inspection, configuration, and inspection control.

Use Automation when you need the detailed recorded-file automation workflow, waiting behavior, cache-reuse semantics, and dataset-export sequence.

The API listens on the configured local port. By default that is http://127.0.0.1:38180/api/v1.

Authentication​

GET /api/v1/health, GET /api/v1/version, and GET /api/v1/playback/{token} are public.

All other currently implemented endpoints require the placeholder X-API-Key header.

Notes​

  • The service binds to loopback only.
  • Playback URLs are returned as opaque local URLs under /api/v1/playback/{token}.
  • GET /api/v1/settings and PATCH /api/v1/settings are aliases for the config endpoints.
  • Most file-analysis detail endpoints require a filePath query parameter.
  • GET /api/v1/openapi.json currently covers the stable automation/export subset first, not the full historical API surface.

OpenAPI​

The application now exposes a machine-readable OpenAPI document at:

  • GET /api/v1/openapi.json

Current intent:

  • provide a stable contract for recorded-file automation control
  • provide a stable contract for file-hash and ingest-run discovery
  • provide a stable contract for DB-backed raw dataset export

Current scope:

  • POST /api/v1/automation/file-session
  • POST /api/v1/automation/file-session/inspect
  • POST /api/v1/automation/files/lookup
  • GET /api/v1/automation/files/{hash}/stages/{stage}
  • GET /api/v1/automation/files/{hash}/ingest-runs
  • GET /api/v1/automation/files/{hash}/ingest-runs/latest
  • GET /api/v1/automation/ingest-runs/{id}
  • the raw MPEG-TS and KLV export endpoints under /api/v1/automation/ingest-runs/{id}/...

Current limitations:

  • the document intentionally starts with the stable automation/export subset
  • it is not yet a complete description of every REST endpoint in the application
  • there is not yet a built-in Swagger UI page for interactive browsing of the OpenAPI document
  • the manual remains the primary source for workflow behavior, cache reuse, and operational caveats

Use Automation for the detailed workflow that sits on top of this contract.

Public endpoints​

  • GET /api/v1/health: returns a simple health payload.
  • GET /api/v1/version: returns the current application version information.
  • GET /api/v1/openapi.json: returns the current OpenAPI document for the automation/export subset of the API.
  • GET /api/v1/playback/{token}: serves a playback stream for an opaque local playback token.

Auth, license, and configuration​

  • GET /api/v1/auth/status: returns the current REST auth status.
  • GET /api/v1/license: returns the current license status.
  • POST /api/v1/license/import: imports a license payload.
  • GET /api/v1/config/nodeinfo: returns the node identifier used for licensing.
  • GET /api/v1/config/license: returns detailed license information.
  • POST /api/v1/config/license: imports a license token.
  • DELETE /api/v1/config/license: removes the installed license.
  • GET /api/v1/config: returns the current application configuration.
  • PATCH /api/v1/config: updates the application configuration.
  • GET /api/v1/settings: alias for GET /api/v1/config.
  • PATCH /api/v1/settings: alias for PATCH /api/v1/config.

Validation rules​

  • GET /api/v1/validation-rules: returns the current rule set and saved templates.
  • PUT /api/v1/validation-rules/current: replaces the current validation rule set.
  • POST /api/v1/validation-rules/templates: saves a named validation-rule template.
  • POST /api/v1/validation-rules/current/restore: restores the current rule set from a saved template.
  • DELETE /api/v1/validation-rules/templates/{name}: deletes a saved template.

File browsing and local path helpers​

  • GET /api/v1/system/file-browse/roots: lists available recorded-file browse roots.
  • POST /api/v1/system/file-browse/entries: lists files and folders for a requested browse location.
  • POST /api/v1/system/file-check: validates a local recorded-file path.

Recent sources​

  • GET /api/v1/sources/recent: returns the recent source list.
  • DELETE /api/v1/sources/{id}: removes one recent source entry.

File analysis and processing​

  • POST /api/v1/analysis/file: runs synchronous file analysis.
  • POST /api/v1/analysis/file/jobs: starts an asynchronous analysis job.
  • GET /api/v1/analysis/file/jobs/{id}: returns analysis job status.
  • POST /api/v1/ingest/file/jobs: starts an ingest job.
  • GET /api/v1/ingest/file/jobs/{id}: returns ingest job status.
  • DELETE /api/v1/ingest/file/jobs/{id}: cancels an ingest job.
  • POST /api/v1/process/file/jobs: starts a processing job.
  • GET /api/v1/process/file/jobs/{id}: returns processing job status.

File-analysis detail endpoints​

  • GET /api/v1/analysis/file/mpegts-errors: returns MPEG-TS error details for a file. Supports optional types=... filtering.
  • GET /api/v1/analysis/file/mpegts-pcr-intervals: returns PCR interval points.
  • GET /api/v1/analysis/file/mpegts-psi-table-positions: returns PAT/PMT position points.
  • GET /api/v1/analysis/file/mpegts-pat-intervals: returns PAT interval points.
  • GET /api/v1/analysis/file/mpegts-pmt-intervals: returns PMT interval points.
  • GET /api/v1/analysis/file/mpegts-pcr-monotonicity: returns PCR monotonicity points.
  • GET /api/v1/analysis/file/mpegts-pcr-pts-drift: returns PCR to PTS drift points.
  • GET /api/v1/analysis/file/mpegts-max-pts-intervals: returns maximum PTS interval points.
  • GET /api/v1/analysis/file/klv-raw-decode-errors: returns KLV raw decode failure points.
  • GET /api/v1/analysis/file/klv-universal-key-errors: returns KLV universal-key failure points.
  • GET /api/v1/analysis/file/klv-checksum-errors: returns KLV checksum failure points.
  • GET /api/v1/analysis/file/klv-unknown-tag-errors: returns unknown-tag failure points.
  • GET /api/v1/analysis/file/klv-duplicate-tag-errors: returns duplicate-tag failure points.
  • GET /api/v1/analysis/file/klv-mandatory-field-errors: returns missing mandatory-field failure points.
  • GET /api/v1/analysis/file/klv-timestamp-monotonicity: returns KLV timestamp monotonicity points.
  • GET /api/v1/analysis/file/klv-packet-rate-consistency: returns KLV packet-rate consistency points.
  • GET /api/v1/analysis/file/klv-stream-vs-klv-drift: returns stream-vs-KLV drift points.

Analysis archive​

  • GET /api/v1/analysis/archive: lists cached analysis archive entries.
  • POST /api/v1/analysis/archive/lookup: looks up a cached analysis entry by file path.
  • GET /api/v1/analysis/archive/{hash}: returns cached analysis results for a file hash.
  • DELETE /api/v1/analysis/archive: deletes cached analysis entries by file hash.

Automation and DB-backed dataset export​

These endpoints are intended for external automation and offline analysis tools.

  • The first control endpoints now let the server open a file session and drive it to report.
  • They return persisted data from the local SQLite-backed caches instead of frontend-composed views.
  • They are designed so later orchestration endpoints can reuse the same file hash and ingest-run identifiers.
  • They are the first subset described by GET /api/v1/openapi.json.

Control​

  • POST /api/v1/automation/file-session: opens or replaces the active file session and returns the current workspace. The session may begin at analyze, ingest, process, or report depending on which cached stages are reusable for the current compatibility key.
  • POST /api/v1/automation/file-session/inspect: opens or replaces the active file session, runs the remaining analyze, ingest, and process stages server-side, waits until the session reaches report, and returns the active workspace plus fileHash and latestIngestRunId for follow-up dataset export calls.

OpenAPI Coverage​

  • GET /api/v1/openapi.json: machine-readable OpenAPI contract for the current automation/export subset.

This is intended for generated clients and endpoint validation. Use Automation for the full control-flow semantics.

Discovery​

  • POST /api/v1/automation/files/lookup: resolves a local filePath to the stored file record, the current compatibility key, the cached workflow stages available for reuse, and the ingest runs already stored for that file.
  • GET /api/v1/automation/files/{hash}/stages/{stage}: returns the cached workflow-stage payload for analyze, ingest, or process using the current compatibility key.
  • GET /api/v1/automation/files/{hash}/ingest-runs: lists every stored ingest run for a cached file hash, newest first.
  • GET /api/v1/automation/files/{hash}/ingest-runs/latest: returns the newest completed ingest run for a cached file hash.
  • GET /api/v1/automation/ingest-runs/{id}: returns the persisted ingest-run summary row.

Raw MPEG-TS datasets​

  • GET /api/v1/automation/ingest-runs/{id}/mpegts/pid-stats: returns the raw per-PID packet and byte totals captured during ingest.
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/pcr-values: returns the raw PCR samples stored during ingest.
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/table-positions: returns the raw PAT/PMT section start positions. Supports optional tableType=PAT or tableType=PMT.
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/pes-timestamps: returns the raw PES timestamp rows.
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/discontinuity-indicators: returns the raw discontinuity-indicator rows.
  • GET /api/v1/automation/ingest-runs/{id}/mpegts/errors: returns the raw MPEG-TS error rows. Supports optional types=... filtering.

Raw KLV datasets​

  • GET /api/v1/automation/ingest-runs/{id}/klv/packets: returns the raw stored KLV payload rows.
  • GET /api/v1/automation/ingest-runs/{id}/klv/metadata-packets: returns the decoded KLV metadata packets.
  • GET /api/v1/automation/ingest-runs/{id}/klv/fields: returns the normalized KLV field rows.

Sessions​

  • POST /api/v1/sessions/file: starts a recorded-file inspection session.
  • POST /api/v1/sessions/live: starts a live inspection session.
  • GET /api/v1/sessions/active: returns the active session, if one exists.
  • DELETE /api/v1/sessions/active: stops the active session.
  • POST /api/v1/sessions/active/stage/complete: marks the active workflow stage as complete.
  • GET /api/v1/sessions/{id}: returns a session by ID.
  • GET /api/v1/sessions/{id}/metadata: returns the session metadata items.
  • GET /api/v1/sessions/{id}/findings: returns the session findings.