Developer API Documentation

Version: 1.2.0 | Last Updated: April 07, 2026

1. Introduction & Architecture

The Willow Dynamics Cloud Oracle provides a comprehensive, RESTful API for programmatically interacting with our platform. This document is intended for integration engineers, roboticists, and XR developers who need to automate model creation, execute batch video analysis, and provision edge devices with .int8 topological signatures.

The API is built on an Asynchronous Architecture. Video processing is a long-running task, therefore these jobs follow a Request -> Upload -> Poll pattern to prevent HTTP timeouts and support large file transfers.

REST Uploader (/uploads/presign): A dedicated, high-throughput path for video asset ingestion.
REST Core Services (/data): A low-latency path for data retrieval, job management, and model exporting.

New in V4.1: The API now supports a physics_mode flag, activating our dual-spatial architecture. Physics Models bypass standard torso normalization, projecting the scene into absolute Metric Space (meters) and natively supporting a 76th Node for external object tracking (e.g., tools or balls).

Base API Endpoint & Credentials

Login to get your credentials & base URL.

2. Connection & Authentication

2.1. API Endpoint

You must initialize your SDK or client with the base URL found in the API tab of the interface.

2.2. Authentication Headers

Every request must include the following two HTTP headers. Failure to provide them will result in a 401 Unauthorized or 400 Bad Request.

Header	Description	Example
`x-api-key`	Your unique API Key generated in the Developer API tab.	`QHardroffXP95AzyLNIi4cGdnLRM4r56wjHvXOHf`
`x-customer-id`	Your unique Customer ID, also found in the Developer API tab.	`7245614721101`

Auth Headers Example

{
  "x-api-key": "QHardroffXP95AzyLNIi4cGdnLRM4r56wjHvXOHf",
  "x-customer-id": "8245617721601"
}
          

3. The Asynchronous Workflow

Initiate (Request Upload): Your application sends a POST request to the API at /uploads/presign with your job metadata. The API returns a secure, temporary S3 upload URL and a unique s3Key.
Transfer (Direct S3 Upload): Your application performs an HTTP PUT request directly to the returned presignedUrl, uploading the raw video file. The Cloud Oracle is triggered automatically.
Wait & Poll (Check Status): Your application periodically sends a GET request to the API at /data/models/status or /data/scans/status using the s3_key as a correlation ID. Once the analysisStatus in the response is COMPLETED, the job is finished.

4. Endpoint Reference

POST

/uploads/presign

Initiates a new job by requesting a secure signature to upload a video for either Model Creation or Action Detection.

Request Body (JSON): See Section 5 for advanced parameters.

project: Use mogen_enroll to create a model, or mogen_scan to detect actions.

Success Response (200 OK):

presignedUrl (string): The temporary URL for the HTTP PUT upload.
s3Key (string): The unique ID of the file. You must save this to poll for job status.

Request Body Example

{
  "filename": "pitch_training_01.mp4",
  "metadata": {
    "project": "mogen_enroll", 
    "action_name": "Pro Pitch"
  }
}
          

GET

/data/models

Retrieves a paginated list of all trained models owned by the customer.

GET

/data/models/status?s3_key={key}

Checks the training status of a newly uploaded model. The key is the s3Key returned from the /uploads/presign call.

Status	Meaning
`PROCESSING`	The Fargate container is extracting coordinates and building the signature.
`COMPLETED`	The `.int8` model is built and ready for retrieval.
`FAILED`	Check the `errorMessage` field in the full status record for details.

GET

/data/models/{model_id}

Returns the full metadata object for a specific model, including its action_name, kinematic target_zones, and all baked-in calibration constants.

PUT

/data/models/{model_id}

Updates the calibration constants (DTW, Tempo, Overlap) and/or action_name for an existing model. This is used for "Write Locking" or “baking in” firmware settings.

DELETE

/data/models/{model_id}

Permanently deletes a model and its associated binary from the Cloud Oracle.

PUT Request Body

{
  "threshold_denom": "0.15",
  "tempo_variance_pct": "15",
  "overlap_tolerance_pct": "10",
  "action_name": "Updated Action Name"
}
          

GET

/data/stages

Retrieves a list of all Deployment Stages (IRaaS Deployment Groups) owned by the customer.

GET

/data/stages/{stage_id}

Retrieves the full payload for a specific Stage. This response includes the stage metadata and an array of fully populated model objects assigned to the stage. Each model object includes a short-lived authorizedUrl (presigned S3 link) for immediate binary download by edge devices syncing to this stage.

Response Payload Example

{
  "stageId": "stage-a1b2c3d4",
  "stageName": "Fitness Game Prod",
  "model_details":[
    {
      "analysisId": "model-xyz-123",
      "geminiFileName": "mogen_enroll_complete",
      "authorizedUrl": "https://s3.us-east-2.amazonaws.com/..."
    }
  ]
}
          

GET

/data/scans

Retrieves a paginated list of your action detection history.

GET

/data/scans/{scan_id}

Retrieves the full results of a completed scan. The response contains the detection_results object, which maps each target model ID to an array of detected occurrences.

Occurrence Object:

confidence (float): Probability score (0.0 - 1.0).
start_ms (int) / end_ms (int): Timestamps of the detected action.
box_sequence (array): Bounding box coordinates for UI rendering.

5. Advanced Specifications & Schemas

5.1. Model Creation & Enrollment

To create a model, set the project key in the /uploads/presign metadata to mogen_enroll.

Full `metadata` Object Specification:

Key	Description
`physics_mode`	(New) `"true"` routes data to absolute Metric tracking. `"false"` utilizes Scale-Invariant Universal tracking.
`raw_data_mode`	(New) `"true"` bypasses DSP (Kalman and Savitzky-Golay filters) allowing raw unadulterated sensor ground truth.
`calib_type`	If Physics mode is true, define the strategy: `"yolo"`, `"manual"`, or `"synthetic"`.
`yolo_class`	If YOLO calibration: The COCO ID of the reference object (e.g., `"32"` for Sports Ball).
`known_size_m`	If YOLO calibration: The physical diameter of the object in meters (e.g., `"0.2426"` for Basketball).
`subj_h_m`	If Manual calibration: The known height of the human subject in meters.
`isfinalseed`	(Multi-Camera) Must be `"true"` for the final video in a multi-angle sequence.
`seed_keys`	(Multi-Camera) Comma-separated string of `s3Key` values from child videos.
`trim_data`	(Multi-Camera) Stringified JSON manifest detailing timing and extrinsics. Example: `{"0": {"s": start, "e": end, "a": angle, "h": cam_h_m, "d": cam_d_m}}`. Note: `h` and `d` accept Floats (meters) in Physics Mode, or Imperial in Universal Mode.
`target_zones`	Comma-separated list of active kinematic zones (e.g., `head, torso, arms, hands, legs, feet, object`).
`threshold_denom`	(DTW Sensitivity) In Universal mode, controls proportional strictness. In Physics mode, this defines an absolute Spatial Tolerance Boundary in meters (e.g., `0.15` = 15cm).
`tempo_variance_pct`	(Speed Gate) The allowed % deviation from the seed model's duration. In Physics mode, acts as a strict Absolute Velocity gate.
`overlap_tolerance_pct`	(NMS) The % of temporal overlap allowed between consecutive detections.

Physics Mode Metadata Example

"metadata": {
  "project": "mogen_enroll",
  "action_name": "Robotic Pallet Lift",
  "physics_mode": "true",
  "calib_type": "manual",
  "subj_h_m": "1.85",
  "raw_data_mode": "false",
  "isfinalseed": "true",
  "seed_keys": "uploads/cam_side.mp4",
  "trim_data": "{\"0\":{\"s\":2.1,\"e\":6.5,\"a\":\"Front\",\"h\":1.5,\"d\":3.5},\"1\":{\"s\":1.8,\"e\":6.2,\"a\":\"Side\",\"h\":1.5,\"d\":3.5}}",
  "target_zones": "torso,arms,legs,object",
  "threshold_denom": "0.20",
  "tempo_variance_pct": "10",
  "overlap_tolerance_pct": "25"
}
          

5.2. Client-Side Synchronization Protocol (Acoustic Sync)

The Cloud Oracle's API is stateless and assumes all timestamps in trim_data are pre-synchronized. It is the client application's responsibility to perform alignment. To replicate the "Auto-Sync (Clap)" feature, your SDK must:

Load Audio: Extract the audio track locally for each video.
Find Peak Amplitude: Identify the timestamp of the acoustic event (the clap).
Calculate Offset: Use this peak time as "Time Zero" for that video.
Populate Manifest: Calculate all s (start) and e (end) times in the trim_data manifest relative to each video's unique "Time Zero."

5.3. Virtual Enrollment (3D Data)

To create models directly from .fbx, .json, or .npy files, set project to mogen_virtual_enroll. This bypasses the computer vision pipeline. If physics_mode is set to "true", the engine assumes your data is in absolute meters and will safely auto-pad Node 76 (`[0,0,0,0]`) to legacy 75-node sequences to prevent array indexing crashes.

5.4. Model Export Ecosystem (`GET /data/models/{model_id}/export?format=int8`)

The export endpoint performs Just-In-Time (JIT) transformation. Depending on the Spatial Engine used during creation, the Oracle will deliver a V40 or V41 binary header.

Format	Target Environment	Description
`int8`	Edge SDK (C++/Python)	(Primary) Quantized binary with a 24-byte (V40) or 28-byte (V41 Physics) Little-Endian header.
`onnx`	ML Pipelines (TensorRT)	Standard ONNX graph with signature and calibration metadata embedded in `metadata_props`.
`h`	Embedded Systems (C/C++)	Static C-Header with `#define` macros for calibration.
`json`	Web / Mobile Apps	Comprehensive schema with float32 matrix.
`csv`	Data Science (Pandas/R)	Raw float32 matrix with calibration in a comment header.
`telemetry`	Visualization Engines	The full 3D skeleton sequence and Integrity Scorecard.

.int8 Binary Specification: Depending on the version, the binary is pre-pended with a strict Little-Endian C-struct header. The rest of the payload contains the int8_t RDM distance matrix.

Binary Header Templates

// V40 Universal Header (24-Bytes)
// struct.pack('<IIffff', ...)
[40][ZoneMask][Scale][Overlap][DTW][Tempo]
[...int8_t Payload...]

// V41 Physics Header (28-Bytes)
// struct.pack('<IIfffff', ...)
[41][ZoneMask][CalibrationMethod_Int][Scale][Overlap][SpatialTolerance_Meters][Tempo]
[...int8_t Payload...]
          

6. Appendix

6.1. Response Codes

Code	Meaning
`200 OK`	Request successful.
`204 No Content`	`OPTIONS` pre-flight successful.
`400 Bad Request`	Missing headers or malformed JSON body.
`401 Unauthorized`	Invalid or missing `x-api-key`.
`403 Forbidden`	Accessing data for another Customer ID or API key invalid for Usage Plan.
`404 Not Found`	The requested resource ID or path does not exist.
`429 Too Many Requests`	Rate limit exceeded.
`500 Internal Server Error`	An unhandled error occurred in the Cloud Oracle.

6.2. Code Snippets

Example implementation of model export utilizing the Python SDK wrapper.

Python SDK (Model Export)

import requests

CORE_API_URL = "YOUR_API_ENDPOINT_URL"
headers = {"x-api-key": "YOUR_KEY", "x-customer-id": "YOUR_ID"}

response = requests.get(f"{YOUR_API_ENDPOINT_URL}/data/models/YOUR_MODEL_ID/export?format=int8", headers=headers)

if response.ok: 
    model_binary = response.content