{
  "openapi": "3.0.3",
  "info": {
    "title": "HeimerClean OEM Local API",
    "version": "1.0.1-pilot",
    "description": "Windows x64 integration pilot. Obtain the ephemeral port/session via the native SDK. This is not the public cloud API."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:{port}",
      "variables": {
        "port": {
          "default": "8769",
          "description": "Use the actual runtime port from its protected session descriptor."
        }
      }
    }
  ],
  "security": [
    {
      "localSession": []
    }
  ],
  "components": {
    "securitySchemes": {
      "localSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "Per-process token held in a current-user DPAPI descriptor; automatically attached by the DLL."
      }
    },
    "schemas": {
      "Observation": {
        "properties": {
          "cpu_percent": {
            "type": "number",
            "maximum": 100.0,
            "minimum": 0.0,
            "title": "Cpu Percent"
          },
          "memory_percent": {
            "type": "number",
            "maximum": 100.0,
            "minimum": 0.0,
            "title": "Memory Percent"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "cpu_percent",
          "memory_percent"
        ],
        "title": "Observation"
      }
    }
  },
  "paths": {
    "/v1/status": {
      "get": {
        "summary": "Runtime version, capability, license and webhook status",
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        }
      }
    },
    "/v1/license": {
      "get": {
        "summary": "Sanitized signed OEM entitlement status",
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        }
      }
    },
    "/v1/license/activate": {
      "post": {
        "summary": "Activate a partner/protocol OEM license",
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "license_key"
                ],
                "properties": {
                  "license_key": {
                    "type": "string",
                    "minLength": 4,
                    "maxLength": 64
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/ai": {
      "get": {
        "summary": "Read-only model progress; no autonomous scheduler",
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        }
      }
    },
    "/v1/jobs": {
      "post": {
        "summary": "Create or retrieve a job",
        "responses": {
          "202": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "operation",
                  "idempotency_key"
                ],
                "properties": {
                  "operation": {
                    "type": "string",
                    "enum": [
                      "temp.scan",
                      "optimize"
                    ]
                  },
                  "idempotency_key": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{8,64}$"
                  },
                  "consent": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/jobs/{job_id}": {
      "parameters": [
        {
          "in": "path",
          "name": "job_id",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          }
        }
      ],
      "get": {
        "summary": "Poll job and summary result",
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        }
      }
    },
    "/v1/jobs/{job_id}/cancel": {
      "parameters": [
        {
          "in": "path",
          "name": "job_id",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          }
        }
      ],
      "post": {
        "summary": "Cancel queued work only",
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "summary": "Read up to 100 events after a cursor",
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        },
        "parameters": [
          {
            "in": "query",
            "name": "after",
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Advance to the last sequence returned. Keep polling until empty."
          }
        ]
      }
    },
    "/v1/shutdown": {
      "post": {
        "summary": "Stop an idle runtime without interrupting cleanup",
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/license/activate-stock": {
      "post": {
        "summary": "Activate one prepaid OEM device right; stores a protected pool capability",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "pool_id",
                  "activation_token"
                ],
                "properties": {
                  "pool_id": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{16}$"
                  },
                  "activation_token": {
                    "type": "string",
                    "minLength": 32,
                    "maxLength": 128,
                    "writeOnly": true,
                    "format": "password"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON result"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Local session required"
          },
          "403": {
            "description": "Origin, consent or entitlement denied"
          },
          "409": {
            "description": "Busy, conflicting idempotency or lifecycle state"
          }
        }
      }
    },
    "/v1/telemetry/ai-outcomes": {
      "post": {
        "summary": "Queue a consented measured outcome for a completed current-license optimization",
        "description": "Requires local AI collection configuration and pool consent. All accepted samples remain pending_review. Never trains or publishes a model. See OEM telemetry guide for strict request fields.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "event_id",
                  "job_id",
                  "sample"
                ],
                "properties": {
                  "event_id": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{32}$"
                  },
                  "job_id": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{32}$"
                  },
                  "sample": {
                    "properties": {
                      "consent": {
                        "type": "boolean",
                        "title": "Consent"
                      },
                      "action": {
                        "type": "string",
                        "enum": [
                          "temp_clear",
                          "mem_clear",
                          "noop",
                          "daily_optimization"
                        ],
                        "title": "Action"
                      },
                      "model_version": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_.-]{1,64}$",
                        "title": "Model Version"
                      },
                      "before": {
                        "$ref": "#/components/schemas/Observation"
                      },
                      "after": {
                        "$ref": "#/components/schemas/Observation"
                      },
                      "elapsed_seconds": {
                        "type": "number",
                        "maximum": 3600.0,
                        "exclusiveMinimum": 0.0,
                        "title": "Elapsed Seconds"
                      }
                    },
                    "additionalProperties": false,
                    "type": "object",
                    "required": [
                      "consent",
                      "action",
                      "model_version",
                      "before",
                      "after",
                      "elapsed_seconds"
                    ],
                    "title": "AiOutcome"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Durably queued for review"
          },
          "403": {
            "description": "Collection disabled or entitlement invalid"
          },
          "409": {
            "description": "Job not completed/current or conflicting event ID"
          }
        }
      }
    }
  }
}