OEM Local API Reference

Prepaid device rights can be configured automatically at startup or through authenticated POST /v1/license/activate-stock with pool_id and activation_token. See OEM stock licensing; this does not change the native C ABI.

API version: 1.0 pilot. Base URL: http://127.0.0.1:<runtime-port>. This is a local engine interface, not api.heimerclean.com and not a remote-cleanup service.

Download the OpenAPI contract.

Authentication and request rules

The SDK reads a current-user DPAPI session descriptor and attaches Authorization: Bearer <local-session>. A new session is generated when the runtime starts. Never send this local token to your webhook receiver or cloud API.

• Native loopback clients only; use the literal 127.0.0.1 host and actual port.
• Browser Origin requests and alternate Host headers are denied. There is no browser CORS interface.
• POST requests require application/json, a valid Content-Length and a JSON object of at most 16 KB.
• Unknown fields and duplicate JSON keys are rejected. General desktop IPC, shell commands and arbitrary file paths are not accepted.

Endpoints

Method	Endpoint	Purpose
GET	/v1/status	Versions, capabilities, busy state, license and webhook counters
GET	/v1/license	Sanitized OEM entitlement status
POST	/v1/license/activate	Activate/validate the supplied OEM key
GET	/v1/ai	Read model progress; does not start an autonomous AI loop
POST	/v1/jobs	Submit or retrieve an idempotent job
GET	/v1/jobs/{job_id}	Job state and summary result
POST	/v1/jobs/{job_id}/cancel	Cancel queued work; body {}
GET	/v1/events?after=0	Read up to 100 events after a sequence cursor
POST	/v1/shutdown	Stop an idle runtime; body {}

No endpoint grants update/install, Defender, startup-task or Windows repair access.

Jobs

{
  "operation": "optimize",
  "idempotency_key": "customer-action-0001",
  "consent": true
}

Supported operations:

• temp.scan: read-only scan of the engine's configured safe temporary-file scope; does not delete files.
• optimize: shared manual cleanup/memory optimization with signed OEM entitlement, feature checks and existing engine/protection guards.

Only one job is queued/running at a time. The runtime rechecks permission before execution. Your UI must not use consent: true as a substitute for obtaining actual user or managed-deployment consent.

HTTP 202 returns a job object:

{
  "id": "0123456789abcdef0123456789abcdef",
  "operation": "optimize",
  "state": "queued",
  "created_at": 1792490000.0,
  "updated_at": 1792490000.0,
  "result": null,
  "error": null
}

States: queued, running, succeeded, failed, cancelled. Results contain summary counts, reclaimed storage/memory and engine outcome fields; webhook progress omits local file paths and process names.

Idempotency is durable for the retained job history (latest 256 jobs). The same key with different input is a conflict. A runtime interrupted during a job marks it failed with HC_OEM_RUNTIME_INTERRUPTED on restart; it is not automatically repeated. Inspect the outcome before requesting another cleanup.

Only queued jobs can be cancelled. Cancellation/shutdown does not kill a running engine operation.

Events and failures

Read /v1/events?after=<last-sequence>. Save the last returned sequence and continue until an empty page. Recent event history is bounded; use job polling as the authoritative local result source.

HTTP / code	Host action
401 HC_OEM_UNAUTHORIZED	Reopen the current session descriptor
403 HC_OEM_ENTITLEMENT_REQUIRED	Activate a matching signed OEM license
403 HC_OEM_FEATURE_REQUIRED	Check the cleanup features licensed for this job
403 HC_OEM_CONSENT_REQUIRED	Obtain consent before submitting optimization
409 HC_OEM_BUSY	Wait for the active job
409 HC_OEM_DESKTOP_CONFLICT	Close the standard desktop runtime
409 HC_OEM_IDEMPOTENCY_CONFLICT	Use the original input or a new action key
HC_OEM_ENGINE_FAILED job error	Record the job ID and inspect/support the failure; do not blindly retry

License provisioning boundary

HeimerClean issues OEM-enabled B2B licenses with the agreed oem_partner_id, oem_protocol_id and oem_sdk permission. These values are signed with the existing license/device/expiry policy. The host's startup arguments select the expected identity; they do not grant it.

The existing authenticated administrator licensing API can provision those fields. That is an operator/server action. It is separate from the local /v1/license/activate call used by your installed application. Do not distribute administrator tokens to end-user devices.

Local signed access is checked first. Existing configured licenses use the shared bounded background renewal when due or when their local confirmation needs refreshing. If status includes refresh_pending: true, poll status again before treating it as a final entitlement failure. No trial license is automatically created by the OEM runtime.