The Orchestration Layer API — Human-AI Routing, Escalation, Safety, Audit

OVERVIEW

The HumanOS API provides programmatic access to HUMAN's orchestration and safety layer. It enables applications to:

Route tasks intelligently between humans and AI
Enforce safety boundaries and escalation rules
Manage human-AI collaboration workflows
Track decision provenance and accountability
Audit AI agent behavior
Enforce ethical constraints (Rule of Threes)

Architecture: REST API with OAuth 2.0 authentication
Protocol Version: 1.0
Base URL: https://api.human.xyz/v1/humanos
Authentication: PATs, OAuth 2.0, Service Account Keys (see 96_api_specification_passport.md)

AI AGENT CLIENT PATTERNS

Living HAIO Context: HumanOS is the orchestration layer where AI agents request routing decisions, report confidence levels, and trigger escalations. This API is the primary interface for AI-human collaboration.

AI Agent Integration Points

Agent Operation	Endpoint	Purpose
Request Routing Decision	`POST /route`	AI asks: should I handle this or escalate?
Report Confidence	`POST /confidence`	AI reports uncertainty level
Trigger Escalation	`POST /escalate`	AI escalates to human
Log Action	`POST /provenance`	AI logs decision for audit
Check Boundaries	`GET /boundaries`	AI checks safety constraints

Fourth Law Implementation

AI agents MUST implement the Fourth Law when calling HumanOS:

# AI Agent routing request with confidence
POST /v1/humanos/route
Content-Type: application/json
X-Agent-ID: urn:human:agent:routing:prod-01
X-Confidence-Score: 0.65

{
  "task_id": "task_abc123",
  "task_type": "medical_review",
  "ai_assessment": {
    "can_handle": true,
    "confidence": 0.65,
    "uncertainty_reason": "edge_case_patient_history"
  },
  "escalation_recommendation": true,
  "human_context": "Patient has unusual medication combination"
}

Response when confidence < 70%:

{
  "routing_decision": "escalate_to_human",
  "reason": "ai_confidence_below_threshold",
  "assigned_human": "did:human:medical_reviewer_1",
  "ai_context_provided": true,
  "fourth_law_triggered": true
}

AI Agent Audit Requirements

All AI agent HumanOS calls are logged with:

Agent ID and version
Task context and type
Confidence score at decision time
Routing decision made
Escalation reason (if applicable)
Human reviewer assigned (if escalated)
Decision outcome and feedback

Batch Operations for AI Agents

High-throughput AI systems should use batch routing:

# Batch routing request
POST /v1/humanos/batch-route
Content-Type: application/json
X-Agent-ID: urn:human:agent:workforce:prod-01

{
  "tasks": [
    { "task_id": "t1", "type": "simple_review", "confidence": 0.95 },
    { "task_id": "t2", "type": "medical_review", "confidence": 0.60 },
    { "task_id": "t3", "type": "legal_review", "confidence": 0.85 }
  ]
}

Safety Boundary Checks

Before taking action, AI agents should verify boundaries:

GET /v1/humanos/boundaries?action=approve_payment&amount=50000
X-Agent-ID: urn:human:agent:finance:prod-01

# Response
{
  "action_allowed": false,
  "reason": "amount_exceeds_ai_authority",
  "human_approval_required": true,
  "approval_tier": "finance_director"
}

CORE CONCEPTS

Orchestration

Intelligent routing of work:

AI-First: Attempt AI resolution first
Human-Required: Route directly to humans
Hybrid: AI + human collaboration
Escalation: Escalate when conditions met

Decision Provenance Graph (aka “Context Graph”)

HumanOS is in the execution path of human + agent work. As it routes, escalates, enforces policy, and records outcomes, it emits decision traces (ProvenanceRecords + Attestations) that form a Decision Provenance Graph across entities and time.

What it captures: not just what happened, but why it was allowed to happen (policies evaluated, exceptions granted, approvals/overrides, and evidence references).
Why it matters: this graph becomes the “system of record for autonomy” because it is reconstructable, auditable, and cryptographically anchored.

Decision Moments

Points where intelligence choice is made:

Capability Assessment: Can AI handle this?
Risk Evaluation: What's the risk level?
Context Analysis: What's the situational context?
Routing Decision: Human, AI, or both?

Escalation Rules

Conditions triggering human involvement:

Uncertainty Threshold: AI confidence < threshold
Safety Boundary: Approaching dangerous territory
Ethical Flag: Rule of Threes violation detected
Complexity: Task too complex for current AI
Human Request: Human explicitly requested

Provenance

Decision audit trail:

Who: Human or AI agent identity
What: Decision or action taken
When: Timestamp
Why: Reasoning and context
How: Process and data used

Important: Provenance in HumanOS is not “debug logging.” It is decision-trace data intended to be stitched into the Decision Provenance Graph and verified via ledger anchors.

Safety Envelope

Boundaries enforced by HumanOS:

Capability Boundaries: Don't exceed proven abilities
Ethical Boundaries: Rule of Threes compliance
Risk Boundaries: Safety thresholds
Context Boundaries: Appropriate for situation

AUTHENTICATION

Same OAuth 2.0 flow as Passport API.

Required Scopes:

humanos:read - Read routing and audit data
humanos:write - Submit routing requests
humanos:admin - Configure rules and boundaries
audit:read - Access audit logs

API DESIGN STANDARDS

The HumanOS API follows HUMAN's standard API design patterns for consistency across all products.

Error Handling (RFC 7807)

All error responses use RFC 7807 Problem Details format:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.human.ai/errors/confidence-threshold-error",
  "title": "Confidence Threshold Not Met",
  "status": 422,
  "detail": "AI confidence (0.45) below minimum threshold (0.70) for autonomous action",
  "instance": "/v1/humanos/routing",
  "errors": [
    {
      "field": "ai_confidence",
      "code": "below_threshold",
      "message": "Confidence 0.45 requires human escalation (threshold: 0.70)"
    }
  ],
  "escalation": {
    "required": true,
    "reason": "low_confidence",
    "suggested_reviewers": ["did:human:expert_123"]
  },
  "request_id": "req_abc123"
}

Pagination

All list endpoints use cursor-based pagination:

GET /v1/humanos/audit?task_type=routing&limit=100&cursor=eyJ...

Response: 200 OK
{
  "data": [
    {"event_id": "evt_123", "type": "routing_decision", ...},
    {"event_id": "evt_124", "type": "escalation_triggered", ...}
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImV2dF8yMDAifQ",
  "total_count": 4837
}

Rate Limiting

All responses include rate limit headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 523
X-RateLimit-Reset: 1702224000
X-RateLimit-Resource: routing-requests

...response body...

Rate limit exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/problem+json

{
  "type": "https://api.human.ai/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 1000 routing requests per minute",
  "retry_after_seconds": 60
}

Idempotency

POST/PUT/PATCH/DELETE endpoints support idempotency keys:

POST /v1/humanos/routing
Authorization: Bearer {access_token}
Idempotency-Key: routing_unique_12345
Content-Type: application/json

{
  "task_id": "task_abc123",
  "ai_confidence": 0.85,
  "required_capabilities": ["safety_review"],
  "urgency": "high"
}

Keys cached for 24 hours
Duplicate requests return cached routing decision
409 Conflict if same key with different routing parameters

Webhooks

HumanOS supports webhooks for real-time event notifications:

POST /yourapi.com/webhooks/humanos
Content-Type: application/json
X-Human-Signature: t=1702224000,v1=5257a869b7ecbcd32c0f3870e1438b557f8a9cf32...
X-Human-Delivery-ID: evt_abc123

{
  "id": "evt_abc123",
  "event": "routing.escalated",
  "created_at": "2025-12-10T12:00:00Z",
  "data": {
    "task_id": "task_xyz789",
    "reason": "ai_confidence_below_threshold",
    "assigned_human": "did:human:expert_456"
  }
}

Webhook Events:

routing.completed - Routing decision made
routing.escalated - Task escalated to human
safety.boundary_violation - Safety boundary triggered
audit.provenance_logged - Decision provenance recorded

Verification: Use HMAC-SHA256 with timestamp (see AI Labs API spec for code examples)

Filtering & Sorting

List endpoints support standardized query parameters:

# Filter by event type
GET /v1/humanos/audit?event_type=escalation&date__gte=2025-12-01

# Filter by multiple criteria
GET /v1/humanos/routing/history?status=completed&confidence__gte=0.7

# Sort results (- for descending)
GET /v1/humanos/audit?sort=-created_at,confidence

Versioning

Current version: v1
Path-based versioning: /v1/humanos/...
Deprecated versions include Sunset header
18-month support window after deprecation
Migration guides at https://api.human.ai/docs/migrations/

CORS

CORS enabled for authorized origins:

Access-Control-Allow-Origin: https://app.human.ai
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key
Access-Control-Expose-Headers: X-RateLimit-Limit, X-RateLimit-Remaining

API ENDPOINTS

1. ROUTING & ORCHESTRATION

Create Routing Request

POST /v1/humanos/routing
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "request_id": "req_unique_123",
  "task_type": "medical_diagnosis",
  "context": {
    "patient_age": 45,
    "symptoms": ["chest_pain", "shortness_of_breath"],
    "urgency": "high",
    "existing_conditions": ["hypertension"]
  },
  "ai_agent_id": "agent_medical_assistant",
  "ai_confidence": 0.72,
  "ai_recommendation": "possible_cardiac_event",
  "required_capabilities": [
    {
      "capability_id": "cap_medical_diagnosis",
      "min_weight": 0.85
    }
  ],
  "safety_requirements": {
    "max_risk_level": "medium",
    "human_oversight_required": true
  },
  "escalation_conditions": {
    "uncertainty_threshold": 0.8,
    "life_safety_flag": true
  }
}

Response:

{
  "routing_id": "routing_abc123",
  "decision": "escalate_to_human",
  "reason": "life_safety_flag_triggered",
  "assigned_to": {
    "type": "human",
    "did": "did:human:doctor_xyz",
    "capabilities_matched": [
      {
        "capability_id": "cap_medical_diagnosis",
        "weight": 0.94
      }
    ]
  },
  "escalation_level": "urgent",
  "estimated_response_time": 180,
  "safety_analysis": {
    "risk_level": "high",
    "safety_boundaries_checked": 5,
    "ethical_constraints_checked": 3,
    "all_constraints_met": true
  },
  "provenance": {
    "decision_made_by": "humanos_core",
    "timestamp": "2025-11-25T23:00:00Z",
    "rule_triggered": "life_safety_escalation",
    "ledger_anchor": {
      "transaction_id": "tx_routing_789",
      "block_number": 987658
    }
  }
}

Get Routing Status

GET /v1/humanos/routing/{routing_id}
Authorization: Bearer {access_token}

Response:

{
  "routing_id": "routing_abc123",
  "status": "in_progress",
  "decision": "escalate_to_human",
  "assigned_to": {
    "type": "human",
    "did": "did:human:doctor_xyz"
  },
  "created_at": "2025-11-25T23:00:00Z",
  "assigned_at": "2025-11-25T23:01:30Z",
  "progress": {
    "steps_completed": 1,
    "steps_total": 3,
    "current_step": "human_assessment"
  },
  "estimated_completion": "2025-11-25T23:10:00Z"
}

2. ESCALATION MANAGEMENT

Configure Escalation Rules

POST /v1/humanos/escalation/rules
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "rule_name": "medical_high_risk_escalation",
  "description": "Escalate all high-risk medical decisions to licensed physicians",
  "conditions": [
    {
      "condition_type": "risk_level",
      "operator": ">=",
      "value": "high"
    },
    {
      "condition_type": "domain",
      "operator": "==",
      "value": "medical"
    },
    {
      "condition_type": "ai_confidence",
      "operator": "<",
      "value": 0.85
    }
  ],
  "actions": [
    {
      "action": "escalate_to_human",
      "target_capability": "cap_medical_diagnosis",
      "min_weight": 0.90,
      "urgency": "high"
    },
    {
      "action": "notify_supervisor",
      "notification_threshold": "immediate"
    }
  ],
  "priority": "critical",
  "enabled": true
}

Response:

{
  "rule_id": "rule_medical_abc",
  "rule_name": "medical_high_risk_escalation",
  "status": "active",
  "created_at": "2025-11-25T23:15:00Z",
  "applies_to": ["medical", "healthcare"],
  "estimated_trigger_rate": "12%"
}

Trigger Manual Escalation

POST /v1/humanos/escalation/manual
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "routing_id": "routing_abc123",
  "escalation_reason": "requesting_second_opinion",
  "requested_by": "did:human:doctor_xyz",
  "target_capability": "cap_cardiology_specialist",
  "urgency": "high",
  "context": {
    "initial_assessment": "possible_cardiac_event",
    "uncertainty_areas": ["ecg_interpretation"]
  }
}

Response:

{
  "escalation_id": "escalation_xyz789",
  "status": "assigned",
  "assigned_to": {
    "type": "human",
    "did": "did:human:cardiologist_abc",
    "capabilities": [
      {
        "capability_id": "cap_cardiology_specialist",
        "weight": 0.96
      }
    ]
  },
  "estimated_response_time": 300,
  "escalation_chain": [
    {
      "level": 1,
      "did": "did:human:doctor_xyz",
      "timestamp": "2025-11-25T23:00:00Z"
    },
    {
      "level": 2,
      "did": "did:human:cardiologist_abc",
      "timestamp": "2025-11-25T23:20:00Z"
    }
  ]
}

3. SAFETY BOUNDARIES

Check Safety Boundaries

POST /v1/humanos/safety/check
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "action": "prescribe_medication",
  "context": {
    "medication": "high_dose_beta_blocker",
    "patient_context": {
      "age": 72,
      "existing_conditions": ["asthma"]
    }
  },
  "actor": {
    "type": "ai_agent",
    "agent_id": "agent_prescribing_assistant",
    "confidence": 0.78
  }
}

Response:

{
  "boundary_check_id": "check_abc123",
  "allowed": false,
  "violations": [
    {
      "boundary_type": "capability_boundary",
      "severity": "critical",
      "description": "AI agents cannot prescribe medication without physician oversight"
    },
    {
      "boundary_type": "safety_boundary",
      "severity": "high",
      "description": "Beta blockers contraindicated with asthma - human review required"
    }
  ],
  "required_action": "escalate_to_human",
  "recommended_capabilities": [
    {
      "capability_id": "cap_physician_licensed",
      "min_weight": 0.95
    }
  ],
  "rule_of_threes_analysis": {
    "good_for_human": "uncertain",
    "good_for_humanity": "uncertain",
    "good_for_HUMAN": true,
    "overall_assessment": "requires_human_judgment"
  }
}

Get Safety Configuration

GET /v1/humanos/safety/config?domain=medical
Authorization: Bearer {access_token}

Response:

{
  "domain": "medical",
  "boundaries": [
    {
      "boundary_id": "medical_prescription_boundary",
      "type": "capability_boundary",
      "description": "Only licensed physicians can prescribe medication",
      "enforcement": "strict",
      "exceptions": "none"
    },
    {
      "boundary_id": "medical_diagnosis_boundary",
      "type": "risk_boundary",
      "description": "Life-threatening diagnoses require human confirmation",
      "enforcement": "strict",
      "escalation_required": true
    }
  ],
  "risk_thresholds": {
    "low": 0.3,
    "medium": 0.6,
    "high": 0.85,
    "critical": 0.95
  },
  "escalation_rules": 12,
  "last_updated": "2025-11-20T00:00:00Z"
}

4. DECISION PROVENANCE

Get Decision History

GET /v1/humanos/provenance/{routing_id}
Authorization: Bearer {access_token}

Response:

{
  "routing_id": "routing_abc123",
  "decision_chain": [
    {
      "step_id": "step_1",
      "timestamp": "2025-11-25T23:00:00Z",
      "actor": {
        "type": "ai_agent",
        "agent_id": "agent_medical_assistant",
        "did": "did:human:agent_abc"
      },
      "action": "initial_assessment",
      "input_data": {
        "symptoms": ["chest_pain", "shortness_of_breath"]
      },
      "output_data": {
        "recommendation": "possible_cardiac_event",
        "confidence": 0.72
      },
      "reasoning": "Pattern matches typical cardiac symptoms, but confidence below threshold due to atypical presentation"
    },
    {
      "step_id": "step_2",
      "timestamp": "2025-11-25T23:00:15Z",
      "actor": {
        "type": "humanos_core",
        "instance_id": "humanos_1"
      },
      "action": "routing_decision",
      "reasoning": "Life safety flag triggered, escalating to human physician",
      "rules_evaluated": [
        {
          "rule_id": "rule_medical_abc",
          "triggered": true,
          "reason": "risk_level_high_and_confidence_low"
        }
      ]
    },
    {
      "step_id": "step_3",
      "timestamp": "2025-11-25T23:01:30Z",
      "actor": {
        "type": "human",
        "did": "did:human:doctor_xyz"
      },
      "action": "physician_assessment",
      "input_data": {
        "ai_recommendation": "possible_cardiac_event",
        "patient_data": {...}
      },
      "output_data": {
        "diagnosis": "acute_coronary_syndrome",
        "treatment_plan": "immediate_hospitalization",
        "confidence": 0.92
      },
      "reasoning": "ECG shows ST-elevation, elevated troponin levels confirm ACS"
    }
  ],
  "ledger_anchors": [
    {
      "step_id": "step_1",
      "transaction_id": "tx_prov_001",
      "block_number": 987658
    },
    {
      "step_id": "step_2",
      "transaction_id": "tx_prov_002",
      "block_number": 987658
    },
    {
      "step_id": "step_3",
      "transaction_id": "tx_prov_003",
      "block_number": 987659
    }
  ],
  "accountability": {
    "primary_decision_maker": "did:human:doctor_xyz",
    "ai_support_provided": true,
    "human_oversight_present": true,
    "all_safety_checks_passed": true
  }
}

5. AI AGENT MONITORING

Register AI Agent

POST /v1/humanos/agents/register
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "agent_name": "Medical Assistant Agent",
  "agent_type": "diagnostic_support",
  "capabilities": [
    {
      "capability_id": "cap_symptom_analysis",
      "confidence_level": 0.85
    },
    {
      "capability_id": "cap_medical_knowledge",
      "confidence_level": 0.90
    }
  ],
  "safety_constraints": {
    "cannot_prescribe": true,
    "requires_human_confirmation": true,
    "max_risk_level": "medium"
  },
  "model_info": {
    "model_type": "GPT-4-Medical",
    "version": "2025-11",
    "training_data": "medical_corpus_v3"
  }
}

Response:

{
  "agent_id": "agent_medical_abc",
  "did": "did:human:agent_medical_abc",
  "status": "active",
  "registered_at": "2025-11-25T23:30:00Z",
  "safety_boundaries_configured": 3,
  "monitoring_enabled": true,
  "api_key": "agent_key_secret_abc123"
}

Get Agent Performance

GET /v1/humanos/agents/{agent_id}/performance?period=30d
Authorization: Bearer {access_token}

Response:

{
  "agent_id": "agent_medical_abc",
  "period": "30d",
  "total_requests": 3845,
  "successful_resolutions": 2934,
  "escalations_to_human": 911,
  "escalation_rate": 0.237,
  "avg_confidence": 0.82,
  "safety_violations": 0,
  "boundary_checks_passed": 3845,
  "accuracy_metrics": {
    "human_agreement_rate": 0.94,
    "false_positive_rate": 0.03,
    "false_negative_rate": 0.02
  },
  "performance_trend": "improving",
  "areas_for_improvement": [
    "rare_condition_detection",
    "pediatric_cases"
  ]
}

6. AUDIT & COMPLIANCE

Get Audit Log

GET /v1/humanos/audit?start_date=2025-11-20&end_date=2025-11-25&type=escalation
Authorization: Bearer {audit_token}

Response:

{
  "audit_entries": [
    {
      "entry_id": "audit_001",
      "timestamp": "2025-11-25T23:00:00Z",
      "event_type": "escalation_triggered",
      "routing_id": "routing_abc123",
      "actor": {
        "type": "humanos_core"
      },
      "details": {
        "rule_triggered": "medical_high_risk_escalation",
        "risk_level": "high",
        "assigned_to": "did:human:doctor_xyz"
      },
      "ledger_anchor": {
        "transaction_id": "tx_audit_001",
        "block_number": 987658
      }
    }
  ],
  "total": 487,
  "page": 1
}

Generate Compliance Report

POST /v1/humanos/compliance/report
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "report_type": "regulatory_compliance",
  "period": "2025-Q4",
  "domains": ["medical", "financial"],
  "include_violations": true
}

Response:

{
  "report_id": "report_compliance_q4",
  "period": "2025-Q4",
  "generated_at": "2025-11-25T23:45:00Z",
  "summary": {
    "total_decisions": 45678,
    "human_oversight_decisions": 12456,
    "ai_autonomous_decisions": 33222,
    "safety_violations": 0,
    "ethical_flags": 23,
    "escalations_triggered": 3421,
    "escalation_rate": 0.075
  },
  "compliance_status": {
    "hipaa_compliant": true,
    "gdpr_compliant": true,
    "sox_compliant": true,
    "rule_of_threes_adherence": 0.998
  },
  "recommendations": [
    "Continue current oversight protocols",
    "Review 23 ethical flags for pattern analysis"
  ],
  "report_url": "https://reports.human.xyz/compliance/report_compliance_q4.pdf"
}

DATA SCHEMAS

Routing Request Schema

{
  "request_id": "string",
  "task_type": "string",
  "context": "object (flexible)",
  "ai_agent_id": "string",
  "ai_confidence": "float (0.0-1.0)",
  "required_capabilities": [
    {
      "capability_id": "string",
      "min_weight": "float (0.0-1.0)"
    }
  ],
  "safety_requirements": "object",
  "escalation_conditions": "object"
}

Routing Decision Schema

{
  "routing_id": "string",
  "decision": "ai_autonomous | escalate_to_human | hybrid_collaboration",
  "reason": "string",
  "assigned_to": {
    "type": "human | ai_agent",
    "did": "string (DID)",
    "agent_id": "string (for AI)"
  },
  "escalation_level": "none | low | medium | high | urgent",
  "safety_analysis": "object",
  "provenance": "object"
}

RATE LIMITING

Endpoint Category	Rate Limit	Window
Routing Requests	5000 requests	1 hour
Safety Checks	10000 requests	1 hour
Provenance Queries	2000 requests	1 hour
Agent Monitoring	1000 requests	1 hour
Audit Logs	500 requests	1 hour

ERROR CODES

Same as Passport API, plus:

safety_violation: Safety boundary violated
escalation_required: Human escalation required but not provided
agent_not_registered: AI agent not registered in HumanOS
rule_conflict: Multiple rules triggered with conflicting actions

WEBHOOKS

Available Events

routing.decided: Routing decision made
escalation.triggered: Escalation rule triggered
safety.violation: Safety boundary approached or violated
agent.registered: New AI agent registered
audit.critical: Critical audit event

Execution-path requirement: Every webhook event above MUST correspond to a persisted provenance event and (where applicable) a signed attestation with a ledger anchor. This is what keeps the Decision Provenance Graph complete and audit-grade.

SDKS & CLIENT LIBRARIES

Official SDKs:

JavaScript/TypeScript: npm install @human/humanos-sdk
Python: pip install human-humanos
Go: go get github.com/human/humanos-go

Example (JavaScript):

import { HumanOSClient } from '@human/humanos-sdk';

const client = new HumanOSClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret'
});

// Request routing decision
const routing = await client.routing.create({
  task_type: 'medical_diagnosis',
  ai_confidence: 0.72,
  safety_requirements: {
    max_risk_level: 'medium',
    human_oversight_required: true
  }
});

console.log(`Decision: ${routing.decision}`);
console.log(`Assigned to: ${routing.assigned_to.did}`);

// Check safety boundaries
const safetyCheck = await client.safety.check({
  action: 'prescribe_medication',
  actor: { type: 'ai_agent', agent_id: 'agent_123' }
});

if (!safetyCheck.allowed) {
  console.log('Action blocked:', safetyCheck.violations);
}

// Get provenance for audit
const provenance = await client.provenance.get(routing.routing_id);
console.log('Decision chain:', provenance.decision_chain);

SECURITY CONSIDERATIONS

Routing Integrity

All routing decisions cryptographically signed
Immutable provenance on distributed ledger
Multi-signature for critical decisions

Safety Enforcement

Hardware-enforced boundaries where possible
Continuous monitoring and anomaly detection
Automatic escalation on boundary approach

Agent Accountability

All AI agents have Machine Identity (DID)
Complete audit trail for all actions
Performance monitoring and evaluation

Compliance

Built-in compliance with major regulations (HIPAA, GDPR, SOX)
Audit logs retained for regulatory requirements
Transparent provenance for legal proceedings

VERSIONING & DEPRECATION

Current Version: v1
Deprecation Policy: 18 months notice for breaking changes
Changelog: https://docs.human.xyz/humanos/changelog

Metadata

File: 100_api_specification_humanos.md
Status: Complete
Version: 1.0
Created: November 25, 2025
Purpose: Enable developer integration with HumanOS (Orchestration Layer)

Cross-References (Related API & HumanOS Files):

See: 22_humanos_orchestration_core.md - Core HumanOS orchestration architecture
See: 23_humanos_safety_and_escalation.md - Safety & escalation framework
See: 36_humanos_technical_standards_and_protocol.md - Technical standards & protocols
See: 33_policy_engine_and_boundary_enforcement.md - Policy engine integration
See: 96_api_specification_passport.md - Passport API for identity verification
See: 97_api_specification_capability_graph.md - Capability API for routing decisions
See: 98_api_specification_workforce_cloud.md - Workforce Cloud API for task assignment

Strategic Purposes:

Building (developer enablement)
Governance (safety enforcement)
Market (enterprise trust)

Final Note: This API is the heart of HUMAN's human-AI orchestration protocol. It ensures every decision is safe, accountable, and aligned with human values.

100. HUMANOS API SPECIFICATION

OVERVIEW

AI AGENT CLIENT PATTERNS

AI Agent Integration Points

Fourth Law Implementation

AI Agent Audit Requirements

Batch Operations for AI Agents

Safety Boundary Checks

CORE CONCEPTS

Orchestration

Decision Provenance Graph (aka “Context Graph”)

Decision Moments

Escalation Rules

Provenance

Safety Envelope

AUTHENTICATION

API DESIGN STANDARDS

Error Handling (RFC 7807)

Pagination

Rate Limiting

Idempotency

Webhooks

Filtering & Sorting

Versioning

CORS

API ENDPOINTS

1. ROUTING & ORCHESTRATION

Create Routing Request

Get Routing Status

2. ESCALATION MANAGEMENT

Configure Escalation Rules

Trigger Manual Escalation

3. SAFETY BOUNDARIES

Check Safety Boundaries

Get Safety Configuration

4. DECISION PROVENANCE

Get Decision History

5. AI AGENT MONITORING

Register AI Agent

Get Agent Performance

6. AUDIT & COMPLIANCE

Get Audit Log

Generate Compliance Report

DATA SCHEMAS

Routing Request Schema

Routing Decision Schema

RATE LIMITING

ERROR CODES

WEBHOOKS

Available Events

SDKS & CLIENT LIBRARIES

SECURITY CONSIDERATIONS

Routing Integrity

Safety Enforcement

Agent Accountability

Compliance

VERSIONING & DEPRECATION

Metadata