Human Execution API Spec (v0.1)

This specification defines a structured interface for requesting real-world task execution from a verified human execution node, and receiving machine-readable results with evidence.

Workflow

1. Submit a TaskRequest (JSON)
2. Receive a TaskReceipt (accepted/rejected + ETA)
3. Receive a TaskResult (JSON + evidence links)

TaskRequest (JSON)

{
  "spec_version": "0.1",
  "task_id": "client-unique-id-123",
  "task_type": "property_visit",
  "priority": "normal",
  "location": {
    "country": "ES",
    "region": "Andalusia",
    "city": "Seville",
    "address": "Full address or meeting point"
  },
  "objective": "Verify property condition and capture evidence.",
  "requirements": {
    "evidence": ["photos_ext", "photos_int", "timestamp"],
    "questions": ["Is the property vacant?", "Any visible issues?"],
    "deliverables_format": "json"
  },
  "constraints": {
    "time_window": {
      "start": "2026-02-16T09:00:00+01:00",
      "end": "2026-02-16T18:00:00+01:00"
    }
  }
}

TaskReceipt (JSON)

{
  "spec_version": "0.1",
  "task_id": "client-unique-id-123",
  "status": "accepted",
  "estimated_completion": "2026-02-16T18:00:00+01:00",
  "notes": "Access details required: keys/contact person."
}

TaskResult (JSON)

{
  "spec_version": "0.1",
  "task_id": "client-unique-id-123",
  "status": "completed",
  "completed_at": "2026-02-16T16:40:00+01:00",
  "summary": "Property appears vacant. Minor facade cracks.",
  "answers": [
    {"question":"Is the property vacant?","answer":"Likely vacant."}
  ],
  "evidence": {
    "photos": [
      {"label":"front","url":"https://.../photo1.jpg","captured_at":"2026-02-16T16:05:00+01:00"}
    ]
  },
  "exceptions": []
}

Task Types (initial)

• property_visit
• physical_inspection
• evidence_capture
• neighborhood_assessment
• listing_verification

SLA (baseline)

• Receipt: accepted/rejected within < 24 business hours
• Execution: within agreed time window
• Result delivery: as soon as possible after execution (same day when feasible)

Back to node identity: node.ai-human-services.com