Personal API & Core SDK Contracts

HumanOS is architected as an open, modular personal intelligence stack. Whether you are building custom hardware integrations, connecting continuous glucose monitors (CGMs), running automated daily loop cron jobs, or self-hosting `@humanos/core`, our typed ports and fail-closed REST APIs provide complete sovereign control.

01 · Personal REST API Endpoints

POST/api/v1/daily-loop

Compiles recent domain observations, assesses first-vertical readiness (Sleep, Circadian, Energy), resolves snapshot-bound EvidencePacks, runs the HumanIQ planning engine to emit strictly 3 bounded actions, and atomically commits state.

EXAMPLE REQUEST BODY (JSON):

{
  "userId": "usr_sovereign_1",
  "selectedGoal": "circadian",
  "timeZone": "America/New_York",
  "observations": [
    { "domain": "sleep", "metric": "sleep_hours", "value": 7.8, "unit": "hours" },
    { "domain": "circadian", "metric": "morning_lux_minutes", "value": 25, "unit": "minutes" },
    { "domain": "energy", "metric": "subjective_energy", "value": 82, "unit": "score" }
  ]
}

TYPED RESPONSE SUMMARY:

{
  "ok": true,
  "persisted": true,
  "storageMode": "in-memory", // or "postgres" in durable production
  "decision": {
    "disposition": "RECOMMEND",
    "explanation": "Circadian alignment strong; 3 actions generated.",
    "actions": [
      { "domain": "circadian", "title": "Morning Photonic Lux Entrainment", "evidenceClaimIds": [] },
      { "domain": "recovery", "title": "Cyclic Physiological Sigh", "evidenceClaimIds": [] },
      { "domain": "sleep", "title": "Evening Dim-Light Melatonin Shield", "evidenceClaimIds": [] }
    ]
  },
  "domainStates": [ ... ],
  "verticalReadiness": { "readyForPlanning": true, "coverage": 1.0 }
}

POST/api/v1/wearables/sync

Normalizes raw payload streams from Oura, Whoop, Apple Health, or custom providers through the WearableAdapter port. Deduplicates identical (source, metric, timestamp) tuples automatically while preserving independent sensor readings.

EXAMPLE OURA SYNC PAYLOAD:

{
  "provider": "oura",
  "triggerDailyLoop": true,
  "payload": {
    "id": "oura_sync_sample",
    "day": "2026-09-24",
    "score": 88,
    "total_sleep_duration": 28800, // normalized to 8.00 hours
    "lowest_heart_rate": 51,
    "average_hrv": 64
  }
}

GET/api/v1/health

Returns system status, active version (0.3.2), personal API boundary readiness, and storage durability state for monitoring and container health checks.

02 · Building with the TypeScript Core Engine (@humanos/core)

The core engine has zero external HTTP or cloud runtime dependencies. You can import it into edge workers, Node.js microservices, or local CLI scripts:

pnpm add @humanos/core

Implementing a Custom WearableAdapter

Conform to the WearableAdapter port to ingest data from continuous glucose monitors, EEG bands, or smart patches:

import { WearableAdapter, Observation, IntegrationConnection } from "@humanos/core";

export class ContinuousGlucoseAdapter implements WearableAdapter {
  readonly provider = "cgm";

  async normalize(input: unknown, connection: IntegrationConnection): Promise<Observation[]> {
    const raw = input as { glucose_mg_dl: number; timestamp: string };
    return [{
      id: `obs_cgm_${Date.now()}`,
      userId: connection.userId,
      kind: "wearable",
      domain: "metabolic_health",
      metric: "interstitial_glucose",
      value: raw.glucose_mg_dl,
      unit: "mg/dL",
      source: "dexcom_cgm",
      occurredAt: raw.timestamp,
      confidence: 0.94,
      provenance: [{ sourceId: "cgm:sensor_1", kind: "OBSERVED" }]
    }];
  }
}

Attribution Verification with DefaultProgressVerifier

Verify whether an intervention caused a true physiological shift beyond measurement noise:

import { DefaultProgressVerifier } from "@humanos/core";

const verifier = new DefaultProgressVerifier();
const record = await verifier.verify({
  userId: "user_1",
  goal: myUserGoal,
  observations: historicalObservations,
  outcomes: userCompletedOutcomes,
});

console.log(record.status); // "VERIFIED_IMPROVING" | "LIKELY_IMPROVING" | "NO_MEANINGFUL_CHANGE"
console.log(record.reasonCodes); // ["STATUS:VERIFIED_IMPROVING"]

SECURITY CONTRACT

Configuring Bearer Authorization

In production environments, all mutation requests must pass a secure Bearer token in the Authorization: Bearer <TOKEN> header matching the server's configured HUMANOS_INTERNAL_API_TOKEN. Requests failing verification are immediately rejected with HTTP 401 and an empty body.