THREATBYTESTM
All systems operational

Contract

API reference

How the workspace and the analysis engine talk to the platform. Generated from the shared OpenAPI contract.

Status01

The API is a published contract that is not yet served. The 19 operations below are defined in shared/openapi.yaml; the platform implements them under /api/v1 when the backend stage begins. Until then the workspace reads DEMO data and these endpoints return 404.

Authentication02
  • Workspace calls use the signed-in user's session; each operation is checked against the role permission matrix.
  • Engine calls use a dedicated engine API key sent as a bearer token. The engine has no other route to data.
  • Administrator operations require the administrator role on the session.
Conventions03
  • Request and response bodies are JSON.
  • Timestamps are ISO 8601 in UTC.
  • Identifiers are opaque strings; do not parse them.
  • Queue endpoints (next job, next training command) return null when there is nothing to do, and hand each item to exactly one caller.
Samples3 operations

Register specimens and read their metadata and analysis status.

MethodPathSummaryCallerRequestResponse
GET/samplesList samplesWorkspaceNoneSample[]
POST/samplesCreate a new sampleWorkspaceSampleCreate201 Sample
GET/samples/{id}Get a single sampleWorkspaceNoneSample
Analysis jobs and results4 operations

Queue analysis work, hand jobs to the engine one at a time, and accept results.

MethodPathSummaryCallerRequestResponse
GET/analysis/jobsList analysis jobsWorkspaceNoneAnalysisJob[]
POST/analysis/jobsCreate an analysis jobWorkspaceAnalysisJobCreate201 AnalysisJob
POST/analysis/jobs/nextEngine requests the next pending jobEngineNoneAnalysisJob or null
POST/analysis/resultsEngine posts analysis resultsEngineAnalysisResultCreate202 Accepted
Reports2 operations

Read completed analysis reports with verdict, score, and indicators.

MethodPathSummaryCallerRequestResponse
GET/reportsList analysis reportsWorkspaceNoneAnalysisReport[]
GET/reports/{id}Get analysis report by idWorkspaceNoneAnalysisReport
Engine status and training4 operations

Engine heartbeat and the queue of training commands issued from the workspace.

MethodPathSummaryCallerRequestResponse
GET/engine/statusGet engine statusWorkspaceNoneEngineStatus
PATCH/engine/statusEngine updates its status heartbeatEngineEngineStatusUpdate204 No Content
POST/engine/training/commands/nextEngine requests the next training commandEngineNoneTrainingCommand or null
GET/training/datasetsList training datasetsWorkspaceNoneTrainingDataset[]
Experiments3 operations

Experiment definitions and their runs, including recorded metrics.

MethodPathSummaryCallerRequestResponse
GET/experimentsList experimentsWorkspaceNoneExperiment[]
POST/experimentsCreate experimentWorkspaceExperimentCreate201 Experiment
GET/experiments/{id}/runsList runs for an experimentWorkspaceNoneExperimentRun[]
Mitigation and baselines2 operations

Agentic mitigation actions awaiting or past approval, and reactive-baseline runs for comparison.

MethodPathSummaryCallerRequestResponse
GET/mitigation/actionsList mitigation actionsWorkspaceNoneMitigationAction[]
GET/baselinesList baseline runsWorkspaceNoneBaselineRun[]
Administration1 operation

Administrator-only operations.

MethodPathSummaryCallerRequestResponse
GET/admin/usersAdmin list of usersAdministratorNoneAdminUser[]