{ "openapi": "3.0.3", "info": { "title": "HUMAN API", "description": "HUMAN platform API", "version": "1.0.0" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "ProblemDetails": { "type": "object", "description": "RFC 7807 Problem Details for HTTP APIs", "properties": { "type": { "type": "string", "format": "uri", "description": "URI reference to error type documentation", "example": "https://api.haio.run/errors/validation-error" }, "title": { "type": "string", "description": "Short, human-readable summary", "example": "Validation Failed" }, "status": { "type": "integer", "description": "HTTP status code", "example": 400 }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence", "example": "The request body contains invalid or missing fields" }, "instance": { "type": "string", "format": "uri", "description": "URI reference to specific occurrence (request path)", "example": "/v1/capabilities/match" }, "errors": { "type": "array", "description": "Field-level validation errors", "items": { "$ref": "#/components/schemas/ValidationError" } }, "remediation": { "type": "array", "description": "Steps to fix the error", "items": { "$ref": "#/components/schemas/RemediationStep" } }, "documentation_url": { "type": "string", "format": "uri", "description": "Link to error documentation", "example": "https://docs.haio.run/errors/validation-error" }, "request_id": { "type": "string", "description": "Unique request ID for debugging", "example": "req_a7b3c9d2e1f4g5h6" }, "incident_id": { "type": "string", "description": "Incident ID for internal errors", "example": "inc_xyz789" } }, "required": [ "type", "title", "status", "detail" ], "additionalProperties": true }, "LearningExplainMetadata": { "type": "object", "description": "Optional explain metadata on learning proposals (POST /v1/humanos/learning/proposals) and\nembedded in humanos_tuning_actions.payload after apply. Validated with LearningExplainMetadataSchema\nin @human/humanos; unknown keys are stripped.\n", "properties": { "source": { "type": "string", "enum": [ "package_default", "admin", "user_explicit", "inferred", "system_benchmark" ] }, "scope": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "approval_state": { "type": "string", "enum": [ "none", "pending", "approved", "rejected", "applied", "rolled_back" ] }, "changed_at": { "type": "string" }, "changed_by": { "type": "string" }, "rollback_target": { "type": "string" }, "expiry": { "type": "string" } }, "additionalProperties": true }, "ValidationError": { "type": "object", "description": "Field-level validation error", "properties": { "field": { "type": "string", "description": "Field path (e.g., \"content\", \"metadata.title\")", "example": "requiredCapabilities" }, "code": { "type": "string", "description": "Machine-readable error code", "example": "REQUIRED_FIELD_MISSING" }, "message": { "type": "string", "description": "Human-readable error message", "example": "This field is required" }, "expected": { "type": "string", "description": "Expected value/format", "example": "array of capability IDs" }, "received": { "type": "string", "description": "Actual value received", "example": "undefined" } }, "required": [ "field", "code", "message" ] }, "RemediationStep": { "type": "object", "description": "Step to fix an error", "properties": { "step": { "type": "integer", "description": "Step number", "example": 1 }, "description": { "type": "string", "description": "What to do", "example": "Include an Authorization header with a valid API token" }, "link": { "type": "string", "format": "uri", "description": "Link to relevant documentation", "example": "https://docs.haio.run/authentication" } }, "required": [ "step", "description" ] }, "PaginationInfo": { "type": "object", "description": "Pagination metadata for list responses", "properties": { "has_more": { "type": "boolean", "description": "Whether more results exist", "example": true }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for next page (null if has_more = false)", "example": "eyJpZCI6ImdyYW50XzEyMyJ9" }, "total_count": { "type": "integer", "description": "Total count (optional, omit for large datasets)", "example": 487 } }, "required": [ "has_more", "next_cursor" ] }, "ErrorResponse": { "deprecated": true, "type": "object", "description": "DEPRECATED: Use ProblemDetails instead (RFC 7807)", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "Agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "capabilities": { "type": "array", "items": { "type": "string" } }, "owner_org_passport_id": { "type": "string" }, "passport_id": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive", "deploying" ] } }, "required": [ "id", "name", "capabilities", "owner_org_passport_id", "status" ] }, "AgentListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "agents" ] }, "meta": { "type": "object", "nullable": true } }, "required": [ "data" ] }, "AgentDeployRequest": { "type": "object", "properties": { "manifest": { "type": "object", "additionalProperties": true }, "bundleBase64": { "type": "string" }, "bundleHash": { "type": "string" }, "profile": { "type": "string" }, "region": { "type": "string" }, "wait": { "type": "boolean" } }, "required": [ "manifest", "bundleBase64", "bundleHash" ] }, "AgentDeployResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "agentId": { "type": "string" }, "status": { "type": "string" }, "trace_id": { "type": "string" } }, "required": [ "agentId", "status" ] } }, "required": [ "data" ] }, "AgentStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true }, "status": { "type": "string" }, "runtime": { "type": "object", "nullable": true }, "owner_org_passport_id": { "type": "string" }, "passport_id": { "type": "string", "nullable": true }, "capabilities": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "status", "owner_org_passport_id" ] } }, "required": [ "data" ] }, "ApprovalRequest": { "type": "object", "properties": { "id": { "type": "string", "example": "approval_abc123" }, "task_id": { "type": "string", "example": "task_def456" }, "agent_id": { "type": "string", "example": "agent://org/acme/processor@v1" }, "requester_passport_id": { "type": "string", "example": "did:human:requester123" }, "approver_passport_id": { "type": "string", "example": "did:human:approver456" }, "action_description": { "type": "string", "example": "Process high-value payment" }, "risk_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "risk_factors": { "type": "array", "items": { "type": "object", "properties": { "factor": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ] } } } }, "request_data": { "type": "object" }, "status": { "type": "string", "enum": [ "pending", "approved", "approved_with_modifications", "rejected", "delegated", "overridden", "expired", "cancelled" ] }, "responded_by": { "type": "string", "nullable": true }, "response_comment": { "type": "string", "nullable": true }, "modified_params": { "type": "object", "nullable": true }, "alternatives": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "responded_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "escalation_schema": { "$ref": "#/components/schemas/EscalationSchema", "nullable": true }, "conversation_id": { "type": "string", "nullable": true, "description": "ID of the approval conversation (if any)" }, "delegated_to": { "type": "string", "nullable": true, "description": "Passport DID of delegated approver" }, "override_action": { "type": "string", "nullable": true, "description": "Override action description" } }, "required": [ "id", "task_id", "agent_id", "status", "created_at" ] }, "AsyncExecution": { "type": "object", "properties": { "id": { "type": "string", "example": "exec_abc123" }, "task_id": { "type": "string" }, "agent_id": { "type": "string" }, "requester_passport_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ] }, "result_json": { "type": "object", "nullable": true }, "error_json": { "type": "object", "nullable": true }, "progress_percent": { "type": "integer", "minimum": 0, "maximum": 100 }, "progress_message": { "type": "string", "nullable": true }, "callback_url": { "type": "string", "nullable": true }, "callback_success": { "type": "boolean", "nullable": true }, "callback_attempts": { "type": "integer" }, "max_attempts": { "type": "integer" }, "current_attempt": { "type": "integer" }, "queued_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "provenance_id": { "type": "string", "nullable": true } }, "required": [ "id", "status", "queued_at" ] }, "WorkflowSummary": { "type": "object", "properties": { "workflow_id": { "type": "string" }, "root_node": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "stats": { "$ref": "#/components/schemas/WorkflowStats" } }, "required": [ "workflow_id", "stats" ] }, "WorkflowDAG": { "type": "object", "properties": { "workflow_id": { "type": "string" }, "root_node": { "$ref": "#/components/schemas/WorkflowNode" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNode" } }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEdge" } }, "stats": { "$ref": "#/components/schemas/WorkflowStats" } }, "required": [ "workflow_id", "nodes", "edges", "stats" ] }, "WorkflowNode": { "type": "object", "properties": { "id": { "type": "string" }, "workflow_id": { "type": "string" }, "parent_node_id": { "type": "string", "nullable": true }, "node_type": { "type": "string", "enum": [ "agent", "human", "approval", "fork", "join", "condition" ] }, "node_name": { "type": "string", "nullable": true }, "agent_id": { "type": "string", "nullable": true }, "agent_name": { "type": "string", "nullable": true }, "input": { "type": "object", "nullable": true }, "output": { "type": "object", "nullable": true }, "error": { "type": "object", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "skipped", "waiting_approval" ] }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "duration_ms": { "type": "integer", "nullable": true }, "visual_metadata": { "type": "object", "nullable": true }, "provenance_id": { "type": "string", "nullable": true }, "execution_id": { "type": "string", "nullable": true }, "approval_id": { "type": "string", "nullable": true } }, "required": [ "id", "workflow_id", "node_type", "status", "created_at" ] }, "WorkflowEdge": { "type": "object", "properties": { "id": { "type": "string" }, "from_node_id": { "type": "string" }, "to_node_id": { "type": "string" }, "edge_type": { "type": "string", "enum": [ "sequence", "success", "failure", "condition_true", "condition_false", "fork", "join" ] }, "condition": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "required": [ "id", "from_node_id", "to_node_id", "edge_type" ] }, "WorkflowStats": { "type": "object", "properties": { "total_nodes": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "running": { "type": "integer" }, "pending": { "type": "integer" }, "total_duration_ms": { "type": "integer", "nullable": true }, "avg_node_duration_ms": { "type": "number", "nullable": true } }, "required": [ "total_nodes", "completed", "failed", "running", "pending" ] }, "RevocationRecord": { "type": "object", "properties": { "id": { "type": "string" }, "delegation_id": { "type": "string" }, "revoked_by": { "type": "string" }, "revoked_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "required": [ "id", "delegation_id", "revoked_by", "revoked_at" ] }, "MarketplaceConnectorListing": { "type": "object", "description": "Connector listing in marketplace", "properties": { "connector_id": { "type": "string", "description": "Connector ID", "example": "conn_google_calendar" }, "name": { "type": "string", "description": "Connector name", "example": "Google Calendar" }, "provider": { "type": "string", "description": "Provider name", "example": "google" }, "description": { "type": "string", "description": "Short description" }, "icon_url": { "type": "string", "format": "uri", "description": "Icon URL" }, "version": { "type": "string", "description": "Connector version", "example": "1.0.0" }, "publisher_id": { "type": "string", "description": "Publisher ID ('human' for core connectors)" }, "certified": { "type": "boolean", "description": "HUMAN-certified badge" }, "pricing_model": { "type": "string", "enum": [ "free", "paid", "freemium" ] }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability IDs" }, "install_count": { "type": "integer", "description": "Number of installations" }, "rating_average": { "type": "number", "format": "float", "nullable": true, "description": "Average rating (0.00-5.00)" }, "rating_count": { "type": "integer", "description": "Number of ratings" }, "oauth": { "type": "object", "properties": { "required": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "deployment_modes": { "type": "array", "items": { "type": "string", "enum": [ "cloud", "hybrid", "self-hosted" ] } }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "down", "unknown" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "ConnectorDetails": { "type": "object", "description": "Detailed connector information", "properties": { "connector_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "description": { "type": "string" }, "long_description": { "type": "string", "description": "Markdown-formatted long description" }, "icon_url": { "type": "string", "format": "uri" }, "version": { "type": "string" }, "publisher": { "type": "object", "properties": { "publisher_id": { "type": "string" }, "name": { "type": "string" }, "verified": { "type": "boolean" } } }, "certified": { "type": "boolean" }, "pricing_model": { "type": "string", "enum": [ "free", "paid", "freemium" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "oauth": { "type": "object", "properties": { "required": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "authorization_url": { "type": "string", "format": "uri" }, "token_url": { "type": "string", "format": "uri" } } }, "deployment_modes": { "type": "array", "items": { "type": "string" } }, "configuration_schema": { "type": "object", "description": "JSON Schema for connector configuration" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "down", "unknown" ] }, "last_health_check_at": { "type": "string", "format": "date-time", "nullable": true }, "statistics": { "type": "object", "properties": { "install_count": { "type": "integer" }, "rating_average": { "type": "number", "format": "float", "nullable": true }, "rating_count": { "type": "integer" }, "invocation_count_30d": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "InstallationPendingOAuth": { "type": "object", "description": "Installation pending OAuth authorization", "properties": { "installation_id": { "type": "string" }, "connector_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_oauth" ] }, "oauth_authorization_url": { "type": "string", "format": "uri", "description": "URL user must visit to authorize" }, "oauth_state": { "type": "string", "description": "OAuth state parameter" }, "redirect_uri": { "type": "string", "format": "uri", "description": "OAuth redirect URI" }, "expires_at": { "type": "string", "format": "date-time", "description": "Authorization URL expiration (15 minutes)" } } }, "InstallationActive": { "type": "object", "description": "Active installation (no OAuth required)", "properties": { "installation_id": { "type": "string" }, "connector_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active" ] }, "installed_at": { "type": "string", "format": "date-time" } } }, "ConnectorInstallation": { "type": "object", "description": "Installed connector details", "properties": { "installation_id": { "type": "string" }, "connector": { "type": "object", "properties": { "connector_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "icon_url": { "type": "string", "format": "uri", "nullable": true } } }, "status": { "type": "string", "enum": [ "active", "suspended", "uninstalled" ] }, "deployment_mode": { "type": "string", "enum": [ "cloud", "hybrid", "self-hosted" ] }, "config": { "type": "object", "additionalProperties": true }, "granted_permissions": { "type": "array", "items": { "type": "string" } }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "down", "unknown" ] }, "installed_by": { "type": "string", "description": "DID of person who installed" }, "installed_at": { "type": "string", "format": "date-time" }, "last_invocation_at": { "type": "string", "format": "date-time", "nullable": true }, "invocation_count_30d": { "type": "integer", "description": "Invocations in last 30 days" } } }, "ConnectorRating": { "type": "object", "description": "Connector rating and review", "properties": { "rating_id": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "review_text": { "type": "string", "nullable": true }, "user": { "type": "object", "properties": { "user_id": { "type": "string" }, "display_name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RatingSummary": { "type": "object", "description": "Rating summary statistics", "properties": { "average": { "type": "number", "format": "float", "description": "Average rating (0.00-5.00)" }, "count": { "type": "integer", "description": "Total number of ratings" }, "distribution": { "type": "object", "description": "Count per star rating", "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } } } } }, "InstallationUsage": { "type": "object", "description": "Installation usage statistics (30 days)", "properties": { "installation_id": { "type": "string" }, "connector_id": { "type": "string" }, "period": { "type": "string", "enum": [ "30d" ] }, "statistics": { "type": "object", "properties": { "total_invocations": { "type": "integer" }, "successful_invocations": { "type": "integer" }, "failed_invocations": { "type": "integer" }, "average_duration_ms": { "type": "number", "format": "float" }, "total_cost_usd": { "type": "number", "format": "float" }, "last_invocation_at": { "type": "string", "format": "date-time", "nullable": true } } }, "daily_breakdown": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "invocations": { "type": "integer" }, "cost_usd": { "type": "number", "format": "float" } } } } } }, "SessionExchangeRequest": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Requested delegation capabilities. Defaults to reasoning + agents read/invoke if empty." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Alias for capabilities (accepted for client convenience)" }, "duration_seconds": { "type": "integer", "minimum": 1, "maximum": 2592000, "default": 86400, "description": "Token duration in seconds (max 30 days)" }, "environment": { "type": "string", "description": "Optional environment constraint" }, "risk_level": { "type": "string", "enum": [ "low", "standard", "high" ], "default": "standard" }, "required_verification_tier": { "type": "integer", "description": "Required passport verification tier (rejects if below)" }, "required_identity_tier": { "type": "integer", "description": "Required passport identity tier (rejects if below)" } } }, "SessionExchangeResponse": { "type": "object", "required": [ "delegation_id", "token", "passport_id", "did", "capabilities", "created_at", "expires_at" ], "properties": { "delegation_id": { "type": "string", "description": "Unique delegation grant ID" }, "token": { "type": "string", "description": "Bearer token for API authentication" }, "passport_id": { "type": "string", "description": "Passport DID that owns this delegation" }, "did": { "type": "string", "description": "DID of the passport" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "verification_tier": { "type": "integer" }, "identity_tier": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "DeploymentComplianceResponse": { "type": "object", "properties": { "deployment_id": { "type": "string" }, "protocol_version": { "type": "string" }, "compliance": { "type": "object", "properties": { "human_passport_minting": { "type": "string", "enum": [ "device_only" ] }, "attestation_formats_accepted": { "type": "array", "items": { "type": "string" } }, "ledger_sync_status": { "type": "string" }, "passport_count": { "type": "integer" }, "verification_count": { "type": "integer" }, "last_compliance_check": { "type": "string", "format": "date-time" } } }, "invariants": { "type": "object", "properties": { "server_side_key_generation": { "type": "boolean" }, "private_key_access": { "type": "boolean" }, "biometric_binding_hash_used": { "type": "boolean" }, "webauthn_required_for_humans": { "type": "boolean" } } }, "signature": { "type": "string", "description": "HMAC-SHA256 signature of the compliance record" } } }, "WalledGardenStatus": { "type": "object", "properties": { "network_verification": { "type": "string", "enum": [ "local_only", "network_verified" ] }, "explanation": { "type": "string" }, "mitigations": { "type": "array", "items": { "type": "string" } }, "risks": { "type": "object", "properties": { "walled_garden_possible": { "type": "boolean" }, "blast_radius": { "type": "string" }, "risk_acceptance": { "type": "string" } } }, "recommendations": { "type": "array", "items": { "type": "string" } } } }, "ReasoningThinkRequest": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "content": { "type": "string" } } } }, "task": { "type": "string", "enum": [ "reasoning", "coding", "summarization", "creative", "math", "general" ] }, "complexity": { "type": "string", "enum": [ "simple", "medium", "complex" ] }, "budget": { "type": "string", "enum": [ "minimize", "optimize", "unlimited" ], "default": "optimize" }, "pinned_model": { "type": "string", "description": "Override model selection with a specific model" }, "entity_id": { "type": "string", "description": "Organization or entity for cost tracking" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "integer", "minimum": 1 } } }, "ReasoningThinkResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" } } } } }, "metadata": { "type": "object", "properties": { "costUsd": { "type": "number" }, "durationMs": { "type": "integer" }, "routingDecision": { "type": "object", "properties": { "selected": { "type": "string" }, "reason": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } } } } } } } }, "ModelListResponse": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelInfo" } } } }, "ModelInfo": { "type": "object", "properties": { "model_id": { "type": "string" }, "provider": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string" }, "capabilities": { "type": "object", "properties": { "reasoning": { "type": "number" }, "coding": { "type": "number" }, "summarization": { "type": "number" }, "multilingual": { "type": "number" }, "math_reasoning": { "type": "number" }, "creative_writing": { "type": "number" }, "instruction_following": { "type": "number" } } }, "context_length": { "type": "integer" }, "supports_streaming": { "type": "boolean" }, "supports_function_calling": { "type": "boolean" }, "supports_vision": { "type": "boolean" }, "performance": { "type": "object", "properties": { "avg_latency_ms": { "type": "number" }, "reliability": { "type": "number" }, "success_rate": { "type": "number" } } }, "cost": { "type": "object", "properties": { "input_cost_per_million": { "type": "number", "description": "USD per million input tokens" }, "output_cost_per_million": { "type": "number", "description": "USD per million output tokens" } } }, "status": { "type": "string", "enum": [ "active", "deprecated", "experimental" ] } } }, "ModelPerformanceResponse": { "type": "object", "properties": { "model_id": { "type": "string" }, "total_requests": { "type": "integer" }, "success_rate": { "type": "number" }, "avg_latency_ms": { "type": "number" }, "avg_cost_usd": { "type": "number" }, "by_complexity": { "type": "object", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer" }, "success_rate": { "type": "number" }, "avg_cost": { "type": "number" } } } } } }, "BenchmarkSubmission": { "type": "object", "required": [ "model_id", "benchmark_type", "benchmark_suite", "score" ], "properties": { "model_id": { "type": "string" }, "benchmark_type": { "type": "string", "description": "e.g., reasoning, coding, math" }, "benchmark_suite": { "type": "string", "description": "e.g., mmlu, humaneval, gsm8k" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "run_at": { "type": "string", "format": "date-time" }, "run_by": { "type": "string" }, "test_cases_passed": { "type": "integer" }, "test_cases_total": { "type": "integer" }, "raw_results": { "type": "object" } } }, "BenchmarkResult": { "type": "object", "properties": { "id": { "type": "string" }, "model_id": { "type": "string" }, "benchmark_type": { "type": "string" }, "benchmark_suite": { "type": "string" }, "score": { "type": "number" }, "run_at": { "type": "string", "format": "date-time" }, "run_by": { "type": "string" }, "test_cases_passed": { "type": "integer" }, "test_cases_total": { "type": "integer" } } }, "PromptProfile": { "type": "object", "properties": { "prompt_uri": { "type": "string" }, "prompt_key": { "type": "string" }, "org_id": { "type": "string" }, "scope": { "type": "string" }, "namespace": { "type": "string" }, "active_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PromptVersion": { "type": "object", "properties": { "prompt_uri": { "type": "string" }, "prompt_key": { "type": "string" }, "org_id": { "type": "string" }, "version": { "type": "string" }, "content": { "type": "string" }, "meta": { "type": "object" }, "input_schema": { "type": "object" }, "extends_uri": { "type": "string" }, "published_by": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "deprecated" ] } } }, "PromptPublishRequest": { "type": "object", "required": [ "version", "content", "meta" ], "properties": { "version": { "type": "string", "description": "Semver version (e.g., \"1.0.0\")" }, "content": { "type": "string", "description": "Prompt body text" }, "meta": { "type": "object", "description": "Prompt metadata (id, namespace, scope, description)", "properties": { "id": { "type": "string" }, "namespace": { "type": "string" }, "scope": { "type": "string" }, "description": { "type": "string" } } }, "input_schema": { "type": "object", "description": "Optional JSON Schema for prompt inputs" } } }, "PromptListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PromptProfile" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfo" } } }, "PromptVersionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PromptVersion" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfo" } } }, "PromptPerformanceResponse": { "type": "object", "properties": { "prompt_key": { "type": "string" }, "window": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "stats": { "type": "object", "properties": { "total_calls": { "type": "integer" }, "avg_tokens": { "type": "integer" }, "avg_cost_usd": { "type": "number" }, "avg_duration_ms": { "type": "integer" }, "positive_signals": { "type": "integer" }, "negative_signals": { "type": "integer" }, "rephrases": { "type": "integer" }, "corrections": { "type": "integer" } } }, "model_breakdown": { "type": "array", "items": { "type": "object", "properties": { "model_id": { "type": "string" }, "provider": { "type": "string" }, "call_count": { "type": "integer" }, "avg_latency_ms": { "type": "integer" }, "avg_cost_usd": { "type": "number" }, "avg_tokens": { "type": "integer" }, "success_rate": { "type": "number" } } } }, "recommended_model": { "type": "string", "nullable": true } } }, "PromptAffinityResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "prompt_key": { "type": "string" }, "model_id": { "type": "string" }, "provider": { "type": "string" }, "sample_size": { "type": "integer" }, "stats": { "type": "object", "properties": { "avg_latency_ms": { "type": "integer" }, "avg_cost_usd": { "type": "number" }, "avg_tokens": { "type": "integer" }, "success_rate": { "type": "number" } } }, "affinity_score": { "type": "number" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationInfo" } } }, "CpOrg": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Org Passport DID", "example": "did:org:acme" }, "name": { "type": "string", "example": "Acme Corp" }, "deployment_mode": { "type": "string", "enum": [ "cloud", "self_hosted", "hybrid" ] }, "autonomy_profile": { "type": "string", "enum": [ "paranoid", "balanced", "aggressive" ] }, "data_residency_tier": { "type": "string", "enum": [ "local_only", "regional", "global" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "org_did", "name", "deployment_mode" ] }, "CreateCpOrgRequest": { "type": "object", "required": [ "org_did", "name" ], "properties": { "org_did": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "deployment_mode": { "type": "string", "enum": [ "cloud", "self_hosted", "hybrid" ], "default": "cloud" }, "autonomy_profile": { "type": "string", "enum": [ "paranoid", "balanced", "aggressive" ], "default": "balanced" }, "data_residency_tier": { "type": "string", "enum": [ "local_only", "regional", "global" ], "default": "global" } } }, "MarketplaceAssetList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceAsset" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "MarketplaceAsset": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string", "example": "1.0.0" }, "asset_type": { "type": "string", "enum": [ "connector", "agent", "workflow", "capability", "workforce", "dataset", "muscle" ] }, "publisher_id": { "type": "string" }, "review_status": { "type": "string", "enum": [ "pending", "approved", "rejected", "deprecated", "pending_publisher_response" ] }, "trust_tier": { "type": "string", "enum": [ "community", "verified", "certified", "enterprise" ] }, "lifecycle_stage": { "type": "string", "enum": [ "dev", "staging", "production" ] }, "install_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "SubmitMarketplaceAssetRequest": { "type": "object", "required": [ "name", "asset_type" ], "properties": { "name": { "type": "string" }, "asset_type": { "type": "string", "enum": [ "connector", "agent", "workflow", "capability", "workforce", "dataset", "muscle" ] }, "visibility": { "type": "string", "enum": [ "org_private", "org_internal", "global" ], "default": "org_private" }, "lifecycle_stage": { "type": "string", "enum": [ "dev", "staging", "production" ], "default": "production" }, "manifest": { "type": "object", "description": "Canonical asset manifest (FR-9)", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "provenance": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "description": "URL or DID of source code repository" }, "publishedBy": { "type": "string" } } }, "capabilities": { "type": "object", "properties": { "required_scopes": { "type": "array", "items": { "type": "string" } } } } } } } }, "Resource": { "type": "object", "description": "Resource record in the resource graph", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "uri": { "type": "string" }, "owner_did": { "type": "string" }, "controller_did": { "type": "string" }, "kind": { "type": "string" }, "schema_id": { "type": "string", "nullable": true }, "connector_id": { "type": "string" }, "metadata": { "type": "object" }, "provenance_ref": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ResourceCreateRequest": { "type": "object", "required": [ "uri", "kind", "owner_did" ], "properties": { "uri": { "type": "string" }, "kind": { "type": "string" }, "owner_did": { "type": "string" }, "schema_id": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "provenance_ref": { "type": "string", "nullable": true } } }, "ResourcePatchRequest": { "type": "object", "properties": { "kind": { "type": "string" }, "schema_id": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "provenance_ref": { "type": "string", "nullable": true } } }, "ResourceListResponse": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "total_count": { "type": "integer", "nullable": true } } }, "Schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "authority_did": { "type": "string" }, "kind": { "type": "string" }, "version": { "type": "integer" }, "definition": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" } } }, "SchemaRegisterRequest": { "type": "object", "required": [ "kind", "definition" ], "properties": { "kind": { "type": "string" }, "definition": { "type": "object" }, "created_by": { "type": "string" } } }, "SchemaListResponse": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Schema" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "OrgSchemaPref": { "type": "object", "properties": { "org_did": { "type": "string" }, "kind_pattern": { "type": "string" }, "preferred_schema_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "OrgSchemaPrefUpsertRequest": { "type": "object", "required": [ "org_did", "kind_pattern", "preferred_schema_id" ], "properties": { "org_did": { "type": "string" }, "kind_pattern": { "type": "string" }, "preferred_schema_id": { "type": "string" } } }, "OrgSchemaPrefListResponse": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgSchemaPref" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "OrgProfile": { "type": "object", "properties": { "org_did": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "website_url": { "type": "string", "nullable": true }, "logo_url": { "type": "string", "nullable": true }, "brand_tokens": { "type": "object", "nullable": true }, "updated_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrgCommsSettings": { "type": "object", "properties": { "org_did": { "type": "string" }, "send_mode": { "type": "string", "enum": [ "transactional", "marketing", "all" ] }, "from_display_name": { "type": "string" }, "from_email": { "type": "string" }, "reply_to_email": { "type": "string", "nullable": true }, "legal_footer": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } } }, "ApprovalMessage": { "type": "object", "description": "A message in an approval conversation", "properties": { "id": { "type": "string", "description": "Unique message ID", "example": "msg_abc123" }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Who sent the message (user = human reviewer, assistant = agent)" }, "content": { "type": "string", "description": "Message content" }, "created_at": { "type": "string", "format": "date-time", "description": "When the message was sent" } }, "required": [ "id", "role", "content" ] }, "ApprovalDecisionType": { "type": "string", "description": "The type of decision made on an approval request.\n- approved: Approve the request as-is\n- approved_with_modifications: Approve with changed parameters\n- rejected: Reject the request\n- delegated: Re-route to another approver\n- overridden: Human overrides the agent's approach entirely\n", "enum": [ "approved", "approved_with_modifications", "rejected", "delegated", "overridden" ] }, "ApprovalRespondRequest": { "type": "object", "description": "Request body for responding to an approval", "properties": { "decision": { "$ref": "#/components/schemas/ApprovalDecisionType" }, "responded_by": { "type": "string", "description": "Passport DID of responder" }, "comment": { "type": "string", "description": "Optional comment explaining the decision" }, "modified_params": { "type": "object", "description": "Modified parameters (for approved_with_modifications)" }, "delegate_to": { "type": "string", "description": "Passport DID to delegate to (for delegated decisions)" }, "override_action": { "type": "string", "description": "Override action description (for overridden decisions)" } }, "required": [ "decision", "responded_by" ] }, "EscalationSchema": { "type": "object", "description": "JSON Schema with UI rendering hints for the approval context panel.\nWhen provided on an approval request, the UI uses this schema to\nauto-render structured context instead of showing raw JSON.\n", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EscalationSchemaProperty" } }, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "properties" ] }, "EscalationSchemaProperty": { "type": "object", "description": "A property in an escalation schema with optional UI hints", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "array", "object" ] }, "description": { "type": "string" }, "enum": { "type": "array", "items": { "type": "string" } }, "items": { "type": "object", "properties": { "type": { "type": "string" } } }, "ui": { "type": "object", "description": "UI rendering hints for the approval component", "properties": { "displayAs": { "type": "string", "enum": [ "text", "number", "currency", "badge", "badges", "radio", "select", "code", "json", "list", "link" ] }, "label": { "type": "string", "description": "Field label (overrides property key)" }, "variant": { "type": "string", "enum": [ "default", "info", "success", "warning", "danger" ] }, "currency": { "type": "string", "description": "Currency code (for displayAs currency)" }, "hidden": { "type": "boolean", "description": "Whether to hide this field by default" } } } }, "required": [ "type" ] }, "PassportActivityEvent": { "type": "object", "description": "Subject-facing activity event (Passport Transparency). Core fields are always present; data_categories and purpose may be null when the subject's org has a transparency redaction policy.", "required": [ "event_id", "event_type", "timestamp", "outcome", "risk_level" ], "properties": { "event_id": { "type": "string", "description": "Unique event identifier" }, "event_type": { "type": "string", "description": "Type of governed decision (e.g. delegation.used, grant.created)" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 UTC)" }, "actor_did": { "type": "string", "nullable": true }, "actor_display": { "type": "string", "nullable": true }, "subject_did": { "type": "string" }, "grant_id": { "type": "string", "nullable": true }, "connector_id": { "type": "string", "nullable": true }, "connector_name": { "type": "string", "nullable": true }, "outcome": { "type": "string" }, "risk_level": { "type": "string" }, "data_categories": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "May be null when the subject's org has a transparency redaction policy that hides data categories." }, "purpose": { "type": "string", "nullable": true, "description": "May be null when the subject's org has a transparency redaction policy that hides purpose." }, "proofs": { "type": "object", "properties": { "provenance_ref": { "type": "string", "nullable": true }, "attestation_ref": { "type": "string", "nullable": true }, "ledger_anchor_ref": { "type": "string", "nullable": true } } } } }, "CpExtensionCapabilitiesSnapshot": { "type": "object", "description": "Snapshot of humanos.extension.v1 manifest `capabilities` at install (`marketplace_cp_extensions.capabilities`).", "properties": { "read": { "type": "array", "items": { "type": "string" }, "description": "Declared read capability ids (e.g. artifacts, metrics, policy)." }, "write": { "type": "array", "items": { "type": "string" }, "description": "Declared write capability ids (often empty for read-only extensions)." } }, "additionalProperties": false }, "LayerStatus": { "type": "object", "description": "Progress for a single verification layer (WebAuthn device, biometric binding, social vouches, proof of personhood).", "properties": { "status": { "type": "string", "description": "Layer state (e.g. complete, available, pending, not_started)." }, "completed_at": { "type": "string", "format": "date-time" }, "provider": { "type": "string" }, "action_url": { "type": "string", "description": "Relative or absolute URL to complete the layer when status is available." } }, "additionalProperties": true }, "TierStatus": { "type": "object", "description": "Availability/progress for an identity tier (pseudonymous through credential-verified).", "properties": { "status": { "type": "string", "description": "Tier state (e.g. active, available, locked)." }, "action_url": { "type": "string" } }, "additionalProperties": true }, "CapabilityGatedRequires": { "type": "object", "description": "Minimum identity tier and/or verification layer index required to unlock the gated capability. Omitted keys mean not applicable.", "properties": { "identity_tier": { "type": "integer", "description": "Required identity tier (0–3)." }, "layer": { "type": "integer", "description": "Required verification layer index when gating by layer." } }, "additionalProperties": false }, "CapabilityGatedItem": { "type": "object", "properties": { "capability": { "type": "string", "description": "Capability id / gate name (e.g. marketplace.publish)." }, "requires": { "$ref": "#/components/schemas/CapabilityGatedRequires" }, "message": { "type": "string", "description": "Human-readable reason the capability is gated." } }, "required": [ "capability", "requires", "message" ], "additionalProperties": false }, "PassportVerificationStatusResponse": { "type": "object", "description": "Validity Ladder snapshot: verification tier, identity tier, per-layer progress, identity tier progress, unlocked vs gated capabilities.", "properties": { "did": { "type": "string", "description": "Passport DID." }, "verification_tier": { "type": "integer", "description": "Current verification tier (Validity Ladder)." }, "identity_tier": { "type": "integer", "description": "Current identity tier." }, "layers": { "type": "object", "description": "Device attestation, biometric, social, and proof-of-personhood layer status.", "properties": { "device_attestation": { "$ref": "#/components/schemas/LayerStatus" }, "biometric_binding": { "$ref": "#/components/schemas/LayerStatus" }, "social_attestation": { "$ref": "#/components/schemas/LayerStatus" }, "proof_of_personhood": { "$ref": "#/components/schemas/LayerStatus" } }, "required": [ "device_attestation", "biometric_binding", "social_attestation", "proof_of_personhood" ], "additionalProperties": false }, "identity_tiers": { "type": "object", "description": "Pseudonymous through credential-verified tier progress.", "properties": { "pseudonymous": { "$ref": "#/components/schemas/TierStatus" }, "org_verified": { "$ref": "#/components/schemas/TierStatus" }, "kyc_verified": { "$ref": "#/components/schemas/TierStatus" }, "credential_verified": { "$ref": "#/components/schemas/TierStatus" } }, "required": [ "pseudonymous", "org_verified", "kyc_verified", "credential_verified" ], "additionalProperties": false }, "capabilities_unlocked": { "type": "array", "items": { "type": "string" }, "description": "Capability strings unlocked at the current tiers." }, "capabilities_gated": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityGatedItem" }, "description": "Capabilities not yet available, with requirements and messages." } }, "required": [ "did", "verification_tier", "identity_tier", "layers", "identity_tiers", "capabilities_unlocked", "capabilities_gated" ], "additionalProperties": false }, "OrgUsageDetails": { "type": "object", "description": "Per-organization compute spend vs plan cap for the current calendar month (cloud_metering_events aggregate).", "properties": { "org_did": { "type": "string", "description": "Organization DID (org_id in DB)." }, "plan_tier": { "type": "string", "description": "Plan tier (e.g. free, pro, business, enterprise)." }, "used_usd": { "type": "number", "description": "Total USD billed compute used this month." }, "included_usd": { "type": "number", "nullable": true, "description": "USD included in the plan tier cap; null when unlimited (enterprise)." }, "authorized_topup_usd": { "type": "number", "description": "USD from active compute_overage_authorizations (stacked on cap)." }, "ceiling_usd": { "type": "number", "nullable": true, "description": "included_usd + top-up when capped; null when unlimited." }, "used_pct": { "type": "integer", "description": "Rounded percentage of ceiling used (0 when unlimited)." }, "stage": { "type": "string", "description": "ok | warning (≥80%) | ceiling-hit (≥100%) | unlimited." } }, "required": [ "org_did", "plan_tier", "used_usd", "included_usd", "authorized_topup_usd", "ceiling_usd", "used_pct", "stage" ], "additionalProperties": false } }, "responses": { "Unauthorized": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "BadRequest": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "paths": { "/health": { "get": { "summary": "Check the platform's health status", "description": "The health endpoint provides a window into the current operational status of the HUMAN platform. By revealing the connectivity state and version details, it ensures transparency and builds trust with users, crucial for maintaining a robust and reliable Human-AI orchestration environment.", "operationId": "getHealthStatus", "tags": [ "Operations", "Monitoring" ], "x-code-hash": "df0b59e89172941b", "x-generated-at": "2026-03-31T03:38:37.597Z", "responses": { "200": { "description": "The platform is healthy and operational.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "database": { "type": "string", "enum": [ "connected" ] }, "version": { "type": "string" }, "commit": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "status", "database", "version", "timestamp" ] }, "examples": { "healthy_platform": { "summary": "Healthy Platform", "description": "Response indicating a fully operational platform with database connectivity.", "value": { "status": "ok", "database": "connected", "version": "1.2.3", "commit": "abc123def", "timestamp": "2023-10-02T12:34:56Z" } } } } } }, "500": { "description": "A server error occurred during the health check.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Response indicating an unexpected server error.", "value": { "type": "https://human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Unexpected error during health check. Please try again later or contact support if the issue persists." } } } } } }, "503": { "description": "The platform is experiencing issues, such as database connectivity problems.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_disconnected": { "summary": "Database Disconnected", "description": "Response when the database is disconnected.", "value": { "status": "error", "database": "disconnected", "version": "1.2.3", "commit": "abc123def", "timestamp": "2023-10-02T12:34:56Z" } }, "health_check_error": { "summary": "Health Check Error", "description": "Response when an error occurs during the health check.", "value": { "status": "error", "database": "error", "version": "1.2.3", "commit": "abc123def", "timestamp": "2023-10-02T12:34:56Z" } } } } } } } } }, "/.well-known/did.json": { "get": { "summary": "Resolve a DID for the HUMAN platform", "description": "Dive into the world of decentralized identities with the HUMAN platform's DID resolution endpoint. This service allows you to retrieve a well-defined DID Document, crucial for establishing verifiable digital identities. It's a gateway to ensuring trust and authenticity in a decentralized ecosystem, enabling seamless human-AI interaction.", "operationId": "resolveDidJsonWellKnown", "tags": [ "Identity", "DID" ], "x-code-hash": "7531d3628d3b86e6", "x-generated-at": "2026-03-23T02:49:25.432Z", "responses": { "200": { "description": "Successfully retrieved the DID Document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "@context": { "type": "string", "example": "https://www.w3.org/ns/did/v1" }, "id": { "type": "string", "example": "did:web:api.acme.com" }, "verificationMethod": { "type": "array", "items": { "type": "object" } }, "authentication": { "type": "array", "items": { "type": "object" } }, "service": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "did:web:api.acme.com#api" }, "type": { "type": "string", "example": "LinkedDomains" }, "serviceEndpoint": { "type": "string", "example": "https://api.acme.com" } } } } } }, "examples": { "default": { "summary": "Example", "description": "A DID Document for the Acme Corporation's API service", "value": { "@context": "https://www.w3.org/ns/did/v1", "id": "did:web:api.acme.com", "verificationMethod": [], "authentication": [], "service": [ { "id": "did:web:api.acme.com#api", "type": "LinkedDomains", "serviceEndpoint": "https://api.acme.com" } ] } } } } } }, "400": { "description": "Invalid request due to missing or incorrect DID parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "REQUIRED_FIELD_MISSING" }, "message": { "type": "string", "example": "DID query parameter is required when platform DID cannot be derived" }, "expected": { "type": "string", "example": "DID string or ?did=..." }, "received": { "type": "string", "example": "undefined" } } }, "examples": { "default": { "summary": "Example", "description": "The request lacks the necessary DID parameter.", "value": { "error": "REQUIRED_FIELD_MISSING", "message": "DID query parameter is required when platform DID cannot be derived", "expected": "DID string or ?did=...", "received": "undefined" } } } } } }, "404": { "description": "DID Document not found for the provided DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "DID_NOT_FOUND" }, "message": { "type": "string", "example": "No DID Document found for the provided DID" } } }, "examples": { "default": { "summary": "Example", "description": "No DID Document exists for the given identifier.", "value": { "error": "DID_NOT_FOUND", "message": "No DID Document found for the provided DID" } } } } } }, "500": { "description": "Internal server error encountered while resolving the DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INTERNAL_SERVER_ERROR" }, "incidentId": { "type": "string", "example": "inc_1697040595000" }, "message": { "type": "string", "example": "Failed to resolve DID" } } }, "examples": { "default": { "summary": "Example", "description": "A server-side error occurred during DID resolution.", "value": { "error": "INTERNAL_SERVER_ERROR", "incidentId": "inc_1697040595000", "message": "Failed to resolve DID" } } } } } } } } }, "/v1/system-capabilities": { "get": { "summary": "Retrieve System Capabilities Overview", "description": "Explore the dynamic landscape of your system's capabilities with this endpoint. As part of HUMAN's Capability Graph, it provides a comprehensive list of all defined actions, resources, and constraints, helping you understand and manage the skills within your distributed network. This is crucial for aligning your technological ecosystem with strategic goals.", "operationId": "getSystemCapabilities", "tags": [ "System", "Capabilities", "Control Plane" ], "x-code-hash": "c42bb1208f4a3535", "x-generated-at": "2026-03-24T22:23:16.838Z", "responses": { "200": { "description": "A detailed list of system capabilities, including their attributes and constraints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "resource_type": { "type": "string" }, "action": { "type": "string" }, "description": { "type": "string" }, "risk_level": { "type": "string" }, "constraints": { "type": "object" }, "version": { "type": "string" }, "locked": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" } } }, "examples": { "example_response": { "summary": "Example Response", "description": "An organization discovers its system capabilities to align with its strategic initiatives.", "value": { "capabilities": [ { "id": 1, "resource_type": "compute", "action": "provision", "description": "Provision a new computing resource.", "risk_level": "low", "constraints": { "max_instances": 5 }, "version": "1.0", "locked": false, "created_at": "2023-01-15T12:34:56Z", "updated_at": "2023-02-20T08:23:45Z" }, { "id": 2, "resource_type": "storage", "action": "allocate", "description": "Allocate additional storage capacity.", "risk_level": "medium", "constraints": { "max_storage": "100GB" }, "version": "1.1", "locked": true, "created_at": "2023-01-20T15:45:12Z", "updated_at": "2023-03-10T10:15:30Z" } ], "count": 2 } } } } } }, "400": { "description": "The request was malformed or missing necessary parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request": { "summary": "Malformed Request", "description": "Occurs when the request parameters are incorrect.", "value": { "type": "https://example.com/probs/malformed-request", "title": "Malformed Request", "status": 400, "detail": "The request could not be understood by the server due to incorrect syntax.", "errors": [ "Parameter 'xyz' is missing." ] } } } } } }, "401": { "description": "Authentication credentials were not provided or are invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Occurs when the user is not authenticated.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access denied due to invalid credentials. Please check your Passport and try again." } } } } } }, "403": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Occurs when the user lacks adequate permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the required permissions to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "The endpoint does not exist or was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found": { "summary": "Not Found", "description": "Occurs when the requested resource is not available.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested endpoint does not exist. Verify the URL and try again." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "Occurs due to an unexpected server issue.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_123456789." } } } } } } } } }, "/v1/ontology/packages": { "get": { "summary": "Retrieve curated ontology package list", "description": "Discover the universe of capabilities with this endpoint, which fetches a curated list of ontology packages. Ideal for developers and organizations aiming to leverage the HUMAN Protocol's power, it helps you navigate through the capabilities landscape by filtering packages by scope, publisher, and status.", "operationId": "getOntologyPackages", "tags": [ "Ontology", "Packages" ], "x-code-hash": "c3d34a8384ab0d8d", "x-generated-at": "2026-03-24T22:41:12.422Z", "responses": { "200": { "description": "A list of ontology packages matching the query criteria", "content": { "application/json": { "schema": { "type": "object", "properties": { "packages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "publisher": { "type": "object", "properties": { "did": { "type": "string" }, "name": { "type": "string" } } }, "name": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string" }, "license": { "type": "string" }, "capability_count": { "type": "integer" }, "status": { "type": "string" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "version", "publisher", "name", "description", "scope", "license", "capability_count", "status" ] } }, "count": { "type": "integer" } }, "required": [ "packages", "count" ] }, "examples": { "successful_retrieval_of_ontology_packages": { "summary": "Successful retrieval of ontology packages", "description": "Retrieve a list of published ontology packages for acme organization.", "value": { "packages": [ { "id": "pkg_1234", "version": "1.0.0", "publisher": { "did": "did:human:acme", "name": "Acme Corp" }, "name": "Invoice Processing", "description": "A package for processing invoices with advanced AI capabilities.", "scope": "org", "license": "MIT", "capability_count": 5, "status": "published", "published_at": "2023-10-15T12:34:56Z" } ], "count": 1 } } } } } }, "400": { "description": "Invalid query parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_status_parameter": { "summary": "Invalid status parameter", "description": "The status parameter provided is invalid.", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid Query Parameter", "status": 400, "detail": "The status parameter must be 'published', 'draft', or 'archived'.", "errors": [ "Invalid 'status' value provided: 'completed'" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_token": { "summary": "Missing authentication token", "description": "The request lacks a valid authentication token.", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication token is missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied_to_resource": { "summary": "Access denied to resource", "description": "The user does not have permission to access the requested resource.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ontology_package_not_found": { "summary": "Ontology package not found", "description": "The requested ontology package could not be found.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The ontology package you are looking for does not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "The server encountered an unexpected error.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An internal error occurred, preventing the request from being fulfilled." } } } } } } } }, "post": { "summary": "Publish a new ontology package", "description": "In the vibrant world of Human-AI collaboration, the tools we utilize must evolve. This endpoint allows you to publish a new ontology package, a cornerstone for skill tracking and capability management. By enabling organizations to define and share their ontology structures, it fosters a rich ecosystem of knowledge and collaboration.", "operationId": "publishOntologyPackage", "tags": [ "Ontology", "Capability Graph" ], "x-code-hash": "38240717098c98c0", "x-generated-at": "2026-03-24T22:42:52.560Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "version", "publisher_name", "name", "signature", "manifest_json", "scope", "license" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the ontology package." }, "version": { "type": "string", "description": "Semantic versioning of the package." }, "publisher_name": { "type": "string", "description": "Name of the publisher." }, "name": { "type": "string", "description": "Name of the ontology package." }, "signature": { "type": "string", "description": "Cryptographic signature of the package." }, "manifest_json": { "type": "object", "description": "JSON object detailing the package manifest." }, "scope": { "type": "string", "enum": [ "canonical", "org" ], "description": "Scope of the package." }, "license": { "type": "string", "enum": [ "open", "commercial", "proprietary" ], "description": "License type for the package." }, "org_slug": { "type": "string", "description": "Organization slug when scope is 'org'." }, "description": { "type": "string", "description": "Optional description of the package." }, "changelog": { "type": "string", "description": "Optional changelog for the package." }, "price_amount": { "type": "number", "description": "Price amount for the package." }, "price_currency": { "type": "string", "description": "Currency for the price." }, "price_billing_period": { "type": "string", "enum": [ "one-time", "annual", "monthly" ], "description": "Billing period for the price." } } }, "examples": { "acme_ontology_package": { "summary": "Acme Ontology Package", "description": "Publishing a new ontology package for Acme Corp.", "value": { "id": "acme-ontology-v1", "version": "1.0.0", "publisher_name": "Acme Corp", "name": "Acme Ontology", "signature": "a1b2c3signature", "manifest_json": { "capabilities": [ "capability://data.processing", "capability://ai.modeling" ] }, "scope": "org", "license": "commercial", "org_slug": "acme", "description": "Ontology package for processing and modeling data.", "changelog": "Initial release.", "price_amount": 199.99, "price_currency": "USD", "price_billing_period": "annual" } } } } } }, "responses": { "201": { "description": "The ontology package was successfully published.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the published package." }, "version": { "type": "string", "description": "Version of the published package." }, "name": { "type": "string", "description": "Name of the published package." }, "scope": { "type": "string", "description": "Scope of the published package." }, "license": { "type": "string", "description": "License of the published package." }, "status": { "type": "string", "description": "Status of the package." }, "publisher": { "type": "object", "properties": { "did": { "type": "string", "description": "DID of the publisher." }, "name": { "type": "string", "description": "Name of the publisher." } } }, "capability_count": { "type": "integer", "description": "Number of capabilities in the package." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "published_at": { "type": "string", "format": "date-time", "description": "Publishing timestamp." } } }, "examples": { "default": { "summary": "Example", "value": { "id": "acme-ontology-v1", "version": "1.0.0", "name": "Acme Ontology", "scope": "org", "license": "commercial", "status": "published", "publisher": { "did": "did:example:123456789", "name": "Acme Corp" }, "capability_count": 2, "created_at": "2023-10-04T00:00:00Z", "published_at": "2023-10-04T00:00:00Z" } } } } } }, "400": { "description": "The request was invalid due to missing or incorrect data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Validation errors occurred.", "errors": [ { "field": "id", "code": "REQUIRED_FIELD_MISSING", "message": "id is required", "expected": "ontology package id string", "received": "null" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please authenticate and retry." } } } } } }, "403": { "description": "The user does not have the necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "Publishing canonical ontology packages requires human_api:capabilities:create:canonical permission." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The ontology package you are attempting to publish does not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Incident ID: inc_1633550400" } } } } } } } } }, "/v1/ontology/packages/:id": { "get": { "summary": "Retrieve ontology package metadata", "description": "Uncover the complete lineage and evolution of an ontology package with this endpoint. It provides a detailed account of all versions of a specified package, allowing users to trace its history and understand its development over time. This is crucial for tracking capability changes and ensuring compliance with evolving standards.", "operationId": "getOntologyPackageById", "tags": [ "Ontology", "Packages" ], "x-code-hash": "ccbf48557be16bef", "x-generated-at": "2026-03-24T22:42:14.247Z", "responses": { "200": { "description": "Successfully retrieved ontology package metadata, including all available versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "version_count": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "publisher": { "type": "object", "properties": { "did": { "type": "string" }, "name": { "type": "string" } } }, "scope": { "type": "string" }, "license": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "publisher": { "type": "object", "properties": { "did": { "type": "string" }, "name": { "type": "string" } } }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "license": { "type": "string" }, "pricing": { "type": [ "object", "null" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "billing_period": { "type": "string" } } }, "capability_count": { "type": "integer" }, "status": { "type": "string" }, "changelog": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "examples": { "successful_ontology_package_retrieval": { "summary": "Successful ontology package retrieval", "description": "Retrieve detailed metadata for the 'acme' organization's package with all versions.", "value": { "id": "pkg_12345", "version_count": 3, "name": "Acme Invoice Ontology", "description": "An ontology package for processing invoices in the Acme organization.", "publisher": { "did": "did:human:acme123", "name": "Acme Corp" }, "scope": "invoices", "license": "MIT", "versions": [ { "version": "1.0.0", "publisher": { "did": "did:human:acme123", "name": "Acme Corp" }, "name": "Acme Invoice Ontology", "description": "Initial release with basic invoice processing capabilities.", "scope": "invoices", "license": "MIT", "pricing": null, "capability_count": 5, "status": "active", "changelog": "Initial release.", "created_at": "2023-01-15T10:00:00Z", "published_at": "2023-01-16T10:00:00Z" }, { "version": "1.1.0", "publisher": { "did": "did:human:acme123", "name": "Acme Corp" }, "name": "Acme Invoice Ontology", "description": "Added support for multi-currency invoices.", "scope": "invoices", "license": "MIT", "pricing": null, "capability_count": 7, "status": "active", "changelog": "Added multi-currency support.", "created_at": "2023-02-01T10:00:00Z", "published_at": "2023-02-02T10:00:00Z" } ] } } } } } }, "400": { "description": "Bad Request - The request could not be understood or was missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_package_id": { "summary": "Missing package id", "description": "The request failed because the package ID was not provided.", "value": { "type": "https://example.com/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Package id is required", "errors": [ { "field": "id", "code": "INVALID_VALUE", "message": "Package id is required", "expected": "non-empty ontology package id", "received": "" } ] } } } } } }, "404": { "description": "Not Found - No ontology package matches the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "package_not_found": { "summary": "Package not found", "description": "The specified ontology package ID does not exist.", "value": { "type": "https://example.com/problems/not-found", "title": "Ontology Package Not Found", "status": 404, "detail": "No ontology package found with ID 'pkg_12345'." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://example.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Incident ID: inc_1695783678123" } } } } } } } } }, "/v1/ontology/packages/:id/:version": { "get": { "summary": "Retrieve Ontology Package Details", "description": "Delve into the rich tapestry of skills and capabilities with our ontology packages. This endpoint grants you access to the intricate details of a specific ontology package version, including its publisher, licensing, and capabilities. Ideal for orchestrating human expertise and AI synergy.", "operationId": "getOntologyPackageDetails", "tags": [ "Ontology", "Packages" ], "x-code-hash": "1ef016ea8dba2312", "x-generated-at": "2026-03-24T22:41:52.449Z", "responses": { "200": { "description": "Successfully retrieved the ontology package details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the package." }, "version": { "type": "string", "description": "Version of the ontology package." }, "publisher": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier of the publisher." }, "name": { "type": "string", "description": "Name of the publisher." } } }, "name": { "type": "string", "description": "Name of the ontology package." }, "description": { "type": "string", "description": "Detailed description of the package." }, "scope": { "type": "string", "description": "Scope of the package's applicability." }, "license": { "type": "string", "description": "Licensing terms of the package." }, "pricing": { "type": "object", "nullable": true, "properties": { "amount": { "type": "number", "description": "Price amount." }, "currency": { "type": "string", "description": "Currency of the price." }, "billing_period": { "type": "string", "description": "Billing period for the price." } } }, "capability_count": { "type": "integer", "description": "Number of capabilities included." }, "status": { "type": "string", "description": "Current status of the package." }, "changelog": { "type": "string", "nullable": true, "description": "Recent changes in the package." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "published_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Publishing timestamp." } } }, "examples": { "ontology_package_details_example": { "summary": "Ontology Package Details Example", "description": "Retrieving details for an active ontology package used by Acme Corp.", "value": { "id": "pkg_001", "version": "1.0.3", "publisher": { "did": "did:example:123456789abcdefghi", "name": "Acme Corp" }, "name": "Invoice Processing Ontology", "description": "A comprehensive package for processing invoices with AI assistance.", "scope": "Finance", "license": "MIT", "pricing": { "amount": 199.99, "currency": "USD", "billing_period": "annual" }, "capability_count": 10, "status": "active", "changelog": "Added new capabilities for multi-currency support.", "created_at": "2023-01-15T08:00:00Z", "published_at": "2023-02-10T09:30:00Z" } } } } } }, "400": { "description": "Bad Request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_id_format": { "summary": "Invalid ID Format", "description": "The provided package ID was malformed.", "value": { "type": "https://example.com/problems/invalid-id", "title": "Invalid Package ID", "status": 400, "detail": "The package ID 'pkg_@@!' is not valid. Please use a valid alphanumeric ID.", "errors": [ "ID must be alphanumeric." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "An attempt to access the endpoint without authentication.", "value": { "type": "https://example.com/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access this resource. Provide valid credentials and try again." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "User does not have permission to view this package.", "value": { "type": "https://example.com/problems/insufficient-permissions", "title": "Access Denied", "status": 403, "detail": "You do not have permission to access package 'pkg_001'. Please contact your administrator for access." } } } } } }, "404": { "description": "Ontology package not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "package_not_found": { "summary": "Package Not Found", "description": "No ontology package found for the specified ID and version.", "value": { "type": "https://example.com/problems/not-found", "title": "Ontology Package Not Found", "status": 404, "detail": "The ontology package with ID 'pkg_999' and version '1.0.0' was not found. Ensure the ID and version are correct." } } } } } }, "500": { "description": "Internal Server Error due to unforeseen circumstances.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://example.com/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID inc_1697045043562." } } } } } } } } }, "/v1/orgs/:orgId/ontologies": { "get": { "summary": "Retrieve ontologies for an organization", "description": "Explore the semantic fabric of your organization by retrieving a list of ontologies. These ontologies, intricately woven by the hands of knowledge engineers, serve as the backbone for task orchestration and AI empowerment within your organization. Discover which ontologies are active and who initiated their installation.", "operationId": "getOrgOntologies", "tags": [ "Organization", "Ontology" ], "x-code-hash": "bf2d162e203e0c65", "x-generated-at": "2026-03-27T15:33:51.136Z", "responses": { "200": { "description": "Successfully retrieved the list of ontologies for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "description": "The unique identifier of the organization." }, "installations": { "type": "array", "items": { "type": "object", "properties": { "installation_id": { "type": "string", "description": "Unique identifier for the ontology installation." }, "package_id": { "type": "string", "description": "Identifier of the ontology package." }, "package_version": { "type": "string", "description": "Version of the ontology package." }, "name": { "type": "string", "description": "Human-readable name of the ontology package." }, "description": { "type": "string", "description": "Detailed description of the ontology package." }, "capability_count": { "type": "integer", "description": "Number of capabilities included in the package." }, "installed_by": { "type": "string", "description": "Identifier of the user who installed the ontology." }, "installed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the ontology was installed." }, "status": { "type": "string", "description": "Current status of the ontology installation." } } } }, "count": { "type": "integer", "description": "Total number of ontology installations retrieved." } } }, "examples": { "acme_corp_ontologies": { "summary": "Acme Corp Ontologies", "description": "Fetching active ontologies for Acme Corp.", "value": { "org_id": "acme-corp", "installations": [ { "installation_id": "inst-001", "package_id": "pkg-123", "package_version": "1.0.0", "name": "Invoice Processing Ontology", "description": "Enhances invoice data extraction and processing.", "capability_count": 5, "installed_by": "user-42", "installed_at": "2023-10-05T14:48:00.000Z", "status": "active" } ], "count": 1 } } } } } }, "400": { "description": "Invalid request due to malformed input or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_id": { "summary": "Missing Org ID", "description": "Request without required organization ID.", "value": { "type": "https://developer.human/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The organization ID is missing. Please provide a valid orgId in the path." } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_authentication_token": { "summary": "No Authentication Token", "description": "Attempt to fetch ontologies without authentication.", "value": { "type": "https://developer.human/probs/authentication-failure", "title": "Authentication Failed", "status": 401, "detail": "Authentication token is missing. Please provide a valid token to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "User lacks permissions to view ontologies.", "value": { "type": "https://developer.human/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have the necessary permissions to access this organization's ontologies. Contact your administrator for more information." } } } } } }, "404": { "description": "The specified organization or ontology could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "nonexistent_organization": { "summary": "Nonexistent Organization", "description": "Organization ID does not match any records.", "value": { "type": "https://developer.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization with ID 'unknown-org' was not found. Please verify the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Generic server-side error.", "value": { "type": "https://developer.human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/delegation-tokens": { "post": { "summary": "Create a delegation token for access control", "description": "In the intricate dance of human and AI collaboration, the Delegation Token is your backstage pass. It empowers entities to act on behalf of others, streamlining operations without sacrificing security. This endpoint creates a token, ensuring trusted interactions across the HUMAN platform.", "operationId": "createDelegationToken", "tags": [ "Identity", "Security" ], "x-code-hash": "293da4bdb68213ef", "x-generated-at": "2026-03-24T22:43:12.082Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delegate": { "type": "string", "description": "The DID of the delegate requesting access." }, "capabilities": { "type": "array", "items": { "type": "string", "description": "Capabilities to be granted, formatted as capability:// URIs." } }, "expiresIn": { "type": "integer", "description": "Time in seconds until the token expires." } }, "required": [ "delegate", "capabilities" ] }, "examples": { "delegate_access_to_invoice_processing": { "summary": "Delegate access to invoice processing", "description": "This example shows how to delegate invoice processing capabilities to an AI agent within the 'acme' organization.", "value": { "delegate": "did:human:agent-12345", "capabilities": [ "capability://invoice.process", "capability://invoice.view" ], "expiresIn": 3600 } } } } } }, "responses": { "200": { "description": "A successful response returns the new delegation token, allowing the delegate to perform specified actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The generated delegation token." }, "expiresAt": { "type": "string", "format": "date-time", "description": "The timestamp when the token will expire." } } }, "examples": { "default": { "summary": "Example", "value": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresAt": "2023-10-15T10:00:00Z" } } } } } }, "400": { "description": "Bad Request - The request was malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'delegate' field is required.", "errors": [ { "field": "delegate", "message": "This field cannot be empty." } ] } } } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden - The operation is not permitted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Not Found - The resource does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified delegate could not be found." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "summary": "List Issuer Delegation Tokens", "description": "Retrieve a curated list of delegation tokens issued by or to your identity, enabling seamless management of access permissions. This endpoint empowers you to monitor and manage the lifecycle of delegation tokens, ensuring your digital interactions are secure and traceable.", "operationId": "getDelegationTokens", "tags": [ "Identity Management", "Delegation" ], "x-code-hash": "ba59c2319d39779a", "x-generated-at": "2026-03-24T22:43:31.472Z", "responses": { "200": { "description": "A paginated list of active delegation tokens associated with the issuer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "delegation_id": { "type": "string", "description": "Unique identifier for the delegation." }, "token_id": { "type": "string", "description": "Unique identifier for the token." }, "scope": { "type": "array", "items": { "type": "string" }, "description": "List of scopes granted by this token." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the token expires." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the token was created." }, "last_used_at": { "type": "string", "format": "date-time", "description": "Timestamp when the token was last used." } }, "required": [ "delegation_id", "token_id" ] } }, "limit": { "type": "integer", "description": "Maximum number of tokens returned in this response." }, "hasMore": { "type": "boolean", "description": "Indicates if more tokens are available beyond this response." } } }, "examples": { "successful_token_list_retrieval": { "summary": "Successful Token List Retrieval", "description": "An example of retrieving a list of delegation tokens for issuer 'acme'.", "value": { "data": [ { "delegation_id": "del_123456789", "token_id": "tok_987654321", "scope": [ "read", "write" ], "expires_at": "2023-12-31T23:59:59Z", "created_at": "2023-01-01T12:00:00Z", "last_used_at": "2023-01-15T08:00:00Z" } ], "limit": 10, "hasMore": false } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_limit_parameter": { "summary": "Malformed Limit Parameter", "description": "Occurs when the 'limit' query parameter is not a positive integer.", "value": { "type": "/problems/bad-request", "title": "Bad Request", "status": 400, "detail": "The 'limit' parameter must be a positive integer." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing Delegation Context", "description": "Occurs when the request lacks the necessary delegation context for authentication.", "value": { "type": "/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context. Please authenticate with a valid DID Passport." } } } } } }, "403": { "description": "Forbidden access when the issuer does not have permission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "Occurs when the user attempts to access tokens they do not own.", "value": { "type": "/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these tokens." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "Occurs when the system encounters an unknown error during processing.", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/device/code": { "post": { "summary": "Initiate device code authorization flow", "description": "Embark on a secure journey to connect devices through cryptographic identity with the HUMAN platform. This endpoint enables applications to request a device code for device authorization, ensuring only verified devices can access protected resources.", "operationId": "postPassportDeviceCode", "tags": [ "Authentication", "DeviceFlow" ], "x-code-hash": "0d8f0c9d2af0950c", "x-generated-at": "2026-04-11T01:54:09.656Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The unique identifier for the client application." }, "scope": { "type": "string", "description": "Space-delimited OAuth scopes requested by the client." } }, "required": [ "client_id", "scope" ] }, "examples": { "valid_device_authorization_request": { "summary": "Valid Device Authorization Request", "description": "A typical request from the 'acme' organization to authorize a new device for processing invoices.", "value": { "client_id": "acme-device-client", "scope": "invoice:read invoice:write" } } } } } }, "responses": { "200": { "description": "Device and user codes generated successfully for verification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string", "description": "The code to be used by the device for authorization." }, "user_code": { "type": "string", "description": "A user-friendly code shown to the user for verification." }, "verification_uri": { "type": "string", "description": "The URI where the user enters the user_code." }, "verification_uri_complete": { "type": "string", "description": "A complete URI including the user_code for seamless verification." }, "expires_in": { "type": "integer", "description": "Time in seconds until the device code expires." }, "interval": { "type": "integer", "description": "Polling interval in seconds for checking authorization status." } } }, "examples": { "default": { "summary": "Example", "value": { "device_code": "abc123xyz", "user_code": "1234-5678", "verification_uri": "https://verify.humanprotocol.org", "verification_uri_complete": "https://verify.humanprotocol.org?user_code=1234-5678", "expires_in": 600, "interval": 5 } } } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden - Client not permitted to request device code", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found - The requested resource could not be found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/passport/device/token": { "post": { "summary": "Exchange device code for access token", "description": "In the heart of HUMAN's secure ecosystem, this endpoint transforms a granted device code into a powerful access token. It ensures devices can autonomously authenticate while maintaining strict access controls, empowering seamless Human-AI interactions.", "operationId": "exchangeDeviceCodeForToken", "tags": [ "Authentication", "Device Flow" ], "x-code-hash": "15e2ddbc1b9b0820", "x-generated-at": "2026-04-11T01:54:21.392Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:device_code" ], "description": "The OAuth grant type for device code exchange" }, "device_code": { "type": "string", "description": "The device code obtained from the device authorization request" }, "client_id": { "type": "string", "description": "The client identifier for the device" } }, "required": [ "grant_type", "device_code", "client_id" ] }, "examples": { "standard_device_code_exchange": { "summary": "Standard Device Code Exchange", "description": "A typical request to exchange a device code for an access token", "value": { "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "123456", "client_id": "acme_device_client" } } } } } }, "responses": { "200": { "description": "Successfully exchanged device code for an access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The access token granted to the device" }, "token_type": { "type": "string", "description": "Type of the token issued, typically 'Bearer'" }, "expires_in": { "type": "integer", "description": "The number of seconds until the access token expires" }, "refresh_token": { "type": "string", "description": "A token to refresh the access token" }, "scope": { "type": "string", "description": "The scope of access granted by the token" } } }, "examples": { "default": { "summary": "Example", "value": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "dtr_abc123xyz987", "scope": "read write" } } } } } }, "400": { "description": "Bad request due to invalid input or state", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/errors/invalid_request", "title": "Invalid Request", "status": 400, "detail": "Device code and client_id are required. Ensure both fields are provided in the request." } } } } } }, "401": { "description": "Unauthorized access attempt", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "The provided credentials do not authorize this request." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not found error when device code is invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/errors/not_found", "title": "Not Found", "status": 404, "detail": "The device code provided does not exist or has expired. Please verify and try again." } } } } } }, "500": { "description": "Internal server error during token issuance", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/errors/internal_server_error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/passport/device/confirm": { "post": { "summary": "Confirm device authorization with user code", "description": "In the world of distributed identity, confirming a device's authorization is crucial for seamless access. This endpoint allows a device to authenticate using a unique user code, ensuring that only trusted devices can operate within the HUMAN ecosystem. It's a vital step in maintaining the security and integrity of digital identities.", "operationId": "confirmDeviceAuthorization", "tags": [ "Identity", "Device Management" ], "x-code-hash": "8770120df88bb516", "x-generated-at": "2026-04-11T01:54:32.903Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_code": { "type": "string", "description": "A unique code to verify the device, formatted as XXXX-XXXX.", "example": "WDJB-MJHT" } }, "required": [ "user_code" ] }, "examples": { "valid_user_code": { "summary": "Valid User Code", "description": "A typical request with a correctly formatted user code.", "value": { "user_code": "WDJB-MJHT" } } } } } }, "responses": { "200": { "description": "Device authorization confirmed successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_code": { "type": "string", "example": "WDJB-MJHT" }, "status": { "type": "string", "example": "approved" }, "subject_did": { "type": "string", "description": "Decentralized Identifier (DID) of the subject who authorized the device.", "example": "did:example:123456789abcdefghi" } } }, "examples": { "default": { "summary": "Example", "value": { "user_code": "WDJB-MJHT", "status": "approved", "subject_did": "did:example:123456789abcdefghi" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "The request body must be valid JSON and include a 'user_code'.", "errors": [ { "field": "user_code", "code": "INVALID_VALUE", "message": "user_code must look like WDJB-MJHT", "expected": "string XXXX-XXXX", "received": "WDJ-MJHT" } ] } } } } } }, "401": { "description": "Authentication required or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must authenticate before accessing this resource." } } } } } }, "403": { "description": "User code is either unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authorization-error", "title": "Authorization Error", "status": 403, "detail": "The user code provided is either unknown or has expired." } } } } } }, "500": { "description": "Unexpected error during device confirmation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/tokens": { "post": { "summary": "Create Personal Access Token", "description": "Generate a secure Personal Access Token (PAT) to authenticate and authorize specific capabilities on the HUMAN platform. This enables users to define scopes for their tokens, ensuring precise skill delegation and operational security.", "operationId": "createPersonalAccessToken", "tags": [ "Authentication", "Tokens" ], "x-code-hash": "fe9ec7b8c2869ae3", "x-generated-at": "2026-04-11T01:53:32.856Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Descriptive name for the token" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Array of capability URIs defining the token's permissions" }, "expires_in": { "type": "string", "description": "Duration before the token expires, e.g., '1h', '30m'" }, "risk_level": { "type": "string", "enum": [ "low", "standard", "high" ], "description": "Risk level associated with the token" }, "environment": { "type": "string", "enum": [ "dev", "staging", "production" ], "description": "Environment where the token is valid" } }, "required": [ "name", "scopes" ] }, "examples": { "basic_token_creation": { "summary": "Basic Token Creation", "description": "Creating a token with read-only access for development environment", "value": { "name": "Dev Read-Only Token", "scopes": [ "capability://read" ], "expires_in": "1h", "risk_level": "low", "environment": "dev" } } } } } }, "responses": { "201": { "description": "Token successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "token_id": { "type": "string", "description": "Unique identifier for the created token" }, "token": { "type": "string", "description": "The actual Personal Access Token" }, "name": { "type": "string", "description": "Name of the token" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes assigned to the token" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the token was created" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration timestamp of the token" } } }, "examples": { "successful_token_creation": { "summary": "Successful Token Creation", "value": { "token_id": "tok_1234567890", "token": "HPAT_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "name": "Dev Read-Only Token", "scopes": [ "capability://read" ], "created_at": "2023-10-31T12:34:56Z", "expires_at": "2023-10-31T13:34:56Z" } } } } } }, "400": { "description": "Invalid request body", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_fields": { "summary": "Missing Fields", "value": { "type": "https://example.com/probs/required-field-missing", "title": "Validation Error", "status": 400, "detail": "One or more required fields are missing or invalid.", "errors": [ { "field": "name", "code": "REQUIRED_FIELD_MISSING", "message": "Token name is required", "expected": "non-empty string", "received": "undefined" }, { "field": "scopes", "code": "REQUIRED_FIELD_MISSING", "message": "At least one scope is required", "expected": "string[]", "received": "empty array" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization token is missing or invalid." } } } } } }, "403": { "description": "Forbidden operation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create tokens in this environment." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "endpoint_not_found": { "summary": "Endpoint Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested endpoint does not exist." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve API Delegation Tokens", "description": "Explore the world of digital credentials by retrieving a list of API delegation tokens tied to your cryptographic identity. This endpoint empowers organizations like 'Acme Corp' to manage and audit their delegation tokens effortlessly, ensuring secure and traceable operations in a distributed ledger environment.", "operationId": "getPassportTokens", "tags": [ "Passport", "Tokens" ], "x-code-hash": "b2ece282d113aea8", "x-generated-at": "2026-04-11T01:53:44.260Z", "responses": { "200": { "description": "A paginated list of active delegation tokens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "token_id": { "type": "string" }, "delegation_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "token_id", "delegation_id" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorField", "hasMore" ] }, "examples": { "acme_corp_tokens": { "summary": "Acme Corp Tokens", "description": "A snapshot of Acme Corp's active API delegation tokens.", "value": { "data": [ { "token_id": "abc123", "delegation_id": "def456", "name": "Acme Invoice Processor", "scopes": [ "invoice:read", "invoice:write" ], "expires_at": "2024-12-31T23:59:59Z", "created_at": "2023-01-01T00:00:00Z", "last_used_at": "2023-10-01T12:34:56Z" } ], "limit": 10, "cursorField": "created_at", "hasMore": false } } } } } }, "400": { "description": "Invalid query parameters were provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "description": "The request contained an invalid 'limit' parameter.", "value": { "type": "https://humanprotocol.org/docs/errors/invalid-query-parameter", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ "limit" ] } } } } } }, "401": { "description": "Authentication context is missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing Delegation Context", "description": "The request was missing the necessary delegation context.", "value": { "type": "https://humanprotocol.org/docs/errors/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Missing delegation context. Ensure your authentication token includes the necessary delegation information." } } } } } }, "403": { "description": "Permission denied due to insufficient privileges.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_privileges": { "summary": "Insufficient Privileges", "description": "The requester does not have permission to access the tokens.", "value": { "type": "https://humanprotocol.org/docs/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have the required permissions to view these tokens. Please check your access rights." } } } } } }, "404": { "description": "No tokens were found matching the query.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_tokens_found": { "summary": "No Tokens Found", "description": "No tokens matched the search criteria.", "value": { "type": "https://humanprotocol.org/docs/errors/not-found", "title": "Not Found", "status": 404, "detail": "No delegation tokens were found for the specified query." } } } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An internal server error occurred.", "value": { "type": "https://humanprotocol.org/docs/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with error code inc_123456789." } } } } } } } } }, "/v1/passport/tokens/:token_id": { "delete": { "summary": "Revoke Passport Token by ID", "description": "This endpoint gracefully revokes a specific passport token, ensuring it no longer grants access or capabilities. It's crucial for maintaining the integrity and security of the HUMAN ecosystem, as it allows users to effectively manage and revoke permissions when necessary.", "operationId": "revokePassportTokenById", "tags": [ "Passport", "Security" ], "x-code-hash": "44699c47606454a2", "x-generated-at": "2026-04-11T01:53:55.292Z", "responses": { "204": { "description": "The token was successfully revoked, ensuring it can no longer be used for authentication.", "content": { "application/json": { "examples": { "successful_revocation": { "summary": "Successful Revocation", "description": "Successfully revoking a passport token for an organization.", "value": null } } } } }, "400": { "description": "The request was malformed, typically due to missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_token_id": { "summary": "Missing Token ID", "description": "A request failed because the token ID was missing.", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Parameters", "status": 400, "detail": "Token ID is required and must be a non-empty string.", "errors": [ { "field": "token_id", "code": "REQUIRED_FIELD_MISSING", "message": "Token id is required.", "expected": "non-empty string", "received": "undefined" } ] } } } } } }, "401": { "description": "The request lacked proper authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "Attempt to revoke a token without authentication.", "value": { "type": "https://example.com/probs/authentication", "title": "Authentication Error", "status": 401, "detail": "Missing delegation context." } } } } } }, "404": { "description": "The specified token was not found, indicating it may already be revoked or never existed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "token_not_found": { "summary": "Token Not Found", "description": "A request to revoke a non-existent token.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "No delegation token found with the specified ID." } } } } } }, "500": { "description": "An unexpected error occurred on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "A server-side issue prevented the revocation of a token.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with the incident ID inc_1234567890." } } } } } } } } }, "/v1/passport/activity": { "get": { "summary": "Retrieve Passport Holder's Activity Feed", "description": "Explore the vibrant tapestry of a passport holder's digital journey through their activity feed. This endpoint offers a glimpse into the events that shape their online interactions, ensuring that sensitive information is filtered with precision, reflecting the orchestration between human discretion and AI insight.", "operationId": "getPassportActivity", "tags": [ "Passport", "Activity" ], "x-code-hash": "e6d1d3a45bb13e10", "x-generated-at": "2026-04-11T01:52:52.625Z", "responses": { "200": { "description": "Returns the filtered activity log for the authenticated passport holder.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "actor_did": { "type": "string" }, "connector_id": { "type": "string" }, "risk_level": { "type": "string" } }, "required": [ "event_type", "timestamp" ] } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "required": [ "data", "hasMore" ] }, "examples": { "fetching_activity_for_a_tech_enthusiast": { "summary": "Fetching Activity for a Tech Enthusiast", "description": "The 'acme' organization views the activity feed of a passport holder detailing different event types, actors, and connectors.", "value": { "data": [ { "event_type": "grant.created", "timestamp": "2023-10-01T12:34:56Z", "actor_did": "did:human:1234", "connector_id": "con_456", "risk_level": "low" }, { "event_type": "delegation.used", "timestamp": "2023-09-29T10:30:00Z", "actor_did": "did:human:5678", "connector_id": "con_789", "risk_level": "medium" } ], "hasMore": true, "nextCursor": "cursor_abc123" } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_date_range": { "summary": "Invalid Date Range", "description": "The user provided an incorrect date range for the query parameters.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid request parameters", "status": 400, "detail": "The 'from' date must be earlier than the 'to' date.", "errors": [ { "field": "from", "code": "INVALID_DATE", "message": "Start date is after end date.", "expected": "ISO8601 date before 'to' date", "received": "2023-10-05" } ] } } } } } }, "401": { "description": "Authentication required to access the activity feed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request was made without the necessary passport authentication.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport authentication required to access this resource." } } } } } }, "403": { "description": "Insufficient permissions to access the requested activity feed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user does not have the required permissions to view the activity feed.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this activity feed." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server-side issue prevented the activity feed from being retrieved.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please retry later. Incident ID: inc_1634567890" } } } } } } } } }, "/v1/passport/activity/:event_id": { "get": { "summary": "Retrieve a specific activity event", "description": "Dive into the story of a particular event within your cryptographic identity's history on the HUMAN platform. This endpoint is your gateway to verifying the authenticity and details of an activity, complete with a receipt that ensures its linkage proof. It's all about ensuring trust in every interaction.", "operationId": "getPassportActivityEvent", "tags": [ "Passport", "Activity" ], "x-code-hash": "605c8e4ef6bf4dd6", "x-generated-at": "2026-04-11T01:53:05.261Z", "responses": { "200": { "description": "Returns the activity event details with proof linkage", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Unique identifier for the activity event" }, "subject_did": { "type": "string", "description": "Decentralized identifier of the event owner" }, "activity_type": { "type": "string", "description": "Type of activity recorded" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the activity occurred" }, "details": { "type": "object", "description": "Additional event-specific details" }, "receipt": { "type": "string", "description": "Cryptographic receipt proving the event linkage" } }, "required": [ "event_id", "subject_did", "activity_type", "timestamp", "receipt" ] }, "examples": { "typical_activity_event": { "summary": "Typical Activity Event", "description": "An example of a successfully retrieved activity event", "value": { "event_id": "evt_123456", "subject_did": "did:human:acme_1234", "activity_type": "DOCUMENT_SIGNED", "timestamp": "2023-10-05T14:48:00Z", "details": { "document_id": "doc_7890", "signature_method": "ECDSA" }, "receipt": "abc123def456ghi789" } } } } } }, "400": { "description": "Invalid request due to malformed parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_event_id": { "summary": "Malformed Event ID", "description": "Example of a malformed event ID leading to request failure", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The event_id parameter is incorrectly formatted. Ensure it is a valid string identifier." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "No authentication provided, resulting in an error", "value": { "type": "https://docs.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport authentication required. Please provide a valid passport token." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Attempt to access an activity event without proper permissions", "value": { "type": "https://docs.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this activity event. Ensure you are the owner." } } } } } }, "404": { "description": "Activity event not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "event_not_found": { "summary": "Event Not Found", "description": "The specified activity event was not found", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The activity event with the specified event_id does not exist. Verify the event_id and try again." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "A server error occurred while processing the request", "value": { "type": "https://docs.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/delegation-tokens/:id": { "get": { "summary": "Retrieve Delegation Token Details", "description": "Uncover the secrets of delegation by fetching detailed information about a specific delegation token. This endpoint empowers you to navigate the intricacies of digital identity and access control, ensuring that every interaction is securely tracked and validated through the HUMAN platform.", "operationId": "getDelegationTokenDetails", "tags": [ "Delegation", "IdentityManagement" ], "x-code-hash": "24a8eb59284031d0", "x-generated-at": "2026-03-24T22:44:23.122Z", "responses": { "200": { "description": "Successfully retrieved the delegation token details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_id": { "type": "string", "description": "Unique identifier for the delegation." }, "token_id": { "type": "string", "description": "Unique identifier for the token." }, "scope": { "type": "array", "items": { "type": "string" }, "description": "The scopes granted by this delegation." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the token is set to expire." }, "created_at": { "type": "string", "format": "date-time", "description": "When the token was created." }, "last_used_at": { "type": "string", "format": "date-time", "description": "The last time the token was used." }, "revoked_at": { "type": "string", "format": "date-time", "description": "When the token was revoked, if applicable." } } }, "examples": { "delegation_token_retrieval": { "summary": "Delegation Token Retrieval", "value": { "delegation_id": "del_123456", "token_id": "tok_78910", "scope": [ "read", "write" ], "expires_at": "2023-12-31T23:59:59Z", "created_at": "2023-01-01T00:00:00Z", "last_used_at": "2023-09-15T12:34:56Z", "revoked_at": null } } } } } }, "400": { "description": "The request could not be understood by the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "badrequestexample": { "summary": "BadRequestExample", "value": { "type": "https://docs.humanplatform.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided token ID is malformed. Ensure you are using a valid token ID format." } } } } } }, "401": { "description": "Authentication credentials were missing or incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorizedexample": { "summary": "UnauthorizedExample", "value": { "type": "https://docs.humanplatform.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Missing delegation context. Please authenticate and try again." } } } } } }, "403": { "description": "The request was understood, but it has been refused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbiddenexample": { "summary": "ForbiddenExample", "value": { "type": "https://docs.humanplatform.com/errors/forbidden-access", "title": "Forbidden Access", "status": 403, "detail": "You do not have permission to access this delegation token. Verify your access rights and try again." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notfoundexample": { "summary": "NotFoundExample", "value": { "type": "https://docs.humanplatform.com/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "Delegation token with the specified ID was not found. Please verify the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internalservererrorexample": { "summary": "InternalServerErrorExample", "value": { "type": "https://docs.humanplatform.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the delegation token. Please try again later, or contact support if the issue persists." } } } } } } } }, "delete": { "summary": "Revoke Delegation Token by ID", "description": "In the dynamic landscape of the HUMAN platform, delegation tokens empower agents to act on behalf of one another securely. This endpoint allows you to revoke an existing delegation token, ensuring that only authorized actions are performed and maintaining the integrity of the network.", "operationId": "revokeDelegationTokenById", "tags": [ "Delegation", "Security" ], "x-code-hash": "2b026e0bac782e5e", "x-generated-at": "2026-03-24T22:44:37.929Z", "responses": { "204": { "description": "The delegation token was successfully revoked, ensuring no further delegation actions can occur with this token.", "content": { "application/json": {} } }, "400": { "description": "The request was malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The delegation token specified was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/delegation-tokens/by-delegation/:id": { "get": { "summary": "Retrieve tokens by delegation ID", "description": "Discover the lifeline of your delegation tokens with a simple query. This endpoint empowers you to list tokens tied to a specific delegation, ensuring precise control and oversight of token usage within the HUMAN ecosystem.", "operationId": "getDelegationTokensByDelegationId", "tags": [ "Delegation", "Tokens" ], "x-code-hash": "4506121005135daa", "x-generated-at": "2026-03-24T22:43:50.874Z", "responses": { "200": { "description": "Successfully retrieved delegation tokens associated with the specified ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "token_id": { "type": "string" }, "delegation_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time" } } } } } }, "examples": { "successful_response": { "summary": "Successful Response", "value": { "data": [ { "token_id": "abc123", "delegation_id": "del456", "created_at": "2023-10-10T14:48:00Z", "expires_at": "2023-12-10T14:48:00Z", "last_used_at": "2023-10-12T10:00:00Z" } ] } } } } } }, "400": { "description": "Occurs when the delegation ID is missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_id": { "summary": "Missing Delegation ID", "value": { "type": "https://example.com/probs/required-field-missing", "title": "Missing Required Field", "status": 400, "detail": "The Delegation ID is required and must be a non-empty string.", "errors": [ { "field": "id", "code": "REQUIRED_FIELD_MISSING", "message": "Delegation ID is required", "expected": "non-empty string", "received": "undefined" } ] } } } } } }, "401": { "description": "Occurs when authentication context is missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_context": { "summary": "Missing Authentication Context", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Missing delegation context. Ensure you have a valid authentication token with the appropriate delegation." } } } } } }, "403": { "description": "Occurs when the requester does not have permission to access the delegation tokens.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access these delegation tokens. Verify if you have the correct privileges." } } } } } }, "404": { "description": "Occurs when no delegation tokens are found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_tokens_not_found": { "summary": "Delegation Tokens Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No delegation tokens were found for the given ID. Ensure the ID is correct and try again." } } } } } }, "500": { "description": "Occurs when an unexpected error happens on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID inc_1696969696969." } } } } } } } } }, "/v1/delegation-tokens/:id/rotate": { "post": { "summary": "Rotate a Delegation Token Safely", "description": "In the HUMAN ecosystem, delegation tokens are the lifeblood of secure interactions. This endpoint allows you to rotate a delegation token, ensuring that access remains current and secure without extending the original delegation period. It's a crucial operation to maintain security and validity in a dynamic environment.", "operationId": "rotateDelegationToken", "tags": [ "Delegation", "Security" ], "x-code-hash": "fe8f30e70ea2ae98", "x-generated-at": "2026-03-24T22:44:57.054Z", "responses": { "201": { "description": "Successfully rotated the delegation token. Returns the new token details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The new delegation token." }, "delegation_id": { "type": "string", "description": "The ID of the delegation associated with the token." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the new token was created." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the new token will expire." } }, "required": [ "token", "delegation_id", "created_at" ] }, "examples": { "successful_token_rotation": { "summary": "Successful Token Rotation", "description": "An example of a successful token rotation for the 'acme' organization.", "value": { "token": "new-token-string", "delegation_id": "del-123456", "created_at": "2023-10-10T12:00:00Z", "expires_at": "2023-12-31T23:59:59Z" } } } } } }, "400": { "description": "Bad Request due to missing or invalid 'id' parameter.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_id_parameter": { "summary": "Missing ID Parameter", "description": "An example response when the 'id' parameter is missing.", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'id' parameter is required and must be a non-empty string.", "errors": [ { "field": "id", "message": "Token or delegation ID is required" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing Delegation Context", "description": "An example response when the delegation context is missing.", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context. Ensure you are authenticated with the correct credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "An example response when the user lacks permissions to rotate the token.", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Cannot rotate: issuer passport or keys not found. Verify your permissions and try again." } } } } } }, "404": { "description": "Not Found when the specified token or delegation does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_token_not_found": { "summary": "Delegation Token Not Found", "description": "An example response when the delegation token ID is not found.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Delegation token with ID 'del-123456' not found." } } } } } }, "500": { "description": "Internal Server Error due to unexpected issues during token rotation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_during_rotation": { "summary": "Internal Server Error During Rotation", "description": "An example response for an internal server error occurring during token rotation.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during token rotation. Please try again later." } } } } } } } } }, "/v1/delegations/:id/revocation": { "get": { "summary": "Retrieve Delegation Revocation Status", "description": "Explore the intricate dance of permissions and trust with this endpoint, which reveals whether a delegation has been revoked. In the world of HUMAN's decentralized networks, knowing the status of delegations is crucial for maintaining the integrity of operations and ensuring the right agents hold the right capabilities.", "operationId": "getDelegationRevocationStatus", "tags": [ "Delegations", "Revocations" ], "x-code-hash": "08c46867580f4fd3", "x-generated-at": "2026-03-24T22:29:48.753Z", "responses": { "200": { "description": "Successfully retrieved the revocation status of the specified delegation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "description": "Indicates if the delegation has been revoked." }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of when the delegation was revoked. Null if not revoked." }, "revoked_reason": { "type": [ "string", "null" ], "description": "Reason for the revocation. Null if not revoked." } }, "required": [ "revoked", "revoked_at", "revoked_reason" ] }, "examples": { "revoked_delegation": { "summary": "Revoked Delegation", "value": { "revoked": true, "revoked_at": "2023-10-03T14:48:00Z", "revoked_reason": "Violation of terms" } }, "active_delegation": { "summary": "Active Delegation", "value": { "revoked": false, "revoked_at": null, "revoked_reason": null } } } } } }, "400": { "description": "The request was malformed or missing crucial parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_id": { "summary": "Missing Delegation ID", "value": { "type": "https://example.com/probs/invalid-params", "title": "Invalid Request Parameters", "status": 400, "detail": "Delegation ID is required and must be a non-empty string.", "errors": [ { "field": "id", "code": "REQUIRED_FIELD_MISSING", "message": "Delegation ID is required", "expected": "non-empty string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication credentials were missing or incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Access requires valid authentication credentials." } } } } } }, "403": { "description": "The client does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://example.com/probs/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have permission to view this delegation's revocation status." } } } } } }, "404": { "description": "The delegation with the specified ID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_not_found": { "summary": "Delegation Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Delegation Not Found", "status": 404, "detail": "No delegation found for the given ID." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/core/permissions": { "get": { "summary": "Retrieve active session permissions", "description": "Discover the rights and capabilities granted to your current session, ensuring you can navigate the HUMAN platform with confidence and clarity. By understanding your permissions, you can seamlessly orchestrate tasks, knowing what actions are at your disposal.", "operationId": "getActivePermissions", "tags": [ "Authorization", "Session Management" ], "x-code-hash": "3e0c38f38c13ae06", "x-generated-at": "2026-03-24T22:30:17.716Z", "responses": { "200": { "description": "Successfully retrieved the effective permissions for the current session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "string" } }, "delegation_id": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "permissions" ] }, "examples": { "successful_permissions_retrieval": { "summary": "Successful Permissions Retrieval", "description": "An example showing successful retrieval of permissions for an active session.", "value": { "permissions": [ "capability://read", "capability://write" ], "delegation_id": "abc123", "expires_at": "2023-11-30T15:00:00Z" } } } } } }, "400": { "description": "Invalid request, typically due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_example": { "summary": "Malformed Request Example", "description": "Example response when the request is not properly formed.", "value": { "type": "https://example.com/probs/malformed-request", "title": "Bad Request", "status": 400, "detail": "The request could not be understood due to malformed syntax." } } } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error_example": { "summary": "Authentication Error Example", "description": "Example response when authentication fails due to missing delegation context.", "value": { "type": "https://example.com/probs/authentication-error", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context. Ensure you are logged in and try again." } } } } } }, "403": { "description": "Permission denied due to insufficient rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied_example": { "summary": "Permission Denied Example", "description": "Example response when the user does not have the necessary permissions.", "value": { "type": "https://example.com/probs/permission-denied", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource." } } } } } }, "404": { "description": "Resource not found, possibly due to incorrect endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "description": "Example response when the endpoint is incorrect or the resource doesn't exist.", "value": { "type": "https://example.com/probs/resource-not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found on the server." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "Example response for an unexpected server error.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } } }, "/v1/provenance/:workflowId": { "get": { "summary": "Retrieve Provenance Graph by Workflow", "description": "Dive into the journey of a workflow within the HUMAN protocol. This endpoint unveils the intricate web of tasks and decisions that form a workflow's provenance, ensuring transparency and accountability.", "operationId": "getProvenanceByWorkflowId", "tags": [ "Provenance", "Workflows" ], "x-code-hash": "2e2ebf1bd264ace4", "x-generated-at": "2026-04-13T19:57:14.218Z", "responses": { "200": { "description": "Successfully retrieved provenance graph or DAG nodes for the specified workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string" }, "graph": { "type": "object" }, "root_node_id": { "type": "string" }, "terminal_node_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workflow_id": { "type": "string" }, "parent_node_id": { "type": "string" }, "node_type": { "type": "string" }, "node_name": { "type": "string" }, "agent_id": { "type": "string" }, "agent_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": "number" }, "provenance_id": { "type": "string" }, "execution_id": { "type": "string" } } } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "from_node_id": { "type": "string" }, "to_node_id": { "type": "string" }, "edge_type": { "type": "string" } } } }, "root_node": { "type": "object", "properties": { "id": { "type": "string" }, "node_type": { "type": "string" }, "status": { "type": "string" } }, "nullable": true }, "stats": { "type": "object" } } }, "examples": { "acme_workflow_provenance": { "summary": "Acme Workflow Provenance", "description": "The provenance graph for Acme's invoice processing workflow.", "value": { "workflow_id": "workflow-12345", "graph": { "nodes": [ { "id": "node-1", "workflow_id": "workflow-12345", "parent_node_id": null, "node_type": "start", "node_name": "Invoice Received", "agent_id": "agent-001", "agent_name": "Alice", "status": "completed", "created_at": "2023-10-01T12:00:00Z", "started_at": "2023-10-01T12:01:00Z", "completed_at": "2023-10-01T12:02:00Z", "duration_ms": 60000, "provenance_id": "prov-001", "execution_id": "exec-001" } ], "edges": [ { "id": "edge-1", "from_node_id": "node-1", "to_node_id": "node-2", "edge_type": "transition" } ], "root_node": { "id": "node-1", "node_type": "start", "status": "completed" }, "stats": {} }, "root_node_id": "node-1", "terminal_node_id": "node-5", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-01T12:10:00Z" } } } } } }, "400": { "description": "The request is malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_workflowid": { "summary": "Missing workflowId", "description": "A request without the workflowId parameter.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing workflowId", "status": 400, "detail": "workflowId path parameter is required." } } } } } }, "404": { "description": "The specified workflow was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "Trying to access a non-existent workflow.", "value": { "type": "https://haio.run/errors/not-found", "title": "Workflow Not Found", "status": 404, "detail": "No workflow found with ID workflow-12345." } } } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error during provenance retrieval.", "value": { "type": "https://haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while fetching provenance. Incident ID: inc_1678945623" } } } } } } } } }, "/v1/events": { "get": { "summary": "Fetch organizational event logs", "description": "Delve into the chronicles of your organization with this endpoint, designed to retrieve a curated list of events. Whether you're tracking the past or steering towards your future, understanding your events is crucial for strategic decision-making.", "operationId": "getOrgEvents", "tags": [ "Events", "Organization" ], "x-code-hash": "0b721959b07e727c", "x-generated-at": "2026-03-24T23:14:52.897Z", "responses": { "200": { "description": "Successfully retrieved list of events for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "event_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "direction": { "type": "string" }, "source_connector_id": { "type": "string" } }, "required": [ "event_id", "event_type", "created_at" ] } }, "limit": { "type": "integer" }, "cursor": { "type": "string" }, "hasMore": { "type": "boolean" } } }, "examples": { "event_list_for_acme_corp": { "summary": "Event List for Acme Corp", "description": "Retrieve the latest 10 events for Acme Corp, revealing recent interactions and changes.", "value": { "data": [ { "event_id": "evt_12345", "event_type": "invoice.processed", "created_at": "2023-10-03T14:48:00.000Z", "direction": "incoming", "source_connector_id": "connector_67890" } ], "limit": 10, "cursor": "2023-10-03T14:48:00.000Z", "hasMore": false } } } } } }, "400": { "description": "Invalid request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ { "field": "limit", "message": "must be a positive integer." } ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Org DID required, but no delegation provided." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these events." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/probs/not-found", "title": "Not Found", "status": 404, "detail": "No events found for the given query parameters." } } } } } }, "500": { "description": "Unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/provenance/query": { "post": { "summary": "Query Provenance Records with Filters", "description": "Uncover the history behind your data by querying provenance records with precision. This endpoint empowers you to trace the lineage of actions within your organization, filtering by specific actors, events, or timeframes. Dive deep into the **Distributed Ledger** to ensure transparency and accountability.", "operationId": "queryProvenanceRecords", "tags": [ "Provenance", "Ledger" ], "x-code-hash": "69d23c6c4eca7a7a", "x-generated-at": "2026-04-13T19:55:42.765Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The decentralized identifier for the organization" }, "actor_id": { "type": "string", "description": "Passport ID of the actor involved" }, "since": { "type": "string", "format": "date-time", "description": "Filter records since this date" }, "event_type": { "type": "string", "description": "Type of event to filter" } } }, "query": { "type": "string", "description": "Optional query string for advanced search" } } }, "examples": { "filter_by_organization_and_actor": { "summary": "Filter by Organization and Actor", "description": "Query provenance records for a specific organization and actor", "value": { "filters": { "org_did": "did:example:acme-org", "actor_id": "passport:12345", "since": "2023-09-01T00:00:00Z", "event_type": "invoice_processed" }, "query": "status:completed" } } } } } }, "responses": { "200": { "description": "A list of provenance records matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "actor": { "type": "string" }, "delegation": { "type": "string" }, "operation": { "type": "object" }, "context": { "type": "object" }, "policy": { "type": "object" }, "outcome": { "type": "string" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "successful_response": { "summary": "Successful Response", "value": { "data": [ { "id": "evt-001", "timestamp": "2023-09-15T12:34:56Z", "actor": "passport:12345", "delegation": "del-001", "operation": { "eventType": "invoice_processed" }, "context": { "orgDid": "did:example:acme-org" }, "policy": { "policyId": "pol-001" }, "outcome": "success" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Invalid request parameters or body", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/provenance/attest": { "post": { "summary": "Attest Provenance Event for Verification", "description": "In the intricate dance of information and identity, this endpoint allows trusted parties to attest to the authenticity of a provenance event. By doing so, it ensures the integrity and trustworthiness of the data within the HUMAN ecosystem, binding the present to the verified past.", "operationId": "attestProvenanceEvent", "tags": [ "Provenance", "Attestation" ], "x-code-hash": "68bfa302adcde5b7", "x-generated-at": "2026-03-24T22:30:55.713Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier for the organization." }, "provenance_record_id": { "type": "string", "description": "Unique identifier for the provenance record." }, "attestation_payload": { "type": "object", "additionalProperties": true, "description": "Optional payload to include additional metadata for attestation." } }, "required": [ "provenance_record_id" ] }, "examples": { "basic_attestation": { "summary": "Basic Attestation", "description": "Attest a provenance record for the 'acme' organization.", "value": { "org_did": "did:human:acme123", "provenance_record_id": "prov-456def789", "attestation_payload": { "verified_by": "John Doe", "verification_date": "2023-09-15" } } } } } } }, "responses": { "201": { "description": "Successfully attested the provenance event, ensuring its authenticity and integrity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "attestation_id": { "type": "string", "description": "Unique identifier for the attestation." }, "signature": { "type": "string", "description": "Cryptographic signature validating the attestation." }, "provenance_record_id": { "type": "string", "description": "Identifier of the attested provenance event." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of attestation creation." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Request was invalid due to missing or malformed fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing provenance_record_id", "status": 400, "detail": "provenance_record_id is required.", "errors": [ { "field": "provenance_record_id", "code": "REQUIRED", "message": "This field is mandatory and was not provided.", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation context required. Please ensure you are authenticated with proper delegation credentials." } } } } } }, "404": { "description": "Provenance record not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No provenance record found with the given ID. Verify the ID and try again." } } } } } }, "500": { "description": "Internal error occurred during attestation processing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Provenance Attestation Failed", "status": 500, "detail": "An unexpected error occurred during the attestation process. Please contact support with the error details." } } } } } } } } }, "/v1/connectors": { "post": { "summary": "Create and register a new connector", "description": "In the vast landscape of digital ecosystems, connectors serve as bridges, enabling seamless interactions between diverse platforms. This endpoint allows you to register a new connector, giving it a digital handshake to the HUMAN protocol, ensuring it can perform its duties in harmony with others.", "operationId": "createConnectorRegistration", "tags": [ "Connectors", "Registration" ], "x-code-hash": "4b480a0cfd8ec1e2", "x-generated-at": "2026-03-24T22:24:52.955Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "manifest": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "name", "provider", "version" ] }, "publisher_id": { "type": "string" }, "visibility": { "type": "string", "enum": [ "org_private", "public" ] }, "certified": { "type": "boolean" }, "org_id": { "type": "string" }, "pricing_model": { "type": "string", "enum": [ "free", "paid" ] }, "config": { "type": "object" } }, "required": [ "manifest" ] }, "examples": { "acme_connector_registration": { "summary": "Acme Connector Registration", "description": "Registering Acme's invoice processing connector for public visibility.", "value": { "manifest": { "id": "acme-invoice-connector", "name": "Acme Invoice Processor", "provider": "Acme Corp", "version": "1.0.0" }, "publisher_id": "acme-publisher-id", "visibility": "public", "certified": true, "org_id": "org-12345", "pricing_model": "free", "config": { "apiKey": "abcd1234" } } } } } } }, "responses": { "201": { "description": "The connector was successfully registered and is now active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "connector_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "id": "connector-67890", "connector_id": "acme-invoice-connector", "name": "Acme Invoice Processor", "provider": "Acme Corp", "version": "1.0.0", "status": "active" } } } } } }, "400": { "description": "The request body is invalid or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body with manifest is required.", "errors": [ { "field": "body", "code": "REQUIRED_FIELD_MISSING", "message": "Request body with manifest is required", "received": "null" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation token required. Please provide a valid token." } } } } } }, "403": { "description": "The client does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the required permissions to register a connector." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/connectors/:id": { "get": { "summary": "Retrieve connector details by identifier", "description": "Delve into the world of connectors with this endpoint, which unveils the secrets of a connector's metadata using its unique identifier. Whether you're orchestrating tasks or verifying integrations, this endpoint ensures you have the detailed insights needed to manage and optimize your connectors effectively.", "operationId": "getConnectorById", "tags": [ "Connectors", "Metadata" ], "x-code-hash": "5832a7c0dae43102", "x-generated-at": "2026-03-24T22:24:36.478Z", "responses": { "200": { "description": "Successfully retrieved the connector metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the connector." }, "connector_id": { "type": "string", "description": "Secondary identifier for the connector." }, "name": { "type": "string", "description": "Name of the connector." }, "provider": { "type": "string", "description": "Provider of the connector." }, "version": { "type": "string", "description": "Version of the connector." }, "description": { "type": [ "string", "null" ], "description": "Description of the connector." }, "icon_url": { "type": [ "string", "null" ], "description": "URL to the connector's icon." }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capabilities offered by the connector." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes required by the connector." }, "oauth_config": { "type": [ "object", "null" ], "description": "OAuth configuration details." }, "deployment": { "type": "object", "description": "Deployment information for the connector." }, "publisher_id": { "type": "string", "description": "Identifier for the publisher of the connector." }, "visibility": { "type": "string", "description": "Visibility status of the connector." }, "certified": { "type": "boolean", "description": "Certification status of the connector." }, "pricing_model": { "type": "string", "description": "Pricing model of the connector." } } }, "examples": { "connector_details_for_acme's_invoice_system": { "summary": "Connector details for Acme's invoice system", "description": "Retrieve the metadata for Acme's invoice processing connector.", "value": { "id": "connector-123", "connector_id": "invoice-processor", "name": "Acme Invoice Processor", "provider": "Acme Inc.", "version": "1.2.3", "description": "Processes invoices for Acme's internal systems.", "icon_url": "https://example.com/icons/acme-invoice.png", "capabilities": [ "capability://process_invoices", "capability://generate_reports" ], "required_scopes": [ "invoices.read", "invoices.write" ], "oauth_config": { "scopes": [ "invoices.read", "invoices.write" ] }, "deployment": { "region": "us-west-2", "status": "active" }, "publisher_id": "pub-456", "visibility": "public", "certified": true, "pricing_model": "pay-as-you-go" } } } } } }, "400": { "description": "Invalid connector ID provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_connector_id": { "summary": "Invalid Connector ID", "description": "The client provided a malformed connector ID.", "value": { "type": "https://humanprotocol.example.com/errors/invalid-id", "title": "Invalid Connector ID", "status": 400, "detail": "The connector ID '123-abc' is not valid. Please ensure it matches the expected format." } } } } } }, "401": { "description": "Unauthorized access - valid authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_token": { "summary": "Missing Authentication Token", "description": "The request lacks a valid authentication token.", "value": { "type": "https://humanprotocol.example.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "An authentication token is required to access this endpoint. Please provide a valid token." } } } } } }, "403": { "description": "Forbidden - insufficient permissions to access this connector.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user does not have permission to view this connector.", "value": { "type": "https://humanprotocol.example.com/errors/access-denied", "title": "Access Denied", "status": 403, "detail": "You do not have the necessary permissions to access this connector. Please contact your administrator." } } } } } }, "404": { "description": "Connector not found with the provided ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_not_found": { "summary": "Connector Not Found", "description": "No connector found for the given ID.", "value": { "type": "https://humanprotocol.example.com/errors/not-found", "title": "Connector Not Found", "status": 404, "detail": "The connector with ID 'connector-789' does not exist. Please verify the ID and try again." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://humanprotocol.example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/agents": { "get": { "summary": "Retrieve a paginated list of agents", "description": "Discover the dynamic landscape of your organization's AI workforce. This endpoint not only lists agents but paints a picture of their capabilities, empowering you to manage and optimize your human-AI orchestration effectively. By leveraging cursor-based pagination, it ensures smooth navigation through extensive datasets.", "operationId": "getAgents", "tags": [ "Agents", "Management" ], "x-code-hash": "77e95741eb34c8ce", "x-generated-at": "2026-03-26T22:21:19.425Z", "responses": { "200": { "description": "Successfully retrieved a paginated list of agents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string" }, "org_agent_id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "deployed_at": { "type": "string", "format": "date-time" }, "deployed_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "did", "org_agent_id", "name", "version", "status", "created_at" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorField", "hasMore" ] }, "examples": { "successful_agents_list_retrieval": { "summary": "Successful agents list retrieval", "description": "A seamless retrieval of agents for the 'acme' organization.", "value": { "data": [ { "did": "did:human:123", "org_agent_id": "agent-acme-007", "name": "Invoice Processor", "version": "v1.0.3", "status": "active", "capabilities": [ "capability://process-invoice", "capability://send-email" ], "description": "Automates invoice processing tasks.", "deployed_at": "2023-10-01T12:34:56Z", "deployed_by": "user@acme.org", "created_at": "2023-09-15T08:45:00Z" } ], "limit": 10, "cursorField": "created_at", "hasMore": false } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination_parameters": { "summary": "Invalid pagination parameters", "description": "Occurs when pagination parameters are incorrect.", "value": { "type": "https://example.com/probs/invalid-params", "title": "Invalid Request Parameters", "status": 400, "detail": "The 'limit' must be a positive integer and 'cursor' must be a valid cursor string.", "errors": [ "Invalid 'limit' value", "Malformed 'cursor' parameter" ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_or_invalid_authentication": { "summary": "Missing or invalid authentication", "description": "When the request lacks valid authentication credentials.", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "Occurs when the user does not have the required permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization not found", "description": "Occurs when the specified organization ID does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization ID 'acme-corp' could not be found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "Occurs when an unexpected error happens on the server.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/agents/:id": { "get": { "summary": "Retrieve details of a specific agent", "description": "Discover the capabilities and identity of a specific agent within the HUMAN ecosystem. This endpoint allows you to access detailed information about an agent, tracked through the HUMAN Passport and Capability Graph, to understand its roles and functions. Uncover how agents are orchestrated to perform tasks safely and transparently.", "operationId": "getAgentDetails", "tags": [ "Agents", "Identity" ], "x-code-hash": "e27dac14f00d498b", "x-generated-at": "2026-01-27T02:28:09.483Z", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Successfully retrieved agent details, including capabilities and identity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the agent." }, "name": { "type": "string", "description": "The human-readable name of the agent." }, "status": { "type": "string", "description": "Current operational status of the agent." }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of capabilities associated with the agent." } }, "required": [ "id", "name", "status", "capabilities" ] }, "examples": { "invoice_processor": { "summary": "Invoice Processor" } } } } }, "400": { "description": "Bad Request - Invalid agent ID format. Ensure the ID is a valid string conforming to UUID standards.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Forbidden - Insufficient permissions to access this agent's details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "Not Found - No agent found with the specified ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/agents/call": { "post": { "summary": "Invoke Agent via Capability or Workflow", "description": "The Unified Human-AI Orchestration Gateway empowers organizations to seamlessly orchestrate tasks across human and AI agents. By leveraging capability URIs, agent URIs, or workflow capability steps, users can route tasks dynamically and ensure AI safety through HumanOS. This endpoint is the backbone of intelligent task routing, ensuring tasks reach the most capable executor.", "operationId": "invokeAgent", "tags": [ "HumanOS", "Agent Orchestration" ], "x-code-hash": "c65fcd2c74964d32", "x-generated-at": "2026-04-30T22:45:29.391Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "capability": { "type": "string", "description": "Capability URI for task routing", "pattern": "^capability://" }, "async": { "type": "boolean", "description": "Whether the invocation should be asynchronous" }, "input": { "type": "object", "description": "Input parameters for the agent" } }, "required": [ "capability" ] }, { "type": "object", "properties": { "target": { "type": "string", "description": "Agent URI for direct invocation" }, "async": { "type": "boolean", "description": "Whether the invocation should be asynchronous" }, "input": { "type": "object", "description": "Input parameters for the agent" } }, "required": [ "target" ] }, { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Unique identifier for the agent, in DID or org_id:agent_name format" }, "async": { "type": "boolean", "description": "Whether the invocation should be asynchronous" }, "input": { "type": "object", "description": "Input parameters for the agent" } }, "required": [ "agent_id" ] }, { "type": "object", "properties": { "humanos": { "type": "object", "properties": { "step_kind": { "type": "string", "enum": [ "capability" ] }, "required_capabilities": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "List of required capabilities for the workflow" }, "required_connectors": { "type": "array", "items": { "type": "string" }, "description": "Connector identifiers for executor ranking" }, "workflow_id": { "type": "string", "description": "Identifier for the workflow" }, "run_id": { "type": "string", "description": "Run identifier within the workflow" }, "runtime_envelope": { "type": "object", "description": "Opaque runtime envelope for execution context" } }, "required": [ "step_kind", "required_capabilities" ] }, "async": { "type": "boolean", "description": "Whether the invocation should be asynchronous" }, "input": { "type": "object", "description": "Input parameters for the agent" } }, "required": [ "humanos" ] } ], "properties": { "input": { "type": "object", "additionalProperties": true, "description": "Payload for the invoked agent: becomes HumanOS `TaskRequest.input` (default `{}`). Also supplied as delegation validation `parameters`." } } }, "examples": { "invoke_with_capability_uri": { "summary": "Invoke with Capability URI", "description": "Example invoking an agent using a capability URI.", "value": { "capability": "capability://org123/email.read", "async": false, "input": { "email_id": "12345" } } }, "invoke_with_agent_uri": { "summary": "Invoke with Agent URI", "description": "Example invoking an agent directly using its agent URI.", "value": { "target": "agent://org1234/financeBot", "async": true, "input": { "invoice_id": "INV-2023-01" } } }, "invoke_with_agent_id": { "summary": "Invoke with Agent ID", "description": "Example invoking an agent using its ID.", "value": { "agent_id": "org5678:invoiceProcessor", "async": true, "input": { "invoice_number": "INV-2023-01" } } }, "invoke_with_workflow_capability_step": { "summary": "Invoke with Workflow Capability Step", "description": "Example invoking an agent using a workflow capability step.", "value": { "humanos": { "step_kind": "capability", "required_capabilities": [ "email.read", "data.summarize" ], "required_connectors": [ "connector1" ], "workflow_id": "workflow123", "run_id": "run5678", "runtime_envelope": {} }, "async": true, "input": { "data_id": "56789" } } } } } } }, "responses": { "200": { "description": "Successful synchronous agent invocation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Result from the agent execution, including any output and timing information." }, "routing": { "type": "object", "description": "Information about task routing through HumanOS." }, "metadata": { "type": "object", "description": "Metadata related to the invocation." }, "action_receipt": { "type": "object", "properties": { "accessedResources": { "type": "array", "items": { "type": "string" } }, "createdArtifacts": { "type": "array", "items": { "type": "string" } }, "sentItems": { "type": "array", "items": { "type": "string" } }, "policyApplied": { "type": "string" }, "receiptId": { "type": "string" }, "timestamp": { "type": "string" }, "action": { "type": "string" }, "actorDid": { "type": "string" }, "actorName": { "type": "string" }, "orgId": { "type": "string" }, "provenanceLink": { "type": "string" }, "boundaryEnforced": { "type": "boolean" }, "delegationScopeId": { "type": "string" } }, "description": "Receipt metadata capturing the action details and provenance." } } }, "examples": { "default": { "summary": "Example", "value": { "result": { "output": "Processed email data successfully.", "duration_ms": 1200 }, "routing": { "executor": "agent://org1234/financeBot" }, "metadata": { "taskId": "task123", "traceId": "trace456" }, "action_receipt": { "accessedResources": [ "resource1", "resource2" ], "createdArtifacts": [ "artifact1" ], "sentItems": [ "email1" ], "policyApplied": "default", "receiptId": "receipt789", "timestamp": "2023-10-01T12:34:56Z", "action": "invoke", "actorDid": "did:human:org1234", "actorName": "FinanceBot", "orgId": "org5678", "provenanceLink": "https://ledger.human/provenance/1234", "boundaryEnforced": true } } } } } } }, "202": { "description": "Async execution queued (`async: true`) or high-risk invocation pending human approval", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Queued async execution", "properties": { "execution_id": { "type": "string" }, "status": { "type": "string" }, "status_url": { "type": "string" }, "message": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" } }, "required": [ "execution_id", "status", "status_url" ] }, { "type": "object", "title": "Pending risk approval", "properties": { "status": { "type": "string" }, "approval_id": { "type": "string" }, "task_id": { "type": "string" }, "risk_level": { "type": "string" }, "message": { "type": "string" }, "approval_url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "approval_id", "task_id" ] } ] } } } }, "400": { "description": "Bad request due to missing required fields or no capable executor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found when the specified agent or capability does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error due to configuration or execution failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/executions/:id": { "get": { "summary": "Poll execution status asynchronously", "description": "Retrieve the current status of an execution task. This endpoint enables clients to track the progress of tasks managed by HUMAN's orchestration layer, ensuring transparent and reliable updates without blocking operations.", "operationId": "getExecutionStatus", "tags": [ "Execution", "Monitoring" ], "x-code-hash": "1336bdc2bc97a16b", "x-generated-at": "2026-04-10T00:55:57.490Z", "responses": { "200": { "description": "The execution status was retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "description": "Async execution status from `execution_queue` (`handleExecutionStatus`). Optional fields depend on `status`.", "properties": { "execution_id": { "type": "string", "description": "Execution identifier (matches path `:id`)." }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ], "description": "Lifecycle state of the execution." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "description": "Present when status is `processing`." }, "message": { "type": "string", "description": "Human-readable hint when queued or processing." }, "result": { "nullable": true, "description": "Present only when status is `completed`. Arbitrary JSON from `execution_queue.result_json` (worker/agent output: objects, arrays, primitives — not a fixed `{ output: string }` shape)." }, "provenance_id": { "type": "string", "description": "Present when status is `completed`." }, "completed_at": { "type": "string", "format": "date-time", "description": "Present when status is `completed` or `failed`." }, "action_receipt": { "type": "object", "additionalProperties": true, "description": "Present when status is `completed` (ActionReceipt)." }, "error": { "nullable": true, "description": "Present when status is `failed` (from `error_json`)." } }, "required": [ "execution_id", "status", "created_at", "updated_at" ] }, "examples": { "execution_processing": { "summary": "Execution in progress", "value": { "execution_id": "exec_abc123", "status": "processing", "created_at": "2025-11-25T10:30:00.000Z", "updated_at": "2025-11-25T10:30:05.000Z", "started_at": "2025-11-25T10:30:01.000Z", "message": "Execution is currently being processed" } }, "execution_completed": { "summary": "Execution completed", "value": { "execution_id": "exec_xyz789", "status": "completed", "created_at": "2025-11-25T10:30:00.000Z", "updated_at": "2025-11-25T10:31:00.000Z", "result": { "summary": "Invoice processed successfully.", "line_items": 12 }, "provenance_id": "prov_123", "completed_at": "2025-11-25T10:31:00.000Z", "action_receipt": { "action": "async human.call execution completed" } } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_execution_id": { "summary": "Invalid execution ID", "description": "Occurs when the provided execution ID does not match the expected format.", "value": { "type": "https://api.human.com/docs/errors#400", "title": "Bad Request", "status": 400, "detail": "The execution ID provided is invalid. Please verify the ID format and try again." } } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing authentication", "description": "An error when the client does not provide authentication credentials.", "value": { "type": "https://api.human.com/docs/errors#401", "title": "Unauthorized", "status": 401, "detail": "Authentication required to access this resource. Please provide a valid token." } } } } } }, "403": { "description": "Insufficient permissions to access this execution.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "description": "An error when the client lacks the necessary permissions to view the execution status.", "value": { "type": "https://api.human.com/docs/errors#403", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this execution. Please contact your administrator." } } } } } }, "404": { "description": "Execution not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "execution_not_found": { "summary": "Execution not found", "description": "Occurs when the specified execution ID does not match any existing executions.", "value": { "type": "https://api.human.com/docs/errors#404", "title": "Not Found", "status": 404, "detail": "The execution with the given ID does not exist. Please check the ID and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_during_status_retrieval": { "summary": "Server error during status retrieval", "description": "An unexpected issue occurred on the server while fetching execution status.", "value": { "type": "https://api.human.com/docs/errors#500", "title": "Internal Server Error", "status": 500, "detail": "Unexpected error occurred while processing the request. Please try again later." } } } } } } } } }, "/v1/approvals": { "get": { "summary": "Retrieve pending approval requests", "description": "Navigate the intricate web of task approvals with this endpoint, designed to orchestrate queries across the HUMAN platform. Whether you're an approver, requester, or an automated task agent, this endpoint provides a streamlined view of approval requests, ensuring transparency and traceability in task management.", "operationId": "getApprovalRequests", "tags": [ "Approvals", "Task Management" ], "x-code-hash": "21762684356b70c4", "x-generated-at": "2026-03-24T22:26:02.985Z", "responses": { "200": { "description": "Successfully retrieved the list of approval requests, providing insights into pending tasks and their associated details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "agent_id": { "type": "string" }, "requester_passport_id": { "type": "string" }, "approver_passport_id": { "type": "string" }, "action_description": { "type": "string" }, "risk_level": { "type": "string" }, "risk_factors": { "type": "array", "items": { "type": "string" } }, "alternatives": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "response_comment": { "type": "string" }, "responded_at": { "type": "string", "format": "date-time" }, "responded_by": { "type": "string" }, "modified_params": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "next_cursor": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "description": "Example of a successful response with multiple approval requests", "value": { "data": [ { "id": "approval_12345", "task_id": "task_67890", "agent_id": "agent_001", "requester_passport_id": "passport_abc123", "approver_passport_id": "passport_xyz789", "action_description": "Approve invoice for Acme Corp", "risk_level": "medium", "risk_factors": [ "amount", "vendor reputation" ], "alternatives": [ "Request further documentation", "Reduce payment amount" ], "status": "pending", "response_comment": null, "responded_at": null, "responded_by": null, "modified_params": {}, "created_at": "2023-10-01T12:34:56Z", "expires_at": "2023-11-01T12:34:56Z" } ], "limit": 10, "next_cursor": "cursor_67890" } } } } } }, "400": { "description": "Invalid request due to malformed parameters such as an incorrect cursor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Cursor parameter issue", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid cursor", "status": 400, "detail": "The cursor parameter is invalid or malformed." } } } } } }, "401": { "description": "Unauthorized access due to missing delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Missing delegation context", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Example of a server error response", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/approvals/:id": { "get": { "summary": "Retrieve detailed approval request information", "description": "Dive into the details of a specific approval request, uncovering the journey and decisions it entails. This endpoint enables tracking and understanding of task approval processes, ensuring transparency and accountability within the HUMAN platform.", "operationId": "getApprovalRequestDetails", "tags": [ "Approvals", "Task Management" ], "x-code-hash": "ac91993979fef0af", "x-generated-at": "2026-03-24T22:26:37.766Z", "responses": { "200": { "description": "Approval request details are successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "agent_id": { "type": "string" }, "requester_passport_id": { "type": "string" }, "approver_passport_id": { "type": "string" }, "action_description": { "type": "string" }, "risk_level": { "type": "string" }, "risk_factors": { "type": "array", "items": { "type": "string" } }, "alternatives": { "type": "array", "items": { "type": "string" } }, "request_data": { "type": "object" }, "escalation_schema": { "type": "object" }, "status": { "type": "string" }, "response": { "type": "object" }, "response_comment": { "type": "string" }, "responded_at": { "type": "string", "format": "date-time" }, "responded_by": { "type": "string" }, "modified_params": { "type": "object" }, "delegated_to": { "type": "string" }, "override_action": { "type": "string" }, "conversation_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "provenance_id": { "type": "string" } } }, "examples": { "approval_request_details": { "summary": "Approval Request Details", "description": "An organization 'acme' is reviewing an approval request for task routing.", "value": { "id": "approval_12345", "task_id": "task_67890", "agent_id": "agent_001", "requester_passport_id": "passport_abc123", "approver_passport_id": "passport_xyz789", "action_description": "Request to approve invoice processing", "risk_level": "medium", "risk_factors": [ "new vendor", "large amount" ], "alternatives": [ "manual review", "automated approval" ], "request_data": { "invoice_id": "INV-1001", "amount": 15000 }, "escalation_schema": { "level": "manager", "time_limit": "48 hours" }, "status": "pending", "response": null, "response_comment": null, "responded_at": null, "responded_by": null, "modified_params": null, "delegated_to": null, "override_action": null, "conversation_id": "conv_7890", "created_at": "2023-10-01T10:00:00Z", "expires_at": "2023-10-15T10:00:00Z", "updated_at": "2023-10-01T10:05:00Z", "provenance_id": "prov_123456" } } } } } }, "400": { "description": "Invalid request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request": { "summary": "Malformed Request", "description": "The client submitted a request with an invalid ID format.", "value": { "type": "https://docs.humanprotocol.org/errors/malformed-request", "title": "Malformed Request", "status": 400, "detail": "The provided approval ID 'not_a_valid_id' is not in the correct format.", "errors": [ "approvalId: Invalid format" ] } } } } } }, "401": { "description": "Authentication failed due to missing or invalid delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing Delegation Context", "description": "The client failed to provide required delegation context for authentication.", "value": { "type": "https://docs.humanprotocol.org/errors/missing-delegation", "title": "Authentication Error", "status": 401, "detail": "Missing delegation context. Please ensure your authentication token includes a valid delegation." } } } } } }, "403": { "description": "Permission denied for accessing approval details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "The client lacks necessary permissions to view this approval request.", "value": { "type": "https://docs.humanprotocol.org/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access this approval request. Contact your administrator for access." } } } } } }, "404": { "description": "Approval request not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "approval_request_not_found": { "summary": "Approval Request Not Found", "description": "The specified approval request ID does not exist.", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Approval request with ID 'approval_12345' was not found. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://docs.humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support with incident ID 'inc_1697049600000'." } } } } } } } } }, "/v1/approvals/:id/respond": { "post": { "summary": "Respond to an approval request", "description": "In the ever-evolving landscape of human-AI collaboration, responding to approval requests ensures that tasks flow seamlessly between agents and AI. This endpoint empowers users to make pivotal decisions—approving, rejecting, or delegating—thereby maintaining the dynamic equilibrium of the HUMAN Protocol.", "operationId": "respondToApprovalRequest", "tags": [ "Approvals", "HumanAIOrchestration" ], "x-code-hash": "40e7d1bc1822a387", "x-generated-at": "2026-03-24T22:26:53.492Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "approved_with_modifications", "rejected", "delegated", "overridden" ], "description": "The decision made on the approval request." }, "comment": { "type": "string", "description": "Optional comment providing additional context for the decision." }, "modified_params": { "type": "object", "description": "Parameters modified during approval." }, "delegate_to": { "type": "string", "description": "DID of the agent to whom the task is delegated, if applicable." }, "override_action": { "type": "string", "description": "Action to override current settings, if necessary." } }, "required": [ "decision" ] }, "examples": { "approval_with_comments": { "summary": "Approval with comments", "description": "Approving a request with a comment and modifications.", "value": { "decision": "approved_with_modifications", "comment": "Approved with minor parameter updates", "modified_params": { "budget": 1200 } } } } } } }, "responses": { "200": { "description": "The approval request was successfully processed, and the decision has been recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the approval request." }, "status": { "type": "string", "description": "The current status of the approval request." }, "responded_at": { "type": "string", "format": "date-time", "description": "The timestamp when the decision was made." }, "responded_by": { "type": "string", "description": "The DID of the agent who made the decision." }, "response_comment": { "type": "string", "description": "Any comment that accompanied the response." }, "modified_params": { "type": "object", "description": "Any parameters that were modified during the approval process." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request format or content errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Decision must be one of: approved, approved_with_modifications, rejected, delegated, overridden", "errors": [ { "field": "decision", "code": "INVALID_VALUE", "message": "Decision must be one of: approved, approved_with_modifications, rejected, delegated, overridden", "expected": "approved | approved_with_modifications | rejected | delegated | overridden", "received": "approve" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context. Ensure the request contains valid authentication details." } } } } } }, "403": { "description": "Forbidden - the agent does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to respond to this approval request." } } } } } }, "404": { "description": "Approval request not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Approval request with ID 'apr_123456' was not found. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error during the operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support with incident ID 'inc_123456789'." } } } } } } } } }, "/v1/approvals/:id/cancel": { "post": { "summary": "Cancel a Pending Approval Request", "description": "In the dynamic world of approval workflows, sometimes decisions change. This endpoint empowers users to cancel a pending approval request, ensuring that only relevant and timely actions move forward. Whether it's a shift in priorities or a simple mistake, this is your safety net for agile project management.", "operationId": "cancelApprovalRequest", "tags": [ "Approvals", "WorkflowManagement" ], "x-code-hash": "1a7f85f44d5081bd", "x-generated-at": "2026-03-24T22:27:10.294Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "The reason for canceling the approval." } }, "required": [ "reason" ] }, "examples": { "cancel_with_a_reason": { "summary": "Cancel with a reason", "description": "An example showing a cancellation due to a change in project scope.", "value": { "reason": "Project scope changed, no longer needed." } } } } } }, "responses": { "200": { "description": "The approval request was successfully canceled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the approval request." }, "status": { "type": "string", "description": "The status of the approval request, now set to 'canceled'." }, "cancelled_at": { "type": "string", "format": "date-time", "description": "The timestamp when the cancellation was processed." }, "cancelled_by": { "type": "string", "description": "The DID of the agent who canceled the request." }, "cancellation_reason": { "type": "string", "description": "The reason provided for the cancellation." } } }, "examples": { "default": { "summary": "Example", "value": { "id": "approval_12345", "status": "canceled", "cancelled_at": "2023-10-01T14:48:00.000Z", "cancelled_by": "did:example:123456789abcdefghi", "cancellation_reason": "Project scope changed, no longer needed." } } } } } }, "400": { "description": "The request body is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'reason' field is required.", "errors": [ "The 'reason' field is missing or empty." ] } } } } } }, "401": { "description": "Authentication error due to missing delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context." } } } } } }, "403": { "description": "Permission error, indicating the agent lacks rights to cancel.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to cancel this approval." } } } } } }, "404": { "description": "The specified approval request was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Approval request with ID 'approval_12345' not found." } } } } } }, "409": { "description": "Conflict error indicating the approval request is already canceled.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/conflict", "title": "Conflict", "status": 409, "detail": "The approval request is already canceled." } } } } } }, "500": { "description": "Server error indicating a failure in processing the cancellation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/async-executions": { "get": { "summary": "Retrieve list of async task executions", "description": "Explore the universe of asynchronous task executions with this endpoint. It provides a rich view into ongoing and past tasks, empowering you to manage and track operations efficiently. Whether you're ensuring invoice processing completion or tracking AI model training, this endpoint is your window into the orchestration magic.", "operationId": "getAsyncExecutions", "tags": [ "Task Management", "Async Operations" ], "x-code-hash": "86e2257a352103b1", "x-generated-at": "2026-03-27T23:16:34.767Z", "responses": { "200": { "description": "A list of asynchronous executions with pagination support.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "agent_id": { "type": "string" }, "requester_passport_id": { "type": "string" }, "status": { "type": "string" }, "progress_percent": { "type": "number" }, "progress_message": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "paused_at": { "type": "string", "format": "date-time" }, "pause_reason": { "type": "string" }, "resume_count": { "type": "integer" }, "processing_pause_requested_at": { "type": "string", "format": "date-time" }, "result": { "type": "string" }, "error": { "type": "string" } } } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" } } }, "examples": { "invoice_processing_tasks": { "summary": "Invoice Processing Tasks", "description": "Retrieve a list of async executions for 'acme' organization invoice processing tasks.", "value": { "data": [ { "id": "exec_12345", "task_id": "task_67890", "agent_id": "agent_acme", "requester_passport_id": "passport_001", "status": "completed", "progress_percent": 100, "progress_message": "Task completed successfully", "queued_at": "2023-10-05T12:00:00Z", "started_at": "2023-10-05T12:05:00Z", "completed_at": "2023-10-05T12:10:00Z", "paused_at": null, "pause_reason": null, "resume_count": 0, "processing_pause_requested_at": null, "result": "{\"invoiceId\": \"inv_123\", \"status\": \"processed\"}", "error": null } ], "limit": 10, "cursorField": "queued_at" } } } } } }, "400": { "description": "Invalid request parameters, such as malformed cursor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "Occurs when the cursor parameter is malformed.", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid cursor", "status": 400, "detail": "The cursor parameter is invalid or malformed." } } } } } }, "401": { "description": "Missing or invalid authentication delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing Delegation Context", "description": "Occurs when the delegation context is missing in the request.", "value": { "type": "https://haio.run/errors/authentication", "title": "Authentication Error", "status": 401, "detail": "Missing delegation context. Ensure your request includes valid authentication credentials." } } } } } }, "403": { "description": "Insufficient permissions to access async executions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Occurs when the user does not have the right permissions.", "value": { "type": "https://haio.run/errors/permission", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to view these executions. Check your access rights or contact your administrator." } } } } } }, "500": { "description": "Internal server error. Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server-side error occurred.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1696518012345." } } } } } } } } }, "/v1/async-executions/:id": { "get": { "summary": "Retrieve Async Execution Status", "description": "Uncover the current status and intricate details of an asynchronous execution task. This endpoint empowers users by providing not just the status, but a comprehensive view into the job's lifecycle and its journey through the HumanOS system. It's designed for those who need insights into task progress and execution outcomes in a distributed environment.", "operationId": "getAsyncExecutionStatus", "tags": [ "HumanOS", "AsyncExecution" ], "x-code-hash": "5c6a0d3b4e388973", "x-generated-at": "2026-04-01T18:45:27.135Z", "responses": { "200": { "description": "The async execution status and details were successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the execution." }, "task_id": { "type": "string", "description": "Identifier of the associated task." }, "agent_id": { "type": "string", "description": "Identifier of the agent managing the task." }, "requester_passport_id": { "type": "string", "description": "Passport ID of the requester." }, "job_id": { "type": "string", "description": "Job ID associated with the execution." }, "queue_name": { "type": "string", "description": "Name of the queue that handles the job." }, "priority": { "type": "integer", "description": "Priority level of the execution." }, "status": { "type": "string", "description": "Current status of the execution." }, "result": { "type": "object", "description": "Result metadata of the execution." }, "error": { "type": "object", "description": "Error details if the execution encountered issues." }, "progress_percent": { "type": "number", "description": "Completion percentage of the execution." }, "progress_message": { "type": "string", "description": "Message describing current progress." }, "callback_url": { "type": "string", "description": "URL to notify upon completion." }, "callback_success": { "type": "boolean", "description": "Indicates if callback was successful." }, "callback_attempts": { "type": "integer", "description": "Number of callback attempts made." }, "max_attempts": { "type": "integer", "description": "Maximum allowable attempts." }, "current_attempt": { "type": "integer", "description": "Current attempt number." }, "queued_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution was queued." }, "started_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution started." }, "completed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution completed." }, "paused_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution was paused." }, "paused_by": { "type": "string", "description": "Identifier of the entity that paused the execution." }, "pause_reason": { "type": "string", "description": "Reason for pausing the execution." }, "resume_count": { "type": "integer", "description": "Number of times the execution has been resumed." }, "processing_pause_requested_at": { "type": "string", "format": "date-time", "description": "Timestamp when a pause was requested." }, "provenance_id": { "type": "string", "description": "Provenance tracking ID." }, "run_state": { "type": "string", "nullable": true, "description": "Current run state of the execution." }, "current_step": { "type": "string", "nullable": true, "description": "Current step of the execution process." } } }, "examples": { "successful_async_execution_status_retrieval": { "summary": "Successful async execution status retrieval", "description": "Retrieve detailed status of an async execution for a task.", "value": { "id": "exec_12345", "task_id": "task_67890", "agent_id": "agent_alpha", "requester_passport_id": "passport_abc123", "job_id": "job_54321", "queue_name": "mainQueue", "priority": 5, "status": "completed", "result": { "output": "success", "data": "Sample output data" }, "error": null, "progress_percent": 100, "progress_message": "Execution completed successfully.", "callback_url": "https://example.com/callback", "callback_success": true, "callback_attempts": 1, "max_attempts": 3, "current_attempt": 1, "queued_at": "2023-10-21T10:20:30Z", "started_at": "2023-10-21T10:30:00Z", "completed_at": "2023-10-21T11:00:00Z", "paused_at": null, "paused_by": null, "pause_reason": null, "resume_count": 0, "processing_pause_requested_at": null, "provenance_id": "prov_334455", "run_state": "finalized", "current_step": "summary" } } } } } }, "400": { "description": "Invalid request due to malformed execution ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_execution_id_error": { "summary": "Malformed execution ID error", "description": "The client provided an execution ID that doesn't conform to expected format.", "value": { "type": "https://human.com/probs/invalid-id", "title": "Invalid Execution ID", "status": 400, "detail": "The provided execution ID '123$$$abc' is malformed. Ensure it follows the expected format.", "errors": [ "ID must be alphanumeric." ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing delegation context", "description": "The request failed due to absence of a valid delegation context.", "value": { "type": "https://human.com/probs/missing-delegation", "title": "Missing Delegation Context", "status": 401, "detail": "A valid delegation context is required to access this resource. Ensure your credentials are correct and include a proper delegation." } } } } } }, "403": { "description": "Forbidden: The requester lacks necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions_error": { "summary": "Insufficient permissions error", "description": "The user does not have permission to access this execution status.", "value": { "type": "https://human.com/probs/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have the necessary permissions to retrieve the execution status. Contact your administrator to gain access." } } } } } }, "404": { "description": "Execution not found for the provided ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "execution_not_found_error": { "summary": "Execution not found error", "description": "The requested execution ID does not correspond to any known execution.", "value": { "type": "https://human.com/probs/not-found", "title": "Execution Not Found", "status": 404, "detail": "No execution was found with the ID 'exec_99999'. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server error example", "description": "An unexpected error occurred on the server.", "value": { "type": "https://human.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An internal error occurred while retrieving the execution status. Please try again later. If the problem persists, contact support with this incident ID: inc_1698770400000." } } } } } } } } }, "/v1/async-executions/:id/cancel": { "post": { "summary": "Cancel a queued async execution", "description": "In the dynamic world of Human-AI orchestration, speed and precision are vital. This endpoint allows you to cancel an async execution that is queued, providing agility in task management. Use it when priorities shift or tasks are no longer valid, ensuring optimal resource allocation.", "operationId": "cancelAsyncExecution", "tags": [ "AsyncExecutions", "TaskManagement" ], "x-code-hash": "c6ac56677d54ac71", "x-generated-at": "2026-03-27T23:17:25.379Z", "responses": { "200": { "description": "The execution has been successfully cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the cancelled execution" }, "status": { "type": "string", "description": "Current status of the execution" }, "completed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution was cancelled" } } }, "examples": { "successful_cancellation": { "summary": "Successful Cancellation", "description": "A successful cancellation of an async execution", "value": { "id": "execution_12345", "status": "cancelled", "completed_at": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "Bad Request due to malformed syntax or invalid request data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request": { "summary": "Malformed Request", "description": "The request was malformed and could not be processed.", "value": { "type": "https://api.human/probs/bad-request", "title": "Bad Request", "status": 400, "detail": "The request data was invalid. Check the execution ID format.", "errors": [ "Invalid execution ID." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication Error", "description": "The cancellation request failed due to lack of authentication.", "value": { "type": "https://api.human/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context. Ensure your request includes a valid Passport." } } } } } }, "404": { "description": "The specified execution was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "execution_not_found": { "summary": "Execution Not Found", "description": "The requested execution ID does not exist.", "value": { "type": "https://api.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "Async execution 'execution_12345' was not found. Verify the ID and try again." } } } } } }, "409": { "description": "Conflict because the execution cannot be cancelled.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "cancellation_conflict": { "summary": "Cancellation Conflict", "description": "The execution is in a state that cannot be cancelled.", "value": { "type": "https://api.human/probs/conflict", "title": "Conflict", "status": 409, "detail": "Cannot cancel execution 'execution_12345' as it is already completed." } } } } } }, "500": { "description": "Internal Server Error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred while processing the cancellation.", "value": { "type": "https://api.human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to cancel async execution due to an internal error. Please try again later. If the issue persists, contact support with incident ID: inc_1696513080." } } } } } } } } }, "/v1/workflows/:id/dag": { "get": { "summary": "Retrieve Workflow DAG Visual Representation", "description": "Uncover the intricate dance of tasks with a detailed Directed Acyclic Graph (DAG) for a specified workflow. This endpoint empowers users to visualize workflow orchestration, aiding in understanding complex task dependencies and execution flows.", "operationId": "getWorkflowDAG", "tags": [ "Workflows", "Visualization" ], "x-code-hash": "34746530d2c3b34e", "x-generated-at": "2026-03-29T14:49:24.935Z", "responses": { "200": { "description": "The workflow DAG was successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string", "description": "The unique identifier of the workflow." }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique node identifier within the DAG." }, "name": { "type": "string", "description": "Human-readable name of the node." }, "type": { "type": "string", "description": "Type of the node, representing task or event." } } } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "The origin node ID of the edge." }, "target": { "type": "string", "description": "The destination node ID of the edge." } } } }, "stats": { "type": "object", "description": "Statistics about the workflow execution.", "properties": { "total_nodes": { "type": "integer", "description": "Total number of nodes in the DAG." }, "total_edges": { "type": "integer", "description": "Total number of edges in the DAG." } } } } }, "examples": { "default": { "summary": "Example", "value": { "workflow_id": "workflow-123", "nodes": [ { "id": "node-1", "name": "Start Task", "type": "task" }, { "id": "node-2", "name": "Review Task", "type": "task" } ], "edges": [ { "source": "node-1", "target": "node-2" } ], "stats": { "total_nodes": 2, "total_edges": 1 } } } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "Workflow id is required.", "errors": [ { "field": "id", "code": "REQUIRED_FIELD_MISSING", "message": "Workflow id is required" } ] } } } } } }, "401": { "description": "Authentication failure due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization required. Please provide valid credentials." } } } } } }, "403": { "description": "Permission denied due to insufficient privileges.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Access to this resource is denied. Ensure proper permissions." } } } } } }, "404": { "description": "The specified workflow or its DAG could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "No workflow DAG found for ID: workflow-123. Verify the workflow ID." } } } } } }, "500": { "description": "Internal server error during DAG retrieval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Reference: inc_1696558300000." } } } } } } } } }, "/v1/workflows/:id/stats": { "get": { "summary": "Retrieve workflow execution statistics", "description": "Unlock insights into your workflows with detailed statistics. This endpoint is your gateway to understanding execution patterns, helping you optimize for efficiency and reliability. Discover the story behind every node in your workflow.", "operationId": "getWorkflowStats", "tags": [ "Workflows", "Statistics" ], "x-code-hash": "a6905604f7f9e43c", "x-generated-at": "2026-03-28T16:55:25.850Z", "responses": { "200": { "description": "Successfully retrieved workflow execution statistics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string", "description": "The unique identifier of the workflow." }, "total_runs": { "type": "integer", "description": "Total number of nodes executed in the workflow." }, "completed": { "type": "integer", "description": "Number of nodes that have completed successfully." }, "failed": { "type": "integer", "description": "Number of nodes that failed during execution." }, "avg_duration_ms": { "type": "number", "description": "Average duration of node execution in milliseconds." }, "p99_duration_ms": { "type": "number", "description": "99th percentile duration time of node execution in milliseconds." } } }, "examples": { "acme_corp_workflow_stats": { "summary": "Acme Corp Workflow Stats", "description": "Statistics for Acme Corporation's invoice processing workflow.", "value": { "workflow_id": "wf-12345", "total_runs": 150, "completed": 145, "failed": 5, "avg_duration_ms": 200, "p99_duration_ms": 350 } } } } } }, "400": { "description": "The request could not be understood by the server due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_workflow_id": { "summary": "Missing Workflow ID", "description": "The client forgot to include the workflow ID in the request.", "value": { "type": "https://developer.human/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Workflow id is required.", "errors": [ { "field": "id", "code": "REQUIRED_FIELD_MISSING", "message": "Workflow id is required", "expected": "string", "received": "undefined" } ] } } } } } }, "404": { "description": "The specified workflow could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "Attempt to retrieve stats for a non-existent workflow ID.", "value": { "type": "https://developer.human/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "Workflow with ID 'wf-12345' not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "A server-side error occurred while fetching the workflow stats.", "value": { "type": "https://developer.human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request." } } } } } } } } }, "/v1/delegations/:id/revoke": { "post": { "summary": "Revoke an existing delegation", "description": "This endpoint empowers authorized users to revoke a specific delegation, providing a mechanism for fine-tuned control over permissions. By revoking a delegation, users can ensure that only the right agents maintain access to sensitive resources, reflecting the dynamic nature of trust and responsibility in decentralized networks.", "operationId": "revokeDelegation", "tags": [ "Delegation", "Security" ], "x-code-hash": "7de86db32688039e", "x-generated-at": "2026-03-24T22:29:07.236Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Explanation for revocation" }, "metadata": { "type": "object", "description": "Additional contextual information" } }, "required": [] }, "examples": { "basic_revocation_with_reason": { "summary": "Basic revocation with reason", "description": "Revoking a delegation with a specific reason provided.", "value": { "reason": "Access no longer needed", "metadata": { "requestedBy": "admin@acme.org" } } } } } } }, "responses": { "200": { "description": "The delegation was successfully revoked, and details of the revocation are returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_id": { "type": "string", "description": "The unique identifier of the revoked delegation" }, "revoked_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the delegation was revoked" }, "revoked_by": { "type": "string", "description": "Identifier of the agent who revoked the delegation" }, "reason": { "type": "string", "description": "Reason for revocation" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided metadata field must be an object.", "errors": [ "metadata must be an object" ] } } } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Missing delegation context. Please provide valid authentication credentials." } } } } } }, "403": { "description": "The authenticated user does not have permission to revoke this delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to revoke this delegation." } } } } } }, "404": { "description": "The specified delegation was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Delegation with ID del_12345 was not found." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1697539530." } } } } } } } } }, "/v1/delegations/revocations": { "get": { "summary": "Retrieve List of Revoked Delegations", "description": "Explore the tapestry of revoked delegations to understand the nuances of permission changes over time. This endpoint serves as a historical ledger, providing a window into what was once granted and no longer stands, aiding in auditing and compliance efforts.", "operationId": "getDelegationRevocations", "tags": [ "Delegations", "Revocations" ], "x-code-hash": "4f2f8ab0ef140691", "x-generated-at": "2026-03-24T22:29:29.368Z", "responses": { "200": { "description": "Successfully retrieved the list of revoked delegations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "delegation_id": { "type": "string" }, "revoked_at": { "type": "string", "format": "date-time" }, "revoked_by": { "type": "string" }, "reason": { "type": "string" }, "metadata": { "type": "object" } }, "required": [ "delegation_id", "revoked_at", "revoked_by", "reason" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "successful_response_example": { "summary": "Successful Response Example", "description": "An example of successfully retrieving a page of revoked delegations.", "value": { "data": [ { "delegation_id": "d12345", "revoked_at": "2023-10-05T14:48:00.000Z", "revoked_by": "agent:acme:john.doe", "reason": "Permission misuse detected", "metadata": { "context": "security audit" } } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "An example where the provided cursor is invalid.", "value": { "type": "https://humanprotocol.org/probs/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor. Ensure you are using an opaque next_cursor from a previous response." } ] } } } } } }, "401": { "description": "Unauthorized access due to missing delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing Delegation Context", "description": "Example where the request is unauthorized because the delegation context is missing.", "value": { "type": "https://humanprotocol.org/probs/missing-delegation", "title": "Missing Delegation Context", "status": 401, "detail": "Authentication failed due to missing delegation context. Ensure the delegation is properly set in the context." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Example where the user does not have permission to access these revocations.", "value": { "type": "https://humanprotocol.org/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view revoked delegations. Contact your administrator to request access." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Example where the requested resource does not exist.", "value": { "type": "https://humanprotocol.org/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The resource you are attempting to access does not exist. Verify the endpoint URL and parameters." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An example of an unexpected server error.", "value": { "type": "https://humanprotocol.org/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later and report the incidentId if the issue persists.", "incidentId": "inc_1700000000000" } } } } } } } } }, "/v1/delegations/:id/status": { "get": { "summary": "Retrieve the status of a delegation", "description": "In the realm of Human-AI orchestration, understanding the status of a delegation is crucial for seamless task execution. This endpoint allows you to verify whether a delegation is active, revoked, or expired, ensuring optimal alignment between human and AI capabilities. It exists to safeguard against unauthorized actions and maintain integrity within the HUMAN ecosystem.", "operationId": "getDelegationStatus", "tags": [ "Delegations", "Status" ], "x-code-hash": "c0ff6b5e319b788a", "x-generated-at": "2026-03-24T22:30:03.992Z", "responses": { "200": { "description": "The delegation's current status is returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "revoked_at": { "type": "string", "format": "date-time" }, "revoked_by": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "delegation_id", "status" ] }, "examples": { "active_delegation": { "summary": "Active Delegation", "description": "A delegation that is currently active.", "value": { "delegation_id": "d1234", "status": "active" } }, "revoked_delegation": { "summary": "Revoked Delegation", "description": "A delegation that has been revoked due to policy violations.", "value": { "delegation_id": "d5678", "status": "revoked", "revoked_at": "2023-11-01T12:34:56Z", "revoked_by": "admin@acme.org", "reason": "Policy violations detected" } } } } } }, "400": { "description": "Bad request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_delegation_id": { "summary": "Malformed Delegation ID", "description": "The delegation ID provided is not valid.", "value": { "type": "https://example.com/probs/invalid-delegation-id", "title": "Invalid Delegation ID", "status": 400, "detail": "The delegation ID 'abc' is not properly formatted. Ensure you provide a valid delegation ID." } } } } } }, "401": { "description": "Unauthorized access due to missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing Delegation Context", "description": "No delegation context is present in the request.", "value": { "type": "https://example.com/probs/missing-delegation-context", "title": "Missing Delegation Context", "status": 401, "detail": "Authentication failed due to missing delegation context. Ensure your request includes valid delegation credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user does not have permission to view this delegation status.", "value": { "type": "https://example.com/probs/access-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access the status of this delegation. Contact your administrator for access." } } } } } }, "404": { "description": "Delegation not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_not_found": { "summary": "Delegation Not Found", "description": "The specified delegation ID does not exist.", "value": { "type": "https://example.com/probs/delegation-not-found", "title": "Delegation Not Found", "status": 404, "detail": "No delegation found with the ID 'd9999'. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred while retrieving the delegation status.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. If the issue persists, contact support with the incident ID.", "incidentId": "inc_1698303600000" } } } } } } } } }, "/v1/academy/courses": { "get": { "summary": "Retrieve curated list of academy courses", "description": "Embark on a journey to expand your knowledge with our academy's diverse course offerings. This endpoint provides a curated list of courses, complete with filtering options for category and difficulty, empowering users to tailor their learning path to their interests and skill level.", "operationId": "getAcademyCourses", "tags": [ "Education", "Courses" ], "x-code-hash": "b4507219f21e24bf", "x-generated-at": "2026-03-24T23:15:37.024Z", "responses": { "200": { "description": "Successfully retrieves the list of courses with pagination support.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "course_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "capability_ids": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string", "nullable": true }, "duration_minutes": { "type": "integer" }, "difficulty": { "type": "string" }, "is_published": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "course_id", "title", "duration_minutes", "difficulty", "is_published", "created_at" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } } }, "examples": { "successful_course_retrieval": { "summary": "Successful course retrieval", "description": "Returning a list of courses filtered by category 'Technology'.", "value": { "data": [ { "course_id": "course-101", "title": "Intro to AI", "description": "Learn the basics of artificial intelligence, including machine learning, neural networks, and more.", "capability_ids": [ "capability://ai.fundamentals" ], "category": "Technology", "duration_minutes": 120, "difficulty": "Beginner", "is_published": true, "created_at": "2023-11-01T10:00:00Z" } ], "limit": 10, "cursorField": "created_at", "hasMore": false } } } } } }, "400": { "description": "Bad Request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_difficulty_level": { "summary": "Invalid difficulty level", "description": "The difficulty parameter is not one of the allowed values.", "value": { "type": "https://example.com/probs/invalid-query-param", "title": "Invalid Query Parameter", "status": 400, "detail": "One or more query parameters are invalid.", "errors": [ { "field": "difficulty", "code": "INVALID_ENUM", "message": "difficulty must be one of: Beginner, Intermediate, Advanced", "expected": "Beginner|Intermediate|Advanced", "received": "Expert" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing credentials", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "The authenticated user does not have permission to access this resource.", "value": { "type": "https://example.com/probs/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "The specific course or category could not be found.", "value": { "type": "https://example.com/probs/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The course or category you are looking for does not exist." } } } } } }, "500": { "description": "Internal server error due to unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "description": "An unexpected error occurred on the server, preventing the request from being fulfilled.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "summary": "Create a new course offering", "description": "In the ever-evolving landscape of learning, this endpoint empowers organizations to craft new educational journeys. By enabling the creation of courses, it fuels the continuous growth of human potential, orchestrated with precision by AI.", "operationId": "createCourse", "tags": [ "Academy", "Courses" ], "x-code-hash": "249758b15edfc7aa", "x-generated-at": "2026-03-24T23:15:14.736Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the course" }, "description": { "type": "string", "description": "A detailed description of the course" }, "capability_ids": { "type": "array", "items": { "type": "string" }, "description": "List of capability identifiers needed for the course" }, "duration_minutes": { "type": "integer", "minimum": 0, "description": "Duration of the course in minutes" }, "difficulty": { "type": "string", "enum": [ "beginner", "intermediate", "advanced" ], "description": "The difficulty level of the course" }, "is_published": { "type": "boolean", "description": "Whether the course is published" }, "category": { "type": "string", "description": "The category under which the course falls" } }, "required": [ "title" ] }, "examples": { "basic_course_creation_example": { "summary": "Basic course creation example", "description": "This example demonstrates the creation of a beginner-level course on AI fundamentals.", "value": { "title": "AI Fundamentals", "description": "An introductory course to artificial intelligence.", "capability_ids": [ "capability://ai_fundamentals" ], "duration_minutes": 120, "difficulty": "beginner", "is_published": true, "category": "Technology" } } } } } }, "responses": { "201": { "description": "Course successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "course_id": { "type": "string", "description": "The unique identifier of the created course" }, "title": { "type": "string", "description": "The title of the course" }, "description": { "type": "string", "description": "The course description" }, "capability_ids": { "type": "array", "items": { "type": "string" }, "description": "The capabilities associated with the course" }, "category": { "type": "string", "description": "The course category" }, "duration_minutes": { "type": "integer", "description": "The duration of the course in minutes" }, "difficulty": { "type": "string", "description": "The difficulty of the course" }, "is_published": { "type": "boolean", "description": "Publication status of the course" }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the course was created" } } }, "examples": { "successful_course_creation_response": { "summary": "Successful course creation response", "value": { "course_id": "course-12345", "title": "AI Fundamentals", "description": "An introductory course to artificial intelligence.", "capability_ids": [ "capability://ai_fundamentals" ], "category": "Technology", "duration_minutes": 120, "difficulty": "beginner", "is_published": true, "created_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Invalid request payload", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_title_field": { "summary": "Missing title field", "value": { "type": "https://humanprotocol.org/errors/validation", "title": "Invalid request", "status": 400, "detail": "The request body is invalid.", "errors": [ { "field": "title", "code": "REQUIRED_FIELD_MISSING", "message": "title is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_error": { "summary": "Unauthorized error", "value": { "type": "https://humanprotocol.org/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid. Please provide valid credentials to access this resource." } } } } } }, "403": { "description": "Permission denied error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_error": { "summary": "Forbidden error", "value": { "type": "https://humanprotocol.org/errors/permissions", "title": "Forbidden", "status": 403, "detail": "You do not have the required permissions to create a course. Please contact your administrator." } } } } } }, "404": { "description": "Resource not found error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_error": { "summary": "Not found error", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The resource you are trying to access does not exist. Please check the URL and try again." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "https://humanprotocol.org/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/workflows": { "get": { "summary": "Retrieve paginated list of workflows", "description": "Dive into the world of orchestrated tasks with our workflow listing endpoint. This API call reveals a curated collection of workflows, each a story of human and AI collaboration, allowing you to track progress, performance, and history. It's your window into the seamless dance of tasks performed by agents, perfect for audit trails and operational oversight.", "operationId": "getWorkflows", "tags": [ "Workflow Management", "Task Orchestration" ], "x-code-hash": "044633d12bf1f109", "x-generated-at": "2026-03-28T16:54:50.920Z", "responses": { "200": { "description": "A successful response delivering a list of workflows, showcasing the orchestration of tasks and their current states.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "workflow_id": { "type": "string" }, "total_nodes": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "running": { "type": "integer" }, "pending": { "type": "integer" }, "duration_ms": { "type": "integer" }, "root_node_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "has_more": { "type": "boolean" } } }, "examples": { "acme_org's_workflow_overview": { "summary": "Acme Org's Workflow Overview", "description": "A snapshot of Acme Org's active workflows with status and metrics.", "value": { "data": [ { "workflow_id": "wf_001", "total_nodes": 5, "completed": 3, "failed": 1, "running": 1, "pending": 0, "duration_ms": 15000, "root_node_id": "node_123", "created_at": "2023-10-01T12:34:56Z" } ], "has_more": false } } } } } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor": { "summary": "Invalid Cursor", "description": "The cursor parameter was malformed.", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid cursor", "status": 400, "detail": "The cursor parameter is invalid or malformed." } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The user is not authenticated.", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect. Please provide a valid Passport token." } } } } } }, "403": { "description": "The user does not have the necessary permissions to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "The user lacks the necessary permissions.", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "The specified resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "The requested resource does not exist.", "value": { "type": "https://haio.run/errors/not_found", "title": "Not Found", "status": 404, "detail": "The resource you are looking for could not be found. Please check the request parameters and try again." } } } } } }, "500": { "description": "An internal server error occurred while retrieving workflows.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://haio.run/errors/server_error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try your request again later." } } } } } } } } }, "/v1/marketplace/connectors": { "get": { "summary": "Discover and explore marketplace connectors", "description": "Dive into the vibrant ecosystem of HUMAN's marketplace where you can explore and filter public connectors. This endpoint empowers you to search by various parameters, discovering connectors that meet your specific needs and capabilities. It's designed to enhance your interaction with the HUMAN ecosystem by providing a curated list of AI tools and connectors.", "operationId": "getMarketplaceConnectors", "tags": [ "Marketplace", "Connectors" ], "x-code-hash": "f3005a5d0ace6b0b", "x-generated-at": "2026-03-24T22:23:58.742Z", "responses": { "200": { "description": "Successfully retrieved list of marketplace connectors", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "connector_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "description": { "type": "string" }, "icon_url": { "type": "string", "format": "uri" }, "version": { "type": "string" }, "publisher_id": { "type": "string" }, "certified": { "type": "boolean" }, "pricing_model": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "install_count": { "type": "integer" }, "rating_average": { "type": "number", "format": "float" }, "rating_count": { "type": "integer" }, "oauth": { "type": "object", "properties": { "required": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "deployment_modes": { "type": "array", "items": { "type": "string" } }, "health_status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "connector_id", "name", "provider", "version", "publisher_id", "certified", "pricing_model", "capabilities", "install_count", "rating_average", "rating_count", "oauth", "deployment_modes", "health_status" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "examples": { "successful_connector_discovery": { "summary": "Successful connector discovery", "description": "An example response showing a list of connectors from the marketplace, filtering by provider 'acme'.", "value": { "data": [ { "connector_id": "connector_12345", "name": "Acme Invoice Processor", "provider": "Acme Corp", "description": "Efficiently process invoices with AI.", "icon_url": "https://example.com/icons/acme-invoice.png", "version": "1.2.3", "publisher_id": "publisher_acme", "certified": true, "pricing_model": "freemium", "capabilities": [ "invoice-processing", "data-extraction" ], "install_count": 1200, "rating_average": 4.5, "rating_count": 300, "oauth": { "required": true, "scopes": [ "read:invoices", "write:payments" ] }, "deployment_modes": [ "cloud", "on-premise" ], "health_status": "operational", "created_at": "2023-10-01T15:00:00Z" } ], "has_more": true, "next_cursor": "2" } } } } } }, "400": { "description": "Invalid query parameters were provided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid limit parameter", "value": { "type": "https://api.human.com/probs/invalid-query", "title": "Invalid Query Parameters", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ { "field": "limit", "message": "Must be a positive integer." } ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "value": { "type": "https://api.human.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/connectors/installations": { "get": { "summary": "Retrieve the organization's connector installations", "description": "Explore the landscape of connectors your organization has entrusted to carry out crucial tasks. This endpoint unveils the tapestry of installations, helping you manage and optimize the technological prowess at your disposal.", "operationId": "getConnectorInstallations", "tags": [ "Connectors", "Installations" ], "x-code-hash": "b7c65b4ee6b1ebe5", "x-generated-at": "2026-03-24T22:24:17.094Z", "responses": { "200": { "description": "A detailed list of connector installations for the authenticated organization, complete with metadata and status information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "installation_id": { "type": "string" }, "connector": { "type": "object", "properties": { "connector_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "icon_url": { "type": "string", "nullable": true } }, "required": [ "connector_id", "name", "provider" ] }, "status": { "type": "string" }, "deployment_mode": { "type": "string" }, "config": { "type": "object" }, "granted_permissions": { "type": "array", "items": { "type": "string" } }, "health_status": { "type": "string" }, "installed_by": { "type": "string" }, "installed_at": { "type": "string", "format": "date-time" }, "last_invocation_at": { "type": "string", "format": "date-time", "nullable": true }, "invocation_count_30d": { "type": "integer" } }, "required": [ "installation_id", "connector", "status", "deployment_mode", "config", "granted_permissions", "health_status", "installed_by", "installed_at", "invocation_count_30d" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "data", "has_more", "next_cursor" ] }, "examples": { "successful_installations_retrieval": { "summary": "Successful Installations Retrieval", "description": "Retrieve a list of active connectors installed by the 'acme' organization.", "value": { "data": [ { "installation_id": "install-123456", "connector": { "connector_id": "conn-42", "name": "Invoice Processor", "provider": "acme-cloud", "icon_url": "https://example.com/icons/invoice-processor.png" }, "status": "active", "deployment_mode": "cloud", "config": { "api_key": "abcd1234" }, "granted_permissions": [ "read_invoices", "write_reports" ], "health_status": "healthy", "installed_by": "user-789", "installed_at": "2023-09-15T12:34:56Z", "last_invocation_at": "2023-10-01T11:22:33Z", "invocation_count_30d": 45 } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Invalid request parameters, such as a malformed cursor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination_cursor": { "summary": "Invalid Pagination Cursor", "description": "Occurs when the cursor parameter is malformed or not recognized.", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The pagination cursor provided is invalid. Please ensure you are using a cursor returned from a previous request.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque next_cursor from GET /v1/connectors/installations (v:1 keyset)", "received": "invalidCursor123" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "description": "Occurs when the request lacks a valid delegation token.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "A valid delegation token is required to access this endpoint. Ensure your request includes an appropriate token." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An error occurred while processing the request due to an unexpected condition.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/sessions/delegation-tokens": { "post": { "summary": "Exchange Session for Scoped Delegation Token", "description": "Transform your session token into a powerful delegation token, granting you precise capabilities across the HUMAN API. Whether you're managing tasks or accessing resources, this endpoint empowers you to define the scope of your activities securely.", "operationId": "postSessionDelegationTokens", "tags": [ "Sessions", "Delegation" ], "x-code-hash": "473ca7d80d936806", "x-generated-at": "2026-04-29T22:16:59.197Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of requested capabilities. Defaults to a standard set if omitted." }, "orgDid": { "type": "string", "description": "Optional organizational DID for role-based scope." }, "required_verification_tier": { "type": "number", "description": "Minimum verification tier required for this delegation." }, "required_identity_tier": { "type": "number", "description": "Minimum identity tier required for this delegation." }, "duration_seconds": { "type": "number", "description": "Duration for which the delegation token is valid, in seconds." }, "environment": { "type": "string", "description": "Specific environment constraints for the delegation." }, "risk_level": { "type": "string", "enum": [ "low", "standard", "high" ], "description": "Risk level associated with the delegation." } } }, "examples": { "basic_delegation_request": { "summary": "Basic Delegation Request", "description": "Request with default capabilities and 24-hour duration.", "value": { "capabilities": [], "duration_seconds": 86400 } }, "organization-specific_delegation": { "summary": "Organization-Specific Delegation", "description": "Request with role-based scopes for a specific organization.", "value": { "orgDid": "did:example:org123", "required_verification_tier": 2, "required_identity_tier": 3 } } } } } }, "responses": { "200": { "description": "Delegation token successfully created, ready for use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_id": { "type": "string" }, "token": { "type": "string" }, "passport_id": { "type": "string" }, "did": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "verification_tier": { "type": "number" }, "identity_tier": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "has_companion_cp_read": { "type": "boolean" } } }, "examples": { "default": { "summary": "Example", "value": { "delegation_id": "del_123456789", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "passport_id": "did:example:user123", "did": "did:example:user123", "capabilities": [ "human_api:reasoning:run", "human_api:agents:read" ], "verification_tier": 2, "identity_tier": 3, "created_at": "2023-10-01T12:00:00Z", "expires_at": "2023-10-02T12:00:00Z", "has_companion_cp_read": false } } } } } }, "400": { "description": "Invalid request parameters or format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided capabilities array contains invalid entries.", "errors": [ "'capabilities[2]' is not a valid capability." ] } } } } } }, "401": { "description": "Unauthorized access, invalid session token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Session token is missing or invalid. Please provide a valid session token in the Authorization header." } } } } } }, "403": { "description": "Forbidden due to insufficient verification tiers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Passport verification tier 1 is below the required tier 2. Upgrade your verification at POST /v1/passports/:did/verify." } } } } } }, "404": { "description": "Resource not found, such as invalid org DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization with DID 'did:example:org123' does not exist." } } } } } }, "500": { "description": "Internal server error during token creation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please contact support with incident ID inc_1698864000.", "incidentId": "inc_1698864000" } } } } } } } } }, "/v1/deployments/compliance": { "get": { "summary": "Verify Deployment Compliance Status", "description": "Discover the compliance heartbeat of a node, ensuring its alignment with the HUMAN protocol. This endpoint is a beacon of transparency, allowing any node to validate the integrity of another's deployment operations.", "operationId": "getComplianceStatus", "tags": [ "Compliance", "Deployment" ], "x-code-hash": "e92245392daafd7d", "x-generated-at": "2026-03-24T22:59:26.587Z", "responses": { "200": { "description": "Returns the detailed compliance status, including protocol adherence and ledger sync.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment_id": { "type": "string" }, "protocol_version": { "type": "string" }, "compliance": { "type": "object", "properties": { "human_passport_minting": { "type": "string" }, "attestation_formats_accepted": { "type": "array", "items": { "type": "string" } }, "ledger_sync_status": { "type": "string" }, "passport_count": { "type": "integer" }, "verification_count": { "type": "integer" }, "last_compliance_check": { "type": "string", "format": "date-time" } } }, "invariants": { "type": "object", "properties": { "server_side_key_generation": { "type": "boolean" }, "private_key_access": { "type": "boolean" }, "biometric_binding_hash_used": { "type": "boolean" }, "webauthn_required_for_humans": { "type": "boolean" } } }, "signature": { "type": "string" } } }, "examples": { "compliant_node_status": { "summary": "Compliant Node Status", "description": "Example of a compliant node's response, showing a healthy and synchronized deployment.", "value": { "deployment_id": "node_12345", "protocol_version": "0.1", "compliance": { "human_passport_minting": "device_only", "attestation_formats_accepted": [ "none", "packed", "tpm", "android-key", "apple", "fido-u2f" ], "ledger_sync_status": "current", "passport_count": 500, "verification_count": 450, "last_compliance_check": "2023-10-21T14:48:00Z" }, "invariants": { "server_side_key_generation": false, "private_key_access": false, "biometric_binding_hash_used": true, "webauthn_required_for_humans": true }, "signature": "dXNlcm5hbWU6cGFzc3dvcmQ=" } } } } } }, "400": { "description": "Invalid request format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_error": { "summary": "Malformed Request Error", "description": "Occurs when the request lacks proper formatting.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request structure is malformed. Ensure all parameters are correctly specified." } } } } } }, "401": { "description": "Unauthorized access attempt.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Occurs when a node attempts access without proper authentication.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this endpoint. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden operation for the current user.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Occurs when a node lacks the required permissions to perform this operation.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Contact your administrator for access." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Occurs when the requested node does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested node could not be found. Verify the node ID and try again." } } } } } }, "500": { "description": "Internal server error during compliance check.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_during_compliance_check": { "summary": "Server Error During Compliance Check", "description": "An unexpected error occurred while processing the compliance status.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing the compliance check. Try again later or contact support with the incident ID inc_1697898765." } } } } } } } } }, "/v1/deployments/compliance/walled-garden-status": { "get": { "summary": "Retrieve deployment's verification status", "description": "In an interconnected digital ecosystem, understanding your deployment's verification status is pivotal. This endpoint unravels whether your deployment's passports are network verified or confined to local validation, a crucial distinction in maintaining security integrity.", "operationId": "getWalledGardenStatus", "tags": [ "Compliance", "Security" ], "x-code-hash": "1839f2363fdc1bb1", "x-generated-at": "2026-04-02T13:16:10.925Z", "responses": { "200": { "description": "Successfully retrieved the walled garden status of the deployment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "network_verification": { "type": "string", "enum": [ "local_only" ] }, "explanation": { "type": "string" }, "mitigations": { "type": "array", "items": { "type": "string" } }, "risks": { "type": "object", "properties": { "walled_garden_possible": { "type": "boolean" }, "blast_radius": { "type": "string" }, "risk_acceptance": { "type": "string" } } }, "recommendations": { "type": "array", "items": { "type": "string" } } } }, "examples": { "local_verification_example": { "summary": "Local Verification Example", "description": "An example scenario where the deployment is verified only locally.", "value": { "network_verification": "local_only", "explanation": "Passports on this deployment are verified locally. Network-wide verification requires distributed ledger integration (v0.3).", "mitigations": [ "All passports use WebAuthn device ceremonies (not server-fabricated)", "Biometric binding hashes prevent duplicate passport creation", "Attestation format and quality are recorded for each passport", "Compliance status is signed and verifiable by other nodes" ], "risks": { "walled_garden_possible": true, "blast_radius": "Local deployment only. Fake passports cannot interoperate with other deployments.", "risk_acceptance": "Canon v0.1 accepts this risk. Mitigation: enterprise deployments can require network verification for all passports." }, "recommendations": [ "Enable network verification when distributed ledger ships (v0.3)", "For enterprise: configure clients to require network-verified passports", "Monitor compliance endpoint for attestation_formats_accepted changes" ] } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameter_example": { "summary": "Invalid Parameter Example", "description": "An example of a response when invalid parameters are provided.", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid parameters", "status": 400, "detail": "The parameter 'xyz' is invalid. Please refer to the API documentation for allowed parameters." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "An example of a response when the user is unauthorized.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid. Please ensure your API key is correct." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "An example of a response when access is forbidden.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource. Please contact your system administrator." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "description": "An example of a response when the resource is not found.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource not found", "status": 404, "detail": "The requested deployment does not exist. Check the deployment ID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "An example of a response when an internal server error occurs.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/reasoning/think": { "post": { "summary": "Execute high-level reasoning tasks", "description": "In the realm of innovation, sometimes you just need to think. This endpoint orchestrates AI and human capabilities to tackle tasks ranging from coding to creative work. By balancing costs, complexity, and quality, it ensures your organization's goals are met efficiently.", "operationId": "postReasoningThink", "tags": [ "Reasoning", "AI Orchestration" ], "x-code-hash": "ae0ef818afd0c74a", "x-generated-at": "2026-03-24T22:25:12.533Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": [ "role", "content" ] } }, "task": { "type": "string", "enum": [ "reasoning", "coding", "summarization", "creative", "math", "general" ] }, "complexity": { "type": "string", "enum": [ "simple", "medium", "complex" ] }, "budget": { "type": "string", "enum": [ "minimize", "optimize", "unlimited" ] }, "pinned_model": { "type": "string" }, "entity_id": { "type": "string" }, "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } }, "required": [ "messages", "task", "complexity", "budget", "entity_id" ] }, "examples": { "basic_reasoning_request": { "summary": "Basic Reasoning Request", "description": "A request for a medium complexity reasoning task with optimized budget.", "value": { "messages": [ { "role": "user", "content": "Analyze the market trends for the next quarter." } ], "task": "reasoning", "complexity": "medium", "budget": "optimize", "entity_id": "org_acme", "temperature": 0.7, "max_tokens": 1000 } } } } } }, "responses": { "200": { "description": "Successfully executed the reasoning task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "text": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" } } } } }, "metadata": { "type": "object", "properties": { "costUsd": { "type": "number" }, "durationMs": { "type": "integer" }, "routingDecision": { "type": "object", "properties": { "selected": { "type": "string" }, "reason": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } } } } } } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad request due to missing or invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.inc/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'messages' field is required and must not be empty.", "errors": [ { "field": "messages", "code": "REQUIRED_FIELD_MISSING", "message": "messages array is required and must not be empty", "expected": "array", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.inc/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "The provided authentication credentials are invalid. Ensure your API key or token is correct." } } } } } }, "403": { "description": "Forbidden access due to budget constraints or policy restrictions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.inc/errors/budget-exceeded", "title": "Budget Exceeded", "status": 403, "detail": "The estimated cost of the task exceeds your current budget limits.", "extensions": { "max_allowed": 0.005, "estimated": 0.0075 } } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.inc/errors/not-found", "title": "Not Found", "status": 404, "detail": "The endpoint you are trying to reach does not exist. Check the URL and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.inc/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/reasoning/models": { "get": { "summary": "Retrieve available AI models and capabilities", "description": "Explore the dynamic landscape of AI models with HUMAN's orchestration endpoint. By filtering models based on provider, status, and capabilities, organizations can harness the right blend of reasoning and coding prowess to meet their unique needs. This endpoint serves as a gateway to understanding and leveraging the diverse skills housed within the HUMAN network.", "operationId": "listReasoningModels", "tags": [ "AI Models", "Capabilities" ], "x-code-hash": "af551aab612bf432", "x-generated-at": "2026-03-24T22:25:29.086Z", "responses": { "200": { "description": "Successfully retrieved a list of available AI models with their capabilities and costs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "model_id": { "type": "string" }, "provider": { "type": "string" }, "display_name": { "type": "string" }, "capabilities": { "type": "object", "properties": { "reasoning": { "type": "number" }, "coding": { "type": "number" }, "summarization": { "type": "number" }, "multilingual": { "type": "number" }, "math_reasoning": { "type": "number" }, "creative_writing": { "type": "number" }, "instruction_following": { "type": "number" } } }, "cost": { "type": "object", "properties": { "input_cost_per_million": { "type": "number" }, "output_cost_per_million": { "type": "number" } } }, "status": { "type": "string" } } } } } }, "examples": { "acme_corp's_ai_model_exploration": { "summary": "Acme Corp's AI Model Exploration", "description": "Acme Corp is filtering models by OpenAI provider and active status, seeking top-tier reasoning capabilities.", "value": { "models": [ { "model_id": "gpt-4-turbo", "provider": "openai", "display_name": "GPT-4 Turbo", "capabilities": { "reasoning": 9.5, "coding": 9, "summarization": 8.5, "multilingual": 8, "math_reasoning": 9, "creative_writing": 9.5, "instruction_following": 9.5 }, "cost": { "input_cost_per_million": 10, "output_cost_per_million": 30 }, "status": "active" } ] } } } } } }, "400": { "description": "Invalid query parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_min_reasoning_value": { "summary": "Invalid Min Reasoning Value", "value": { "type": "https://docs.humanprotocol.org/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The 'min_reasoning' query parameter must be a number between 0 and 10.", "errors": [ "min_reasoning: 'invalid_value'" ] } } } } } }, "401": { "description": "Unauthorized access to the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_api_key": { "summary": "Missing API Key", "value": { "type": "https://docs.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "An API key is required to access this endpoint. Please provide a valid key and try again." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied_for_user": { "summary": "Access Denied for User", "value": { "type": "https://docs.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Contact your administrator for access." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested model could not be found. Verify the model ID and try again." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_connection_failure": { "summary": "Database Connection Failure", "value": { "type": "https://docs.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while connecting to the database. Please try again later." } } } } } } } } }, "/v1/reasoning/benchmark": { "post": { "summary": "Submit Model Benchmark Results", "description": "Elevate the capabilities of your AI models by submitting benchmark results. This endpoint allows you to track the performance of your models across different benchmark suites, ensuring continuous improvement and reliability. Record the prowess of your models and contribute to a distributed ledger of AI excellence.", "operationId": "submitBenchmarkResults", "tags": [ "Model", "Benchmarking" ], "x-code-hash": "dabe7c91110c12d3", "x-generated-at": "2026-03-24T22:25:49.256Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model_id": { "type": "string", "description": "Unique identifier for the AI model." }, "benchmark_type": { "type": "string", "description": "Type of benchmark conducted (e.g., 'reasoning')." }, "benchmark_suite": { "type": "string", "description": "Name of the benchmark suite used (e.g., 'mmlu')." }, "score": { "type": "number", "description": "Performance score out of 100." }, "run_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the benchmark was run." }, "run_by": { "type": "string", "description": "Identifier of the system or user that ran the benchmark." }, "test_cases_passed": { "type": "integer", "description": "Number of test cases the model passed." }, "test_cases_total": { "type": "integer", "description": "Total number of test cases." }, "raw_results": { "type": "object", "description": "Detailed raw results of the benchmark." } }, "required": [ "model_id", "benchmark_type", "benchmark_suite", "score", "run_at" ] }, "examples": { "acme_corp's_reasoning_benchmark": { "summary": "Acme Corp's Reasoning Benchmark", "description": "Submitting reasoning benchmark results for Acme Corp's GPT-4 Turbo model.", "value": { "model_id": "gpt-4-turbo", "benchmark_type": "reasoning", "benchmark_suite": "mmlu", "score": 86.4, "run_at": "2024-01-25T10:30:00Z", "run_by": "system", "test_cases_passed": 432, "test_cases_total": 500, "raw_results": { "details": "Comprehensive result data here." } } } } } } }, "responses": { "201": { "description": "Benchmark submitted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the benchmark submission." }, "model_id": { "type": "string", "description": "Identifier of the model benchmarked." }, "benchmark_type": { "type": "string", "description": "Type of benchmark conducted." }, "benchmark_suite": { "type": "string", "description": "Benchmark suite used." }, "score": { "type": "number", "description": "The score achieved in the benchmark." }, "run_at": { "type": "string", "format": "date-time", "description": "When the benchmark was executed." } } }, "examples": { "default": { "summary": "Example", "value": { "id": "bench_123", "model_id": "gpt-4-turbo", "benchmark_type": "reasoning", "benchmark_suite": "mmlu", "score": 86.4, "run_at": "2024-01-25T10:30:00Z" } } } } } }, "400": { "description": "Bad Request - Validation errors occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "One or more fields contain errors.", "errors": [ { "field": "score", "message": "score must be a number (0-100)" } ] } } } } } }, "401": { "description": "Unauthorized - Authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to access this resource. Please provide your credentials." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to perform this action." } } } } } }, "404": { "description": "Not Found - Resource does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found. Verify the model_id and try again." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } } }, "/v1/prompts": { "get": { "summary": "Retrieve readable prompts with filtering", "description": "Explore the universe of prompts you're authorized to view, tailored to your specific scopes and needs. This endpoint empowers users to efficiently navigate through a curated list of prompts, filtered by pertinent criteria such as scope, type, or namespace, ensuring only relevant prompts are presented.", "operationId": "getFilteredPrompts", "tags": [ "Prompts", "Access Control" ], "x-code-hash": "bbb5ae14d9804d9d", "x-generated-at": "2026-03-24T23:18:00.315Z", "responses": { "200": { "description": "Successfully retrieved list of prompts accessible by the caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "promptKey": { "type": "string", "example": "prompt:read:123" }, "namespace": { "type": "string", "example": "acme" }, "type": { "type": "string", "example": "invoice" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z" }, "promptUri": { "type": "string", "example": "prompt://acme/invoice/123" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total_count": { "type": "integer" } } }, "examples": { "acme_corp_prompt_list": { "summary": "Acme Corp Prompt List", "description": "A list of prompts available to Acme Corp's user with read access.", "value": { "data": [ { "promptKey": "prompt:read:123", "namespace": "acme", "type": "invoice", "updatedAt": "2023-10-01T12:00:00Z", "promptUri": "prompt://acme/invoice/123" } ], "has_more": false, "next_cursor": null, "total_count": 1 } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "An example showing an error due to an invalid pagination cursor.", "value": { "type": "/problems/invalid-parameters", "title": "Invalid Request", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque next_cursor from GET /v1/prompts (v:1 keyset)", "received": "" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing delegation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "An error example due to missing delegation information.", "value": { "type": "/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required to list prompts" } } } } } }, "403": { "description": "Forbidden access due to insufficient scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_scope": { "summary": "Insufficient Scope", "description": "An error example where the user lacks the required prompt:read scope.", "value": { "type": "/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have access to these prompts" } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_error": { "summary": "Database Error", "description": "An example error when the server encounters a database issue.", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to list prompts" } } } } } } } } }, "/v1/control-plane/orgs": { "get": { "summary": "Retrieve organizations for a passport", "description": "Discover the organizations where your cryptographic identity, or Passport, is a recognized member. This endpoint allows you to navigate through your affiliations, providing a seamless connection to your roles and responsibilities across the HUMAN network.", "operationId": "getOrgsForPassport", "tags": [ "Organizations", "Identity" ], "x-code-hash": "8881665590b5beff", "x-generated-at": "2026-03-24T23:26:53.397Z", "responses": { "200": { "description": "Organizations successfully retrieved for the given passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "orgId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "nextCursor": { "type": "string" } } }, "examples": { "successful_retrieval": { "summary": "Successful retrieval", "description": "A user fetches their affiliated organizations.", "value": { "data": [ { "orgId": "org-1234", "name": "Acme Corp", "createdAt": "2023-09-10T12:34:56Z" }, { "orgId": "org-5678", "name": "Beta Industries", "createdAt": "2023-08-22T08:21:33Z" } ], "limit": 2, "nextCursor": "eyJjcmVhdGVkX2F0IjoiMjAyMy0wOC0yMlQwODoyMTozM1oifQ==" } } } } } }, "400": { "description": "Bad Request: Issues with request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid parameters", "value": { "type": "https://example.com/probs/invalid-params", "title": "Invalid query parameters", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ "limit must be a positive integer" ] } } } } } }, "401": { "description": "Unauthorized: Passport not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport authentication is required. Please ensure your cryptographic identity is valid and try again." } } } } } }, "403": { "description": "Forbidden: Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these organizations. Verify your roles and permissions." } } } } } }, "404": { "description": "Not Found: No organizations match the criteria", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_organizations_found": { "summary": "No organizations found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No organizations were found for the given passport. Check your membership status." } } } } } }, "500": { "description": "Internal Server Error: Unexpected condition encountered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } }, "post": { "summary": "Create a new organization in the HUMAN protocol", "description": "This endpoint orchestrates the creation of a new organization, weaving together identity, skills, and AI safety into a cohesive entity. It serves as the gateway for enterprising teams to join the HUMAN network, enabling them to harness distributed ledger technology for provenance and task orchestration.", "operationId": "createOrganization", "tags": [ "Organization Management", "Control Plane" ], "x-code-hash": "27a1bcf20e6a457a", "x-generated-at": "2026-03-31T03:41:06.015Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier for the organization." }, "name": { "type": "string", "description": "Human-readable name of the organization." }, "slug": { "type": "string", "description": "URL-friendly identifier, optional." }, "deployment_mode": { "type": "string", "enum": [ "cloud", "on-prem" ], "description": "Deployment preference, default is 'cloud'." }, "data_residency_tier": { "type": "string", "enum": [ "global", "regional" ], "description": "Desired data residency policy, default is 'global'." }, "autonomy_profile": { "type": "string", "enum": [ "balanced", "high", "low" ], "description": "Autonomy level for AI task routing, default is 'balanced'." } }, "required": [ "org_did", "name" ] }, "examples": { "sample_organization_creation": { "summary": "Sample Organization Creation", "description": "Creating an organization for Acme Corp with default settings.", "value": { "org_did": "did:org:acme-corp", "name": "Acme Corp", "slug": "acme-corp", "deployment_mode": "cloud", "data_residency_tier": "global", "autonomy_profile": "balanced" } } } } } }, "responses": { "201": { "description": "The organization was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier of the organization." }, "name": { "type": "string", "description": "Name of the organization." }, "slug": { "type": "string", "description": "URL-friendly identifier." }, "deployment_mode": { "type": "string", "description": "Deployment mode." }, "data_residency_tier": { "type": "string", "description": "Data residency tier." }, "autonomy_profile": { "type": "string", "description": "Autonomy profile." }, "member_roles": { "type": "object", "description": "Roles assigned to initial members." }, "vault_endpoint": { "type": "string", "description": "Endpoint for the organization's vault." } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:org:acme-corp", "name": "Acme Corp", "slug": "acme-corp", "deployment_mode": "cloud", "data_residency_tier": "global", "autonomy_profile": "balanced", "member_roles": { "did:user:12345": "OrgOwner" }, "vault_endpoint": "https://api.humanprotocol.com/v1/vault" } } } } } }, "400": { "description": "Request was malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid Request Data", "status": 400, "detail": "The request body is missing required fields.", "errors": [ { "field": "org_did", "code": "REQUIRED_FIELD_MISSING", "message": "org_did is required", "expected": "string", "received": "null" }, { "field": "name", "code": "REQUIRED_FIELD_MISSING", "message": "name is required", "expected": "string", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport token is missing or invalid. Please authenticate and try again." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create an organization. Please contact your administrator." } } } } } }, "409": { "description": "Conflict error when an organization with the provided DID already exists.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/conflict", "title": "Org Already Exists", "status": 409, "detail": "An org with org_did 'did:org:acme-corp' already exists. Try a different org_did." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace": { "get": { "summary": "Explore marketplace assets effortlessly", "description": "Venture into the HUMAN marketplace to discover a wide array of assets, curated for global visibility and approved for seamless integration. This endpoint empowers users to browse without authentication, ensuring open access to valuable resources while maintaining security for publisher-specific content.", "operationId": "getMarketplaceAssets", "tags": [ "Marketplace", "Assets" ], "x-code-hash": "7d02f4ad2ad62653", "x-generated-at": "2026-03-24T23:27:37.313Z", "responses": { "200": { "description": "A successful response containing a list of marketplace assets, filtered and paginated according to user preferences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "publisher_id": { "type": "string" }, "org_did": { "type": "string" }, "visibility": { "type": "string" }, "asset_type": { "type": "string" }, "trust_tier": { "type": "string" } } } }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" } } }, "examples": { "successful_asset_retrieval": { "summary": "Successful Asset Retrieval", "value": { "data": [ { "id": "asset-123", "name": "Invoice Processing AI", "description": "AI that automates invoice processing for efficiency.", "publisher_id": "org-456", "org_did": "did:example:org-456", "visibility": "global", "asset_type": "AI", "trust_tier": "verified" } ], "hasMore": false, "cursor": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Invalid request parameters, such as an incorrect pagination cursor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor": { "summary": "Invalid Cursor", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "The provided cursor is invalid.", "expected": "opaque cursor from previous response", "received": "invalid_cursor" } ] } } } } } }, "401": { "description": "Authentication required to access publisher-specific assets.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to list publisher assets. Please ensure you are authenticated." } } } } } }, "403": { "description": "User is not authorized to list assets for a specific publisher.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://example.com/probs/authorization-required", "title": "Not Authorized", "status": 403, "detail": "Not authorized to list assets for this publisher. Verify your organizational membership." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://example.com/probs/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The marketplace asset you are looking for does not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/control-plane/marketplace/submit": { "post": { "summary": "Submit asset for review in marketplace", "description": "Embark on a journey to elevate your asset to the marketplace stage by submitting it for a comprehensive review. This process ensures that the asset meets all standards and is ready to make an impact. Replacing the direct publish method, this submission sets the foundation for meticulous vetting, transforming your asset into a beacon of quality.", "operationId": "submitAssetForReview", "tags": [ "Marketplace", "Submission" ], "x-code-hash": "971c5a50b75df58c", "x-generated-at": "2026-04-26T23:22:13.592Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the asset." }, "asset_type": { "type": "string", "description": "The type of asset being submitted, such as extension or bundle." }, "manifest_json": { "type": "object", "description": "The manifest detailing the asset's specifications and requirements." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Additional metadata for the asset." }, "visibility": { "type": "string", "description": "The visibility level of the asset, e.g., org_private." }, "lifecycle_stage": { "type": "string", "description": "The current lifecycle stage of the asset, e.g., production." } }, "required": [ "name", "asset_type", "manifest_json" ] }, "examples": { "basic_extension_submission": { "summary": "Basic Extension Submission", "description": "Submitting an extension asset for review.", "value": { "name": "AcmeExtension", "asset_type": "extension", "manifest_json": { "version": "1.0.0", "capabilities": [ "capability://data.export" ], "required_scopes": [ "scope://read" ], "visibility": "public", "pricing": "free", "safety": "verified", "runtime": "nodejs" }, "metadata": { "author": "Acme Corp" } } } } } } }, "responses": { "201": { "description": "The asset was successfully submitted for review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the submitted asset." }, "name": { "type": "string", "description": "The name of the asset." }, "publisher_id": { "type": "string", "description": "The passport ID of the asset publisher." }, "asset_type": { "type": "string", "description": "The type of the asset." }, "review_status": { "type": "string", "description": "The current review status of the asset." } } }, "examples": { "acmeextension": { "summary": "AcmeExtension" } } } } }, "400": { "description": "The request was malformed or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing required fields", "status": 400, "detail": "name, asset_type, and manifest_json are required." } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to submit assets." } } } } } }, "404": { "description": "The resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource was not found." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/escalations": { "get": { "summary": "Retrieve pending escalation requests", "description": "Navigate the intricate web of organizational approvals by fetching escalation requests awaiting attention. Designed for orchestrating critical decision points, this endpoint empowers users to manage and respond to escalated tasks, ensuring timely resolutions and maintaining workflow integrity.", "operationId": "getEscalationRequests", "tags": [ "Escalations", "Control Plane" ], "x-code-hash": "8a7dde0e0c065466", "x-generated-at": "2026-03-24T23:34:09.247Z", "responses": { "200": { "description": "A list of escalation requests successfully retrieved, providing visibility into ongoing approval processes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the escalation request." }, "status": { "type": "string", "description": "Current status of the escalation." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the escalation was created." }, "approverPassportId": { "type": "string", "description": "Passport ID of the approver." } }, "required": [ "id", "status", "created_at", "approverPassportId" ] } }, "limit": { "type": "integer", "description": "Maximum number of records returned." }, "cursorField": { "type": "string", "description": "Field used for pagination cursor." } }, "required": [ "data", "limit", "cursorField" ] }, "examples": { "successful_escalation_retrieval": { "summary": "Successful Escalation Retrieval", "value": { "data": [ { "id": "esc12345", "status": "pending", "created_at": "2023-10-01T12:34:56Z", "approverPassportId": "passport-67890" } ], "limit": 10, "cursorField": "created_at" } } } } } }, "400": { "description": "Bad request due to invalid cursor parameter.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid cursor", "status": 400, "detail": "The cursor parameter is invalid or malformed. Ensure the cursor is a valid ISO time string." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials_example": { "summary": "Missing Credentials Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions_example": { "summary": "Insufficient Permissions Example", "value": { "type": "https://haio.run/errors/permissions", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "Resource not found due to invalid organization DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_organization_did_example": { "summary": "Invalid Organization DID Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified organization DID does not exist. Verify the DID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error_example": { "summary": "Unexpected Server Error Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/diagnostics/run": { "post": { "summary": "Execute diagnostic checks on organization", "description": "This endpoint is the pulse-checker of organizational health in the HUMAN ecosystem. It orchestrates a series of diagnostic evaluations to determine the state of an organization's systems, applying auto-remediations where autonomy policies permit. It exists to ensure that AI and human interplays are seamlessly maintained, avoiding disruptions and ensuring safety.", "operationId": "runDiagnostics", "tags": [ "Diagnostics", "Health Check" ], "x-code-hash": "131e336a2f7606fb", "x-generated-at": "2026-03-24T23:33:46.506Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The DID of the organization for which diagnostics are to be performed." } }, "required": [ "org_did" ] }, "examples": { "acme_corp_diagnostics": { "summary": "Acme Corp Diagnostics", "description": "Running diagnostics for Acme Corp identified by its DID.", "value": { "org_did": "did:org:acme" } } } } } }, "responses": { "200": { "description": "The diagnostics were executed successfully, providing insights into the system's health.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "bucket": { "type": "string" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "value": { "type": "string" }, "threshold": { "type": "string" } } } }, "autoRemediationApplied": { "type": "boolean" }, "autoRemediationsApplied": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "category": { "type": "integer" }, "reversible": { "type": "boolean" }, "rollbackId": { "type": "string" } } } }, "escalationId": { "type": [ "string", "null" ] } } }, "examples": { "successful_diagnostics": { "summary": "Successful Diagnostics", "description": "Diagnostics for Acme Corp completed with some auto-remediations applied.", "value": { "run_id": "diag-run-123456", "bucket": "degraded", "checks": [ { "name": "execution_error_rate_1h", "status": "warn", "value": "0.05", "threshold": "0.03" } ], "autoRemediationApplied": true, "autoRemediationsApplied": [ { "action": "clear_stuck_jobs", "category": 1, "reversible": true, "rollbackId": "rollback-78910" } ], "escalationId": null } } } } } }, "400": { "description": "The request was malformed, typically due to a missing required field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing org_did", "description": "The request failed because the org_did was not provided.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing org_did", "status": 400, "detail": "org_did is required.", "errors": [] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "description": "Request failed due to missing or invalid credentials.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Valid authentication credentials required." } } } } } }, "403": { "description": "Forbidden access when the requester does not have permission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have the required permissions to run diagnostics.", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "Insufficient permissions to run diagnostics." } } } } } }, "404": { "description": "The requested organization was not found in the system.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "No organization matches the given org_did.", "value": { "type": "https://haio.run/errors/not-found", "title": "Organization Not Found", "status": 404, "detail": "The specified org_did does not correspond to any existing organization." } } } } } }, "500": { "description": "An internal server error occurred while processing the diagnostic request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "A server error occurred, preventing diagnostics from completing.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during diagnostics execution." } } } } } } } } }, "/v1/control-plane/agents": { "get": { "summary": "Retrieve and navigate agent records", "description": "Dive into the orchestration realm with the ability to list and paginate through HUMAN protocol agents. This endpoint empowers you to access detailed records of agents, filtering them by status and registration time, ensuring precise control over your data exploration.", "operationId": "getControlPlaneAgents", "tags": [ "Agent Management", "Control Plane" ], "x-code-hash": "c0b2ce5a274088b7", "x-generated-at": "2026-03-24T23:33:17.174Z", "responses": { "200": { "description": "A successful retrieval of agent records, paginated based on provided parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "registered_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "next_cursor": { "type": "string" } } }, "examples": { "example_with_agents_data": { "summary": "Example with agents data", "description": "Retrieve a list of active agents with pagination.", "value": { "data": [ { "id": "agent123", "name": "Acme Agent Alpha", "status": "active", "registered_at": "2023-05-01T12:34:56Z" }, { "id": "agent124", "name": "Acme Agent Beta", "status": "active", "registered_at": "2023-04-29T11:22:33Z" } ], "limit": 2, "next_cursor": "opaque_cursor_string" } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_error": { "summary": "Invalid cursor error", "description": "The provided cursor for pagination is invalid.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The pagination cursor provided is invalid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor from previous response", "received": "invalid_cursor" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_error": { "summary": "Missing Passport error", "description": "Access denied due to missing cryptographic identity.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport is required to access this endpoint." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission denied", "description": "The user lacks the necessary capabilities to view agents.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access the agent list. Ensure your Passport has the necessary capabilities." } } } } } }, "404": { "description": "Not Found, the resource you are looking for does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent not found", "description": "The requested agent was not found in the system.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The agent you are trying to access does not exist." } } } } } }, "500": { "description": "Internal Server Error due to server malfunction.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/resources": { "post": { "summary": "Create a new resource in the system", "description": "Embark on a journey to enrich your digital ecosystem by creating a new resource within the HUMAN platform. This endpoint allows you to define and store a resource, ensuring it is uniquely identified and properly categorized. The process includes policy resolution to align with your organization's governance, making sure every resource fits seamlessly into your distributed ledger.", "operationId": "createResource", "tags": [ "Resources", "Creation" ], "x-code-hash": "e0a19406caaf710f", "x-generated-at": "2026-04-02T20:09:42.438Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uri", "kind", "owner_did" ], "properties": { "uri": { "type": "string", "description": "Canonical resource URI (must be unique)", "example": "resource://core/email/msg_abc123" }, "kind": { "type": "string", "description": "Resource kind (dot-separated namespace, e.g. core.email.message)", "example": "core.email.message" }, "owner_did": { "type": "string", "description": "Passport DID of the resource owner", "example": "did:human:did_4f5e5e62" }, "schema_id": { "type": "string", "nullable": true, "description": "Schema ID this resource conforms to (e.g. core.email.message.v1)" }, "metadata": { "type": "object", "description": "Arbitrary metadata stored alongside the resource record" }, "provenance_ref": { "type": "string", "nullable": true, "description": "Provenance chain reference ID" } } }, "examples": { "createemailresource": { "summary": "CreateEmailResource", "description": "An example to create a new email message resource for an organization.", "value": { "uri": "resource://core/email/msg_abc123", "kind": "core.email.message", "owner_did": "did:human:did_4f5e5e62", "schema_id": "core.email.message.v1", "metadata": { "subject": "Quarterly Report", "tags": [ "finance", "Q1" ] }, "provenance_ref": "prov_123456" } } } } } }, "responses": { "201": { "description": "The resource was successfully created, contributing to the dynamic tapestry of your organization's data landscape.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uri": { "type": "string", "description": "The unique identifier for the created resource" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the resource was created" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was malformed or missing required fields. Please ensure all required fields are provided and correctly formatted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "422": { "description": "Resource creation failed due to missing policy configuration. Ensure your organization has a defined resource policy.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "An internal server error occurred while processing the request. Please try again later or contact support with the incident ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } }, "get": { "summary": "Retrieve Active Resources List", "description": "Discover the available resources within the HUMAN platform, filtered by various criteria to suit your needs. This endpoint empowers you to efficiently navigate through a wealth of active resources, ensuring you have the right data at your fingertips.", "operationId": "listResources", "tags": [ "Resources" ], "x-code-hash": "ae0b2caabd4a338b", "x-generated-at": "2026-04-02T20:10:06.122Z", "responses": { "200": { "description": "A successful response with a paginated list of resources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string" }, "uri": { "type": "string" }, "owner_did": { "type": "string" }, "controller_did": { "type": "string" }, "kind": { "type": "string" }, "schema_id": { "type": "string" }, "connector_id": { "type": "string" }, "metadata": { "type": "object" }, "provenance_ref": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "limit": { "type": "integer" }, "next_cursor": { "type": "string" } } }, "examples": { "resources_for_acme_corp": { "summary": "Resources for Acme Corp", "description": "Returns a list of email message resources owned by Acme Corp, filtered by connector ID.", "value": { "data": [ { "resource_id": "res_12345", "uri": "resource://acme/email/67890", "owner_did": "did:human:acme123", "controller_did": "did:human:controller123", "kind": "core.email.message", "schema_id": "schema_abc", "connector_id": "conn_67890", "metadata": {}, "provenance_ref": "prov_98765", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T12:00:00Z", "deleted_at": null } ], "limit": 20, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMy0xMC0wMVQxMjowMDowMFoifQ==" } } } } } }, "400": { "description": "Bad request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit": { "summary": "Invalid Limit", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "The specified limit exceeds the maximum allowed value.", "errors": [ { "field": "limit", "code": "OUT_OF_RANGE", "message": "The limit must be between 1 and 100.", "expected": "1-100", "received": "150" } ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_token": { "summary": "Missing Token", "value": { "type": "https://example.com/probs/auth-required", "title": "Unauthorized", "status": 401, "detail": "Authentication token is required to access this resource." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://example.com/probs/access-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these resources." } } } } } }, "404": { "description": "Resource not found for the given query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://example.com/probs/resource-not-found", "title": "Not Found", "status": 404, "detail": "No resources match the specified criteria." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_error": { "summary": "Database Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/schemas/effective": { "get": { "summary": "Retrieve effective schema for an organization", "description": "In the dynamic world of Human-AI orchestration, schemas define how data is structured and understood. This endpoint unveils the effective schema for a given organization and resource kind, ensuring the most precise and current configuration is applied. It caters to organizations like 'acme' that need tailored data handling based on their unique preferences and the latest standards.", "operationId": "getEffectiveSchema", "tags": [ "Schemas", "Configuration" ], "x-code-hash": "19cb805b1d647347", "x-generated-at": "2026-03-24T23:00:36.747Z", "responses": { "200": { "description": "The endpoint successfully returns the effective schema tailored for the specified organization and resource kind.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaId": { "type": "string" }, "definition": { "type": "object" } }, "required": [ "schemaId", "definition" ] }, "examples": { "successful_retrieval": { "summary": "Successful retrieval", "value": { "schemaId": "schema:acme:core.email.message:v2", "definition": { "title": "Email Message Schema", "properties": { "subject": { "type": "string" }, "body": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "400": { "description": "The request is malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_parameters": { "summary": "Missing Parameters", "value": { "type": "https://example.com/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "The request is missing required query parameters.", "errors": [ { "field": "org_did", "code": "REQUIRED_FIELD_MISSING", "message": "org_did query parameter is required", "expected": "string", "received": "undefined" } ] } } } } } }, "404": { "description": "No schema is available for the specified kind.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schema_not_found": { "summary": "Schema Not Found", "value": { "type": "https://example.com/probs/resource-not-found", "title": "Schema Not Found", "status": 404, "detail": "No schema registered for kind \"core.email.message\"", "kind": "core.email.message", "org_did": "did:org:acme" } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/schemas": { "post": { "summary": "Register a new resource schema", "description": "In the dynamic realm of digital resources, schemas are the blueprints that guide interaction. This endpoint empowers organizations to register new schema versions, ensuring consistent understanding and validation across distributed systems. By enforcing authority rules, it safeguards namespace integrity, aligning with HUMAN's commitment to secure and trustworthy orchestration.", "operationId": "registerSchema", "tags": [ "Schemas", "Registration" ], "x-code-hash": "4d19299e6c1334b5", "x-generated-at": "2026-03-24T23:01:01.372Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "definition", "authority_did", "created_by" ], "properties": { "kind": { "type": "string", "description": "The resource kind identifier (e.g., core.email.message).", "example": "core.email.message" }, "definition": { "type": "object", "description": "A JSON Schema (draft 2020-12) detailing the structure of the resource kind." }, "authority_did": { "type": "string", "description": "The Decentralized Identifier (DID) claiming authority over this kind's namespace." }, "created_by": { "type": "string", "description": "DID of the entity (human or CI) registering the schema." } } }, "examples": { "registering_an_email_message_schema": { "summary": "Registering an Email Message Schema", "description": "Shows registration of a schema for email messages within the core namespace.", "value": { "kind": "core.email.message", "definition": { "type": "object", "properties": { "subject": { "type": "string" }, "body": { "type": "string" }, "sender": { "type": "string" } }, "required": [ "subject", "body", "sender" ] }, "authority_did": "did:org:human", "created_by": "did:agent:regina-phalange" } } } } } }, "responses": { "201": { "description": "The schema was successfully registered, ensuring future interactions align with the defined structure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "registered_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example", "value": { "kind": "core.email.message", "registered_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "The request was invalid due to malformed input. Ensure all required fields are correctly formatted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-input", "title": "Invalid Input", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "kind", "code": "REQUIRED_FIELD_MISSING", "message": "kind is required", "expected": "string", "received": "undefined" } ] } } } } } }, "403": { "description": "The authority DID is not permitted to register this schema kind, enforcing namespace security.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/insufficient-permissions", "title": "Authority Violation", "status": 403, "detail": "The provided authority_did is not authorized for the core namespace.", "kind": "core.email.message", "authority_did": "did:org:unauthorized" } } } } } }, "409": { "description": "A schema with the same kind already exists, indicating a potential conflict in registration.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/conflict", "title": "Conflict", "status": 409, "detail": "Schema registration conflict for kind \"core.email.message\"." } } } } } }, "500": { "description": "An unexpected error occurred on the server, hindering schema registration.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An internal server error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve registered schema list", "description": "Delve into the intricacies of schema management with the HUMAN platform. This endpoint unveils a comprehensive, cursor-paginated catalog of registered schemas, essential for orchestrating Human-AI interactions. Tailor your query with precision by utilizing filters for 'kind' and 'authority DID', ensuring you access exactly what you need.", "operationId": "listSchemas", "tags": [ "Schemas", "Data Management" ], "x-code-hash": "9a32ad8e3bbe2d37", "x-generated-at": "2026-03-24T23:01:24.316Z", "responses": { "200": { "description": "A successful response returns a paginated list of schemas, each enriched with metadata such as authority DID, kind, and creation details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "schema_id": { "type": "string" }, "authority_did": { "type": "string" }, "kind": { "type": "string" }, "version": { "type": "string" }, "definition": { "type": "string" }, "created_by": { "type": "string" }, "supersedes_id": { "type": "string" }, "content_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "cursorField": { "type": "string" } } }, "examples": { "successful_schema_retrieval": { "summary": "Successful schema retrieval", "description": "Fetches the first page of schemas, revealing the structure and metadata of each entry.", "value": { "data": [ { "schema_id": "12345", "authority_did": "did:example:authority1", "kind": "invoice", "version": "1.0", "definition": "Schema definition content", "created_by": "user_67890", "supersedes_id": "12344", "content_hash": "hash123", "created_at": "2023-09-01T12:00:00Z", "updated_at": "2023-09-02T12:00:00Z" } ], "hasMore": false, "limit": 20, "cursorField": "created_at" } } } } } }, "400": { "description": "The request was malformed or contained invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor": { "summary": "Invalid cursor", "description": "The pagination cursor provided was not valid.", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid request parameters", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor: 'abc123'. Please provide a valid cursor token." } ] } } } } } }, "401": { "description": "Unauthorized access to the schema listing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "The user failed to provide valid authentication credentials.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication required", "status": 401, "detail": "You must be authenticated to access this resource. Please provide valid credentials." } } } } } }, "403": { "description": "Permission denied for accessing schema data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "description": "The user does not have the necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Access forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "The specified schema was not found.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource not found", "status": 404, "detail": "The schema you are looking for does not exist. Please check the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "The server encountered an internal error.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/org_schema_prefs": { "get": { "summary": "Retrieve organizational schema preferences", "description": "Dive into the world of schemas where each organization defines its unique structure. This endpoint allows you to explore and manage how an organization's data is expected to be shaped, enabling precise data orchestration and ensuring compatibility. By mapping data kinds to preferred schemas, organizations can maintain consistency and control over their data landscape.", "operationId": "listOrgSchemaPrefs", "tags": [ "OrgSchemaPrefs" ], "x-code-hash": "c47cfb991088c9a2", "x-generated-at": "2026-03-24T23:01:39.123Z", "responses": { "200": { "description": "Successfully retrieves a paginated list of schema preferences for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "org_did": { "type": "string", "example": "did:org:acme" }, "kind_pattern": { "type": "string", "example": "invoice.*" }, "preferred_schema_id": { "type": "string", "example": "schema:invoice_v1" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-10-15T08:55:30Z" } } } }, "limit": { "type": "integer", "example": 20 }, "cursorField": { "type": "string", "example": "created_at" }, "hasMore": { "type": "boolean", "example": true } } }, "examples": { "successful_response_example": { "summary": "Successful Response Example", "description": "A snapshot of the schema preferences for the 'acme' organization.", "value": { "data": [ { "org_did": "did:org:acme", "kind_pattern": "invoice.*", "preferred_schema_id": "schema:invoice_v1", "created_at": "2023-10-15T08:55:30Z" } ], "limit": 20, "cursorField": "created_at", "hasMore": true } } } } } }, "400": { "description": "Bad Request - The request parameters are invalid, such as a missing required field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing org_did", "description": "The request is missing the required org_did parameter.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "org_did query parameter is required.", "errors": [ { "field": "org_did", "code": "REQUIRED_FIELD_MISSING", "message": "org_did query parameter is required.", "expected": "string (org DID)", "received": "undefined" } ] } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An example of a server error response when listing schema preferences.", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to list org schema preferences, please try again later." } } } } } } } }, "put": { "summary": "Upsert organization schema preferences", "description": "In the dynamic world of schema management, this endpoint empowers organizations to define and refine their schema preferences with precision. Whether it's a new schema pattern or an update to an existing one, this ensures that the most relevant schema is always at the forefront, aiding efficient task routing and AI interactions.", "operationId": "upsertOrgSchemaPref", "tags": [ "OrgSchemaPrefs" ], "x-code-hash": "7c399aab6c038101", "x-generated-at": "2026-03-24T23:01:56.989Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "org_did", "kind_pattern", "preferred_schema_id" ], "properties": { "org_did": { "type": "string", "description": "A unique identifier for the organization in the form of a DID.", "example": "did:org:acme" }, "kind_pattern": { "type": "string", "description": "A kind or glob pattern for which the schema preference is being set.", "example": "core.health.*" }, "preferred_schema_id": { "type": "string", "description": "The identifier of the schema that the organization prefers.", "example": "core.health.ct_scan.v1" } } }, "examples": { "set_ct_scan_schema_preference": { "summary": "Set CT Scan Schema Preference", "description": "This example demonstrates setting a preferred schema for health-related data within the Acme organization.", "value": { "org_did": "did:org:acme", "kind_pattern": "core.health.*", "preferred_schema_id": "core.health.ct_scan.v1" } } } } } }, "responses": { "200": { "description": "The organization’s schema preference was successfully created or updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "example": "did:org:acme" }, "kind_pattern": { "type": "string", "example": "core.health.*" }, "preferred_schema_id": { "type": "string", "example": "core.health.ct_scan.v1" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z" } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:org:acme", "kind_pattern": "core.health.*", "preferred_schema_id": "core.health.ct_scan.v1", "created_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Invalid input data or JSON format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-input", "title": "Invalid Input", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "org_did", "code": "REQUIRED_FIELD_MISSING", "message": "org_did is required" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The specified schema ID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/schema-not-found", "title": "Schema Not Found", "status": 404, "detail": "The preferred_schema_id \"core.health.ct_scan.v1\" does not exist in the schema registry." } } } } } }, "500": { "description": "Internal server error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "summary": "Remove organization schema preference", "description": "In the realm of digital orchestration, it's crucial to manage the schemas that guide your organization. This endpoint allows you to delete an existing schema preference by specifying its unique organization DID and kind pattern. Once removed, the system will revert to the latest default schema, ensuring seamless continuity.", "operationId": "deleteOrgSchemaPref", "tags": [ "OrgSchemaPrefs", "Configuration" ], "x-code-hash": "77e4566886cbddbd", "x-generated-at": "2026-03-24T23:02:14.573Z", "responses": { "200": { "description": "The schema preference was successfully deleted, allowing the organization to default to the latest schema.", "content": { "application/json": {} } }, "400": { "description": "The request was invalid, typically due to missing or incorrect fields. Ensure all required fields are provided and correctly formatted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication failed. Ensure that your request includes a valid Passport credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "You do not have permission to delete this schema preference. Verify your access rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified schema preference was not found. Double-check the org DID and kind pattern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "The server encountered an error while processing your request. Please try again later or contact support if the issue persists.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/ready": { "get": { "summary": "Check platform readiness and component health", "description": "The GET /ready endpoint provides a vital snapshot of the HUMAN platform's operational status, ensuring that both the database and Redis components are functioning correctly. This health check empowers system administrators to maintain a seamless orchestration of Human-AI tasks by proactively identifying and addressing potential service disruptions.", "operationId": "getPlatformReadiness", "tags": [ "Operations", "Health" ], "x-code-hash": "37f57124cf2e8dba", "x-generated-at": "2026-03-31T03:38:27.520Z", "responses": { "200": { "description": "The platform is fully operational, with all components connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "database": { "type": "string" }, "redis": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "examples": { "healthy_system": { "summary": "Healthy System", "description": "The system is fully operational, with all components connected.", "value": { "ready": true, "database": "connected", "redis": "connected", "timestamp": "2023-03-15T12:45:30.000Z" } } } } } }, "503": { "description": "Service unavailable due to component disconnection.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_disconnected": { "summary": "Database Disconnected", "description": "The database connection is down, affecting platform readiness.", "value": { "type": "https://humanplatform.com/problems/database-disconnected", "title": "Service Unavailable", "status": 503, "detail": "The database connection is currently down. Please ensure the database service is running and accessible." } }, "redis_error": { "summary": "Redis Error", "description": "An error occurred with the Redis component.", "value": { "type": "https://humanplatform.com/problems/redis-error", "title": "Service Unavailable", "status": 503, "detail": "The Redis service encountered an error during health check. Verify Redis configuration and connectivity." } } } } } } } } }, "/v1/passport/grants": { "get": { "summary": "Retrieve Grants for Authenticated User", "description": "Explore the intricate web of permissions with the HUMAN platform by listing all grants where you are the granter. This endpoint unifies both delegation and capability grants into a single view, empowering you to understand and manage the permissions you have bestowed.", "operationId": "getPassportGrants", "tags": [ "Identity", "Permissions" ], "x-code-hash": "fac1011c0683e182", "x-generated-at": "2026-04-11T01:51:27.182Z", "responses": { "200": { "description": "A successful response returns a paginated list of grants that the authenticated user has issued, allowing for introspection and management of delegated permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "grantId": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "grantId", "created_at", "status", "kind" ] } }, "limit": { "type": "integer" }, "nextCursor": { "type": "string" } }, "required": [ "data", "limit" ] }, "examples": { "successful_grants_retrieval": { "summary": "Successful grants retrieval", "value": { "data": [ { "grantId": "grant_12345", "created_at": "2023-10-05T14:48:00.000Z", "status": "active", "kind": "delegation" }, { "grantId": "grant_67890", "created_at": "2023-09-30T10:24:00.000Z", "status": "revoked", "kind": "capability" } ], "limit": 10, "nextCursor": "cursor_string" } } } } } }, "400": { "description": "The request was malformed, possibly due to an invalid pagination cursor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_error": { "summary": "Invalid cursor error", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid Pagination Cursor", "status": 400, "detail": "The pagination cursor provided is not valid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "valid cursor token", "received": "invalid_cursor_string" } ] } } } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication required", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Passport authentication required to view grants" } } } } } }, "403": { "description": "The authenticated user does not have permission to view the requested grants.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission denied", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have the required permissions to view these grants." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Incident ID: inc_1234567890" } } } } } } } } }, "/v1/passport/grants/:grant_id": { "get": { "summary": "Retrieve Detailed Grant Information", "description": "Uncover the full potential of your grant by retrieving detailed information including scopes, constraints, and usage history. This endpoint empowers the granter to manage and review their own grants, ensuring security and transparency in capabilities sharing.", "operationId": "getPassportGrantById", "tags": [ "Passport", "Grants" ], "x-code-hash": "362d983a36b6021d", "x-generated-at": "2026-04-11T01:51:40.704Z", "responses": { "200": { "description": "Successfully retrieved grant details including scopes, constraints, and last usage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "description": "The unique identifier for the grant." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "The list of scopes associated with this grant." }, "constraints": { "type": "object", "description": "Constraints applied to the grant.", "additionalProperties": true }, "last_used_at": { "type": "string", "format": "date-time", "description": "The last time this grant was used." } }, "required": [ "grant_id", "scopes", "constraints", "last_used_at" ] }, "examples": { "acme_organization_grant_example": { "summary": "Acme Organization Grant Example", "description": "An example response for retrieving a grant used by the Acme organization.", "value": { "grant_id": "grant123", "scopes": [ "capability://data.read", "capability://data.write" ], "constraints": { "maxUsage": 1000, "validUntil": "2024-12-31T23:59:59Z" }, "last_used_at": "2023-10-21T15:23:45Z" } } } } } }, "400": { "description": "Invalid request due to malformed grant ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_grant_id_example": { "summary": "Malformed Grant ID Example", "description": "An example of a malformed grant ID error.", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided grant ID '123!' is malformed. Please ensure the grant ID is correctly formatted." } } } } } }, "401": { "description": "Authentication required to access grant information.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required_example": { "summary": "Authentication Required Example", "description": "An example response when authentication is not provided.", "value": { "type": "https://docs.humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Passport authentication required. Please provide valid credentials." } } } } } }, "403": { "description": "Permission denied for accessing another user's grant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied_example": { "summary": "Permission Denied Example", "description": "An example response when trying to access a grant that belongs to another user.", "value": { "type": "https://docs.humanprotocol.org/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access this grant. Ensure you are the granter of this grant." } } } } } }, "404": { "description": "Grant not found for the provided ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "grant_not_found_example": { "summary": "Grant Not Found Example", "description": "An example response when a grant with the specified ID is not found.", "value": { "type": "https://docs.humanprotocol.org/errors/grant-not-found", "title": "Grant Not Found", "status": 404, "detail": "No grant found with ID 'grant123'. Please verify the ID and try again." } } } } } }, "500": { "description": "Internal server error occurred while retrieving the grant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "An example response when an internal error occurs.", "value": { "type": "https://docs.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the grant. Please try again later." } } } } } } } } }, "/v1/passport/grants/:grant_id/revoke": { "post": { "summary": "Revoke a specific passport grant", "description": "In the intricate dance of digital identity, sometimes you need to call back a partner. This endpoint allows a user to revoke a specific grant, immediately updating its status. It ensures that only the rightful owner of the digital identity can perform such a critical action, maintaining trust in our distributed ecosystem.", "operationId": "revokePassportGrant", "tags": [ "Identity", "Security" ], "x-code-hash": "80bbffb1849cbc98", "x-generated-at": "2026-04-11T01:51:54.867Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for revocation, providing context for the action" } } }, "examples": { "revoke_with_reason": { "summary": "Revoke with reason", "description": "Revoking a grant with an explanation", "value": { "reason": "No longer needed for current project" } } } } } }, "responses": { "200": { "description": "Grant successfully revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "description": "Identifier of the revoked grant" }, "grant_type": { "type": "string", "description": "Type of the grant, indicating delegation or capability" }, "status": { "type": "string", "enum": [ "revoked" ], "description": "Current status of the grant" }, "revoked_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the grant was revoked" }, "revoked_by": { "type": "string", "description": "DID of the user who revoked the grant" }, "reason": { "type": [ "string", "null" ], "description": "Reason for revocation if provided" } } }, "examples": { "default": { "summary": "Example", "value": { "grant_id": "grant_12345", "grant_type": "delegation", "status": "revoked", "revoked_at": "2023-10-12T08:45:30Z", "revoked_by": "did:example:123456789abcdefghi", "reason": "No longer required" } } } } } }, "400": { "description": "Invalid request format or missing data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body is malformed. Ensure JSON is correctly formatted." } } } } } }, "401": { "description": "User is not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Passport authentication required. Ensure you are logged in and try again." } } } } } }, "403": { "description": "User does not have permission to revoke this grant", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to revoke this grant. Check your access rights." } } } } } }, "404": { "description": "Grant not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Grant Not Found", "status": 404, "detail": "The specified grant ID could not be found. Verify the grant ID and try again." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. If the problem persists, contact support with incident ID: inc_1696437930123." } } } } } } } } }, "/v1/passport/grants/:grant_id/narrow": { "post": { "summary": "Narrow scopes on a delegation grant", "description": "In the intricate dance of permissions and trust, sometimes it becomes necessary to tighten the reins. This endpoint allows an organization to refine the permissions they've granted, ensuring the recipient can only access what's truly essential. It's about maintaining control in a dynamic environment.", "operationId": "narrowDelegationGrant", "tags": [ "Passport", "Delegation" ], "x-code-hash": "ec5703ab633890bc", "x-generated-at": "2026-04-11T01:52:05.868Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "string" }, "description": "A strict subset of the current scopes to narrow the delegation." }, "constraints": { "type": "object", "description": "Additional conditions applied to the delegation grant." } }, "required": [ "scopes", "constraints" ] }, "examples": { "narrow_scopes_example": { "summary": "Narrow Scopes Example", "description": "An example where the grant is narrowed to only include 'read:invoices' scope.", "value": { "scopes": [ "read:invoices" ], "constraints": { "maxUsage": 100 } } } } } } }, "responses": { "200": { "description": "Successfully narrowed the delegation grant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grantId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "constraints": { "type": "object" }, "status": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing required fields or invalid scopes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified grant could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/passport/grants/:grant_id/pause": { "post": { "summary": "Pause an active delegation grant", "description": "In the intricate dance of human and AI collaboration, there may come a time when a delegation grant needs a pause — a momentary rest to reassess or reallocate resources. This endpoint allows you to hit that pause button, ensuring the grant remains dormant yet poised for future reactivation.", "operationId": "pauseDelegationGrant", "tags": [ "Passport", "Delegation" ], "x-code-hash": "293e628932521ddb", "x-generated-at": "2026-04-11T01:52:17.368Z", "responses": { "200": { "description": "The delegation grant was successfully paused, effectively deactivating it until further notice while keeping it retrievable for future actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_id": { "type": "string", "description": "The unique identifier of the delegation grant." }, "status": { "type": "string", "description": "The current status of the delegation grant, expected to be 'paused'." }, "grantor_did": { "type": "string", "description": "Decentralized Identifier (DID) of the grantor." } }, "required": [ "delegation_id", "status", "grantor_did" ] }, "examples": { "successful_pause_of_grant": { "summary": "Successful pause of grant", "description": "Pausing a delegation grant for the 'acme' organization.", "value": { "delegation_id": "grant_12345", "status": "paused", "grantor_did": "did:human:acme" } } } } } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_grant_id": { "summary": "Invalid grant ID", "description": "The provided grant ID was not valid.", "value": { "type": "/errors/invalid-input", "title": "Invalid Request", "status": 400, "detail": "The grant ID provided does not match the expected format. Please ensure the grant ID is correct and try again." } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication required", "description": "No authentication was provided in the request.", "value": { "type": "/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Passport authentication is required to pause a delegation grant. Please provide valid authentication credentials and try again." } } } } } }, "403": { "description": "Forbidden action: the user lacks permission to pause the grant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission denied", "description": "The user is not allowed to pause this grant.", "value": { "type": "/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to pause this delegation grant. Please check your credentials and permissions, and try again." } } } } } }, "404": { "description": "The specified delegation grant was not found or is not active.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "grant_not_found": { "summary": "Grant not found", "description": "The delegation grant with the given ID was not found.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Active delegation grant grant_12345 not found. Please verify the grant ID and ensure it is active before attempting to pause." } } } } } }, "500": { "description": "Internal server error encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "description": "Unexpected error occurred on the server side.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while attempting to pause the delegation grant. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passport/grants/:grant_id/unpause": { "post": { "summary": "Unpause a paused delegation grant", "description": "In the symphony of human and AI collaboration, sometimes we need to hit pause. But when you're ready to resume the dance, this endpoint lets you seamlessly transition a paused delegation grant back to its active state. It's your cue to continue orchestrating magic.", "operationId": "unpauseDelegationGrant", "tags": [ "Identity", "Delegation" ], "x-code-hash": "e71e1a1ca3117d8f", "x-generated-at": "2026-04-11T01:52:28.591Z", "responses": { "200": { "description": "The delegation grant has been successfully unpaused, allowing activities to resume.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_id": { "type": "string", "description": "The unique identifier of the delegation grant" }, "status": { "type": "string", "enum": [ "active" ], "description": "The updated status of the grant" } } }, "examples": { "successful_unpause_example": { "summary": "Successful Unpause Example", "description": "Successfully unpausing a delegation grant for user interaction to continue.", "value": { "delegation_id": "grant_12345", "status": "active" } } } } } }, "400": { "description": "Bad request due to invalid input or malformed request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_grant_id": { "summary": "Invalid Grant ID", "description": "The provided grant_id was invalid or improperly formatted.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The grant_id 'invalid_id' is not a valid format. Ensure it matches the expected pattern." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_header": { "summary": "Missing Authentication Header", "description": "The request did not include the necessary Passport authentication.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport authentication required. Please include a valid Passport token in the request." } } } } } }, "404": { "description": "The specified delegation grant was not found or is not in a paused state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "grant_not_found": { "summary": "Grant Not Found", "description": "The specified grant_id does not correspond to any paused delegation grant.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Paused delegation grant 'grant_12345' not found. Verify the grant ID and ensure it is paused." } } } } } }, "500": { "description": "An unexpected error occurred while attempting to unpause the grant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An unexpected issue occurred on the server side.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Incident ID: inc_1234567890" } } } } } } } } }, "/v1/passport/grants/:grant_id/expire": { "post": { "summary": "Expire an active delegation grant early", "description": "In the intricate world of Human-AI collaboration, timing is everything. This endpoint allows you to shorten the expiry of an active delegation grant, ensuring that permissions are curtailed as needed. By empowering users to manage time-sensitive access, we enhance security and control.", "operationId": "expireDelegationGrant", "tags": [ "Passport", "Grants" ], "x-code-hash": "f6d35d14af523bf4", "x-generated-at": "2026-04-11T01:52:39.973Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time", "description": "The new expiry date, which must be a valid ISO 8601 timestamp and cannot extend the current expiry." } }, "required": [ "expires_at" ] }, "examples": { "shorten_grant_expiry": { "summary": "Shorten Grant Expiry", "description": "This example shows how to shorten the expiry of a grant to a specific future date.", "value": { "expires_at": "2023-12-31T23:59:59Z" } } } } } }, "responses": { "200": { "description": "Successfully updated the expiry date of the delegation grant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "description": "Unique identifier of the delegation grant." }, "expires_at": { "type": "string", "format": "date-time", "description": "The new expiry date of the grant." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was invalid due to improper input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-input", "title": "Invalid Input", "status": 400, "detail": "The expires_at field must be a valid ISO 8601 timestamp", "errors": [ { "field": "expires_at", "code": "INVALID_VALUE", "message": "expires_at must be a valid ISO 8601 timestamp", "expected": "ISO 8601 timestamp", "received": "not-a-timestamp" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Passport authentication required. Please provide valid credentials." } } } } } }, "403": { "description": "Access to modify the grant is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to modify this grant. Ensure you have the correct access rights." } } } } } }, "404": { "description": "The specified delegation grant was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Active delegation grant grant-12345 not found. Verify the grant_id or check its status." } } } } } }, "500": { "description": "An internal error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID inc_123456789." } } } } } } } } }, "/v1/passport/activity/:event_id/proof": { "get": { "summary": "Retrieve Merkle proof for event verification", "description": "Unlock the cryptographic assurance of your event's integrity with a Merkle proof. This endpoint provides the cryptographic evidence necessary to independently verify an event's presence in the ledger, championing transparency and decentralization by eliminating reliance on HUMΛN's internal databases.", "operationId": "getActivityEventProof", "tags": [ "Passport", "Ledger" ], "x-code-hash": "f44ebdf589ac2bc5", "x-generated-at": "2026-04-11T01:53:14.132Z", "responses": { "200": { "description": "Successfully retrieved the Merkle proof for the event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string" }, "content_hash": { "type": "string" }, "ledger_anchor_ref": { "type": "string" }, "proof": { "type": "object", "properties": { "leaf": { "type": "string" }, "root": { "type": "string" }, "siblings": { "type": "array", "items": { "type": "string" } }, "path": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1 ] } } } } } }, "examples": { "successful_proof_retrieval": { "summary": "Successful Proof Retrieval", "description": "A successful retrieval of the Merkle proof for a specific event.", "value": { "event_id": "event_123456", "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "ledger_anchor_ref": "anchor_78910", "proof": { "leaf": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "root": "9b74c9897bac770ffc029102a200c5deaad1c519e1c1c7c7415e7c42e0b7a572", "siblings": [ "abcdef...", "123456..." ], "path": [ 0, 1, 0 ] } } } } } } }, "404": { "description": "Event not found or not yet anchored.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "event_not_anchored": { "summary": "Event Not Anchored", "description": "The event is either not found or has not been anchored yet.", "value": { "type": "https://human.co/errors/not-anchored", "title": "Event Not Yet Anchored", "status": 404, "detail": "This event has no ledger anchor reference. It may have been written before Wave 3.2 was deployed, or the fire-and-forget attestation is still pending.", "event_id": "event_123456", "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } } } } } }, "503": { "description": "Ledger configuration issue.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ledger_unavailable": { "summary": "Ledger Unavailable", "description": "The ledger is not configured or reachable.", "value": { "type": "https://human.co/errors/ledger-unavailable", "title": "Ledger Not Configured", "status": 503, "detail": "The distributed ledger is not configured in this environment." } } } } } } } } }, "/v1/passport/service-accounts": { "post": { "summary": "Create a new service account", "description": "This endpoint empowers organizations to create service accounts linked to their digital identity, enhancing automated interactions with HUMAN's ecosystem. Service accounts facilitate automated access to resources, allowing seamless integration while maintaining security through scoped permissions and IP allowlists.", "operationId": "createServiceAccount", "tags": [ "Identity", "ServiceAccount" ], "x-code-hash": "22ba496b8af8325e", "x-generated-at": "2026-04-11T01:54:47.890Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A descriptive name for the service account." }, "description": { "type": "string", "description": "Optional detailed information about the service account's purpose." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "An array of capability URIs defining the service account's permissions." }, "ip_allowlist": { "type": "array", "items": { "type": "string", "format": "ipv4" }, "description": "A list of IP addresses allowed to use this service account." }, "owner_passport_did": { "type": "string", "description": "The DID of the owner passport, starting with 'did:human:'." } }, "required": [ "name", "scopes" ] }, "examples": { "create_service_account_for_invoice_processing": { "summary": "Create Service Account for Invoice Processing", "description": "This example demonstrates setting up a service account for 'acme' organization to automate invoice processing.", "value": { "name": "Invoice Processor", "description": "Handles automated invoice processing tasks.", "scopes": [ "capability://finance:invoices:read", "capability://finance:invoices:write" ], "ip_allowlist": [ "192.168.1.10" ], "owner_passport_did": "did:human:org:acme" } } } } } }, "responses": { "201": { "description": "Successfully created service account with an API key and metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "service_account_id": { "type": "string", "description": "The unique identifier for the service account." }, "api_key": { "type": "string", "description": "The secret API key for accessing the service account." }, "name": { "type": "string", "description": "The name of the service account." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes associated with the service account." }, "ip_allowlist": { "type": "array", "items": { "type": "string", "format": "ipv4" }, "description": "List of allowed IP addresses." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the service account was created." } } }, "examples": { "successful_creation": { "summary": "Successful Creation", "description": "A successful response after creating a service account for 'acme'.", "value": { "service_account_id": "hsa12345", "api_key": "HSK_live_4bGZ2k...", "name": "Invoice Processor", "scopes": [ "capability://finance:invoices:read", "capability://finance:invoices:write" ], "ip_allowlist": [ "192.168.1.10" ], "created_at": "2023-10-01T08:00:00Z" } } } } } }, "400": { "description": "The request was malformed. Check the JSON structure and required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_name": { "summary": "Missing Name", "description": "Occurs when 'name' is not provided.", "value": { "type": "https://humanprotocol.org/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "name is required", "errors": [ { "field": "name", "code": "REQUIRED_FIELD_MISSING", "message": "name is required", "expected": "non-empty string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_authentication": { "summary": "No Authentication", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://humanprotocol.org/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required" } } } } } }, "403": { "description": "The authenticated user is not authorized to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_did_assignment": { "summary": "Unauthorized DID Assignment", "description": "Occurs when non-global admin attempts to set owner_passport_did for another passport.", "value": { "type": "https://humanprotocol.org/probs/authorization-error", "title": "Authorization Error", "status": 403, "detail": "Setting owner_passport_did for another passport requires cloud:admin:global" } } } } } }, "404": { "description": "The owner passport DID provided was not found or is inactive.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "Occurs when the specified owner_passport_did does not exist or is inactive.", "value": { "type": "https://humanprotocol.org/probs/passport-not-found", "title": "Passport Not Found", "status": 404, "detail": "Passport not found or inactive" } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A generic error when something goes wrong on the server.", "value": { "type": "https://humanprotocol.org/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/apps/register": { "post": { "summary": "Register a new application with a Passport", "description": "Embark on a journey to integrate your application into the HUMAN ecosystem by registering it with a unique Passport. This endpoint establishes your application's identity, enabling it to interact securely and efficiently through HUMAN's protocol.", "operationId": "registerApplication", "tags": [ "Passport", "Application" ], "x-code-hash": "886c067ba6240ba3", "x-generated-at": "2026-04-11T01:55:00.191Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app_name": { "type": "string", "description": "The name of your application" }, "app_type": { "type": "string", "enum": [ "web", "native", "spa" ], "description": "The type of application, guiding security strategies" }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri", "description": "Registered URIs for redirect after authentication" } }, "scopes": { "type": "array", "items": { "type": "string", "description": "Scopes defining the application's access permissions" } } }, "required": [ "app_name", "app_type", "redirect_uris", "scopes" ] }, "examples": { "register_a_web_application": { "summary": "Register a Web Application", "description": "This example registers a web application named 'Invoicer' for managing company invoices.", "value": { "app_name": "Invoicer", "app_type": "web", "redirect_uris": [ "https://acme.com/callback", "http://localhost:3000/callback" ], "scopes": [ "invoices.read", "invoices.write" ] } } } } } }, "responses": { "201": { "description": "Application successfully registered, returning its credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "description": "Unique client identifier for the application" }, "client_secret": { "type": "string", "description": "Secret used for authenticating the application (only for web apps)" }, "app_name": { "type": "string", "description": "Registered application name" }, "app_type": { "type": "string", "description": "Registered application type" }, "redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "Registered redirect URIs" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Granted scopes for the application" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the application was registered" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Authentication is required to register an application", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/passport/authorize": { "get": { "summary": "Authorize client with OAuth protocol", "description": "Initiate an OAuth authorization flow for a client application using the HUMAN Passport. This endpoint ensures that only verified applications can request access, protecting users and maintaining system integrity.", "operationId": "authorizeClient", "tags": [ "Authentication", "OAuth" ], "x-code-hash": "794463e319c6c603", "x-generated-at": "2026-04-11T01:55:08.792Z", "responses": { "302": { "description": "Redirect to the consent page for user authorization", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_uri": { "type": "string", "description": "The URI to redirect the user for consent" } }, "required": [ "redirect_uri" ] }, "examples": { "default": { "summary": "Example", "value": { "redirect_uri": "https://consent.humanprotocol.org/authorize?request_id=abc123&client_id=acme&scope=openid%20profile" } } } } } }, "400": { "description": "Bad request due to invalid parameters or unsupported features", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/invalid_request", "title": "Invalid Request", "status": 400, "detail": "client_id, redirect_uri, state, code_challenge, and code_challenge_method=S256 are required" } } } } } }, "401": { "description": "Unauthorized due to invalid client credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/invalid_client", "title": "Invalid Client", "status": 401, "detail": "Unknown client_id" } } } } } }, "403": { "description": "Forbidden due to invalid redirect URI or scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "redirect_uri is not registered for this client" } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/internal_error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/oauth/consent": { "post": { "summary": "Authorize and Consent OAuth Requests", "description": "Facilitates user consent for OAuth authorization by securely handling the exchange of authorization codes. This endpoint ensures that users' cryptographic identities and delegated capabilities are respected, maintaining a seamless and secure user experience.", "operationId": "postOauthConsent", "tags": [ "OAuth", "Passport" ], "x-code-hash": "450127d8fa530f9f", "x-generated-at": "2026-04-11T01:55:24.257Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "A unique identifier for the OAuth authorization request." } }, "required": [ "request_id" ] }, "examples": { "valid_oauth_consent_request": { "summary": "Valid OAuth Consent Request", "description": "A typical request for authorizing an OAuth process.", "value": { "request_id": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "responses": { "200": { "description": "Successfully processed the OAuth consent request, redirecting with authorization code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_to": { "type": "string", "description": "The URL to which the user should be redirected, including the authorization code and state." }, "granted_scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes that were successfully granted to the client." } } }, "examples": { "successful_consent_response": { "summary": "Successful Consent Response", "description": "Redirect URL with the granted authorization code.", "value": { "redirect_to": "https://client.example.com/callback?code=oac_abc123&state=xyz789", "granted_scopes": [ "read", "write" ] } } } } } }, "400": { "description": "The request was invalid due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication is required and was not provided or was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "The user's token does not include any requested scopes, hence insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The authorization request was not found, possibly due to expiration or invalid ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/passport/token": { "post": { "summary": "Exchange authorization code for access token", "description": "Unlock the potential of your applications by exchanging an authorization code for an access token. This endpoint safeguards the integrity of your interactions by ensuring strict adherence to OAuth standards, empowering developers to harness secure and seamless user authentication.", "operationId": "exchangeAuthorizationCode", "tags": [ "Authentication", "OAuth" ], "x-code-hash": "ceacc16e34765407", "x-generated-at": "2026-04-11T01:55:35.013Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code" ], "description": "The type of grant being used. Must be 'authorization_code'." }, "code": { "type": "string", "description": "The authorization code received from the authorization server." }, "redirect_uri": { "type": "string", "format": "uri", "description": "The redirect URI used in the authorization request." }, "client_id": { "type": "string", "description": "The client identifier issued to the client during the registration process." }, "client_secret": { "type": "string", "description": "The client secret issued to the client during the registration process." }, "code_verifier": { "type": "string", "minLength": 43, "description": "The code verifier for PKCE validation." } }, "required": [ "grant_type", "code", "redirect_uri", "client_id", "code_verifier" ] }, "examples": { "standard_oauth_token_exchange": { "summary": "Standard OAuth Token Exchange", "description": "Demonstrates a typical request to exchange an authorization code for an access token.", "value": { "grant_type": "authorization_code", "code": "abc123xyz", "redirect_uri": "https://example.com/callback", "client_id": "acme-client-id", "client_secret": "acme-client-secret", "code_verifier": "verifier1234567890abcdefghijklmnopqrstuvwxyzABCDEF" } } } } } }, "responses": { "200": { "description": "Access token successfully issued in response to valid authorization code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The access token issued by the authorization server." }, "token_type": { "type": "string", "enum": [ "Bearer" ], "description": "The type of token issued." }, "expires_in": { "type": "integer", "description": "The lifetime in seconds of the access token." }, "scope": { "type": "string", "description": "The scope of access granted in the token." } } }, "examples": { "default": { "summary": "Example", "value": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "scope": "read:invoices write:invoices" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "code, redirect_uri, client_id, and code_verifier (min 43 chars) are required." } } } } } }, "401": { "description": "Unauthorized due to an invalid client secret.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-client", "title": "Invalid Client", "status": 401, "detail": "Invalid or missing client_secret for confidential client." } } } } } }, "403": { "description": "Forbidden request due to mismatched redirect URI.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-grant", "title": "Invalid Grant", "status": 403, "detail": "redirect_uri does not match the authorization request." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/credentials/verify": { "post": { "summary": "Verify the authenticity of a Passport credential", "description": "Dive into the heart of identity verification with this endpoint, where credentials are scrutinized to ensure trustworthiness. In a world where digital identities are pivotal, knowing the truth behind a credential is paramount. This service verifies the integrity and validity of a Passport credential, giving organizations the confidence they need in their digital interactions.", "operationId": "verifyPassportCredential", "tags": [ "Identity", "Verification" ], "x-code-hash": "a57aef224af07a96", "x-generated-at": "2026-04-11T01:55:46.988Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "credential_id": { "type": "string", "description": "The unique identifier for the credential" } }, "required": [ "credential_id" ] }, { "properties": { "credentialId": { "type": "string", "description": "The unique identifier for the credential (legacy format)" } }, "required": [ "credentialId" ] } ] }, "examples": { "verify_a_credential": { "summary": "Verify a credential", "description": "An example of verifying a credential using the modern field name", "value": { "credential_id": "cred-12345" } } } } } }, "responses": { "200": { "description": "Credential verification results", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Indicates if the credential is valid" }, "issuer_verified": { "type": "boolean", "description": "True if the credential's issuer is verified" }, "not_revoked": { "type": "boolean", "description": "True if the credential has not been revoked" }, "not_expired": { "type": "boolean", "description": "True if the credential has not expired" }, "ledger_anchored": { "type": "boolean", "description": "True if the credential is recorded on the ledger" }, "verification_timestamp": { "type": "string", "format": "date-time", "description": "The time when verification was performed" }, "trust_score": { "type": "integer", "description": "A score representing the trust level of the credential" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing required fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid_request", "title": "Invalid Request", "status": 400, "detail": "Request body must be JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/authentication_required", "title": "Authentication Required", "status": 401, "detail": "Authentication required" } } } } } }, "404": { "description": "The requested credential could not be found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not_found", "title": "Not Found", "status": 404, "detail": "Credential not found" } } } } } }, "500": { "description": "An internal server error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal_error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred" } } } } } } } } }, "/v1/passport/credentials/:credential_id/revoke": { "post": { "summary": "Revoke a specific passport credential", "description": "This endpoint allows the issuing passport to revoke a credential, reflecting changes in a user's capability graph. By revoking a credential, you ensure the integrity and accuracy of the distributed ledger, protecting the ecosystem from outdated or incorrect data.", "operationId": "revokePassportCredential", "tags": [ "Passport", "Credentials" ], "x-code-hash": "f2bdce00a39f7401", "x-generated-at": "2026-04-11T01:55:59.310Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "effective_date": { "type": "string", "format": "date-time", "description": "The ISO 8601 date-time when the revocation should take effect." } }, "oneOf": [ { "required": [ "effective_date" ] } ] }, "examples": { "revoke_credential_with_specific_date": { "summary": "Revoke Credential with Specific Date", "description": "Revoke a credential starting from January 1, 2024.", "value": { "effective_date": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "Credential successfully revoked, reflecting in the distributed ledger.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential_id": { "type": "string", "description": "The unique identifier of the revoked credential." }, "status": { "type": "string", "enum": [ "revoked" ], "description": "The current status of the credential." }, "revoked_at": { "type": "string", "format": "date-time", "description": "The date-time when the credential was revoked." }, "ledger_anchor": { "type": [ "object", "null" ], "properties": { "transaction_id": { "type": "string", "description": "The transaction ID from the distributed ledger." }, "block_number": { "type": "integer", "description": "The block number in the ledger where the transaction is recorded." }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp of the ledger entry." } }, "description": "The ledger anchor details if available." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad request due to invalid data format or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-params", "title": "Invalid Data Format", "status": 400, "detail": "The effective_date must be a valid ISO 8601 date-time string.", "errors": [ { "field": "effective_date", "code": "INVALID_VALUE", "message": "effective_date must be ISO 8601", "expected": "date-time string", "received": "not-a-date" } ] } } } } } }, "401": { "description": "Authentication required to revoke credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to revoke a credential. Ensure your request includes valid authentication credentials." } } } } } }, "403": { "description": "Authorization error when the passport is not the issuer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authorization-error", "title": "Forbidden", "status": 403, "detail": "Only the issuing passport may revoke this credential. Verify your permissions and try again." } } } } } }, "404": { "description": "Credential not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Credential Not Found", "status": 404, "detail": "The credential with ID 1234-abcd could not be found. Check the ID and try again." } } } } } }, "500": { "description": "Internal server error during credential revocation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passport/credentials": { "get": { "summary": "Retrieve Verified Credentials for Passport", "description": "Delve into the rich tapestry of your digital identity by retrieving your verified credentials. This endpoint empowers you to securely access and manage the credentials tied to your Passport, ensuring that only you hold the key to your identity's narrative.", "operationId": "getPassportCredentials", "tags": [ "Identity", "Credentials" ], "x-code-hash": "5ad13eb360f090f4", "x-generated-at": "2026-04-11T01:56:14.407Z", "responses": { "200": { "description": "A successful retrieval of verified credentials associated with the requesting user's Passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the credential." }, "type": { "type": "string", "description": "The type/category of the credential." }, "issued_at": { "type": "string", "format": "date-time", "description": "When the credential was issued." }, "issuer": { "type": "string", "description": "The DID of the issuer." }, "subject": { "type": "string", "description": "The DID of the subject the credential pertains to." } }, "required": [ "id", "type", "issued_at", "issuer", "subject" ] } }, "cursor": { "type": "string", "description": "Opaque cursor for pagination." }, "hasMore": { "type": "boolean", "description": "Indicates if more credentials are available." }, "total": { "type": "integer", "description": "The total count of credentials, if requested." } }, "required": [ "credentials", "hasMore" ] }, "examples": { "successful_retrieval_example": { "summary": "Successful Retrieval Example", "description": "Shows a successful retrieval of credentials for a user's Passport.", "value": { "credentials": [ { "id": "cred-1234", "type": "capability://humanos/employment", "issued_at": "2023-10-01T15:23:01Z", "issuer": "did:human:issuer123", "subject": "did:human:acme-agent" } ], "cursor": "opaque-cursor-string", "hasMore": false, "total": 1 } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "Shows an invalid cursor error due to malformed pagination cursor.", "value": { "type": "https://api.human/probs/invalid-parameters", "title": "Invalid request parameters.", "status": 400, "detail": "Invalid pagination cursor provided.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor (issued_at + id)", "received": "faulty-cursor" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "Shows an error when no authentication is provided.", "value": { "type": "https://api.human/probs/auth-required", "title": "Authentication required", "status": 401, "detail": "You must be authenticated to access this endpoint." } } } } } }, "403": { "description": "Authorization error for accessing other DIDs' credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_did_access": { "summary": "Unauthorized DID Access", "description": "Shows an error when trying to access credentials of another DID.", "value": { "type": "https://api.human/probs/forbidden", "title": "Listing credentials for another DID is not allowed", "status": 403, "detail": "You are not authorized to list credentials for another DID in this release." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error_example": { "summary": "Unexpected Error Example", "description": "Shows a generic error when the server encounters an unexpected condition.", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "summary": "Create Verifiable Credential for Human Passport", "description": "This endpoint empowers organizations and agents to issue verifiable credentials tied to a human's digital identity. By securely managing these credentials, organizations can assert skills or qualifications that are cryptographically verifiable, enhancing trust in digital interactions.", "operationId": "createPassportCredential", "tags": [ "Passport", "Identity" ], "x-code-hash": "12aabf8014ecf8f9", "x-generated-at": "2026-04-11T01:56:52.008Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_did": { "type": "string", "description": "The DID of the human subject receiving the credential." }, "issuer_did": { "type": "string", "description": "The DID of the issuer, which must be an org or agent." }, "type": { "type": "array", "items": { "type": "string" }, "description": "The type(s) of credential being issued." }, "claims": { "type": "object", "description": "A JSON object representing claims associated with the credential." }, "expiration_date": { "type": "string", "format": "date-time", "description": "The optional expiration date for the credential in ISO 8601 format." } }, "required": [ "subject_did", "issuer_did", "type", "claims" ] }, "examples": { "issue_skill_credential": { "summary": "Issue Skill Credential", "description": "Demonstrates issuing a credential asserting a skill proficiency.", "value": { "subject_did": "did:human:123456789abcdefghi", "issuer_did": "did:org:acme", "type": [ "SkillCredential" ], "claims": { "skill": "Blockchain Development", "proficiency": "Expert" }, "expiration_date": "2025-12-31T23:59:59Z" } } } } } }, "responses": { "201": { "description": "Credential successfully issued and cryptographically signed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential_id": { "type": "string", "description": "The unique identifier for the issued credential." }, "type": { "type": "array", "items": { "type": "string" }, "description": "The type(s) of the issued credential." }, "issued_at": { "type": "string", "format": "date-time", "description": "The timestamp when the credential was issued." }, "proof": { "type": "object", "properties": { "type": { "type": "string", "description": "The proof type used for signing." }, "created": { "type": "string", "format": "date-time", "description": "The date and time when the proof was created." }, "verificationMethod": { "type": "string", "description": "The method used to verify the proof." }, "proofValue": { "type": "string", "description": "The cryptographic proof value." } } }, "ledger_anchor": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "The ID of the transaction anchoring this credential on the ledger." }, "block_number": { "type": "integer", "description": "The block number containing the transaction." }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp when the transaction was recorded on the ledger." } }, "nullable": true } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request data; see detail for errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Error", "status": 401, "detail": "Authentication required" } } } } } }, "403": { "description": "Permission denied due to mismatched issuer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "issuer_did must match the authenticated passport (issuer)" } } } } } }, "404": { "description": "The specified human passport was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Passport did:human:123456789abcdefghi not found" } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred" } } } } } } } } }, "/v1/passport/credentials/client-signed": { "post": { "summary": "Create a Client-Signed Credential", "description": "This endpoint allows an authenticated issuer to create a client-signed credential within the HUMAN network. By leveraging cryptographic proofs, it ensures the integrity and authenticity of issued credentials, advancing trust in decentralized identity management.", "operationId": "createClientSignedCredential", "tags": [ "Credentials", "Passport" ], "x-code-hash": "9c7863ce1dda683f", "x-generated-at": "2026-04-11T01:56:31.875Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "subject_did": { "type": "string", "pattern": "^did:human:.*" }, "issuer_did": { "type": "string", "pattern": "^did:human:.*" }, "type": { "type": "array", "items": { "type": "string" } }, "claims": { "type": "object" }, "issued_at": { "type": "string", "format": "date-time" }, "expiration_date": { "type": "string", "format": "date-time" }, "signature": { "type": "string" }, "signing_key_purpose": { "type": "string", "enum": [ "attest", "auth" ] } }, "required": [ "subject_did", "issuer_did", "claims", "issued_at", "signature" ] } ] }, "examples": { "standard_credential_issue": { "summary": "Standard Credential Issue", "description": "Example of issuing a credential for a subject with specific claims.", "value": { "subject_did": "did:human:example123", "issuer_did": "did:human:issuer456", "type": [ "VerifiableCredential", "ProofOfEmployment" ], "claims": { "employee_id": "E12345", "position": "Software Engineer", "organization": "acme" }, "issued_at": "2023-10-01T12:00:00Z", "expiration_date": "2024-10-01T12:00:00Z", "signature": "base64encodedsignature==", "signing_key_purpose": "attest" } } } } } }, "responses": { "201": { "description": "Credential successfully created with a unique identifier.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential_id": { "type": "string" }, "type": { "type": "array", "items": { "type": "string" } }, "issued_at": { "type": "string", "format": "date-time" }, "proof": { "type": "object", "properties": { "type": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "verificationMethod": { "type": "string" }, "proofValue": { "type": "string" } } }, "ledger_anchor": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "block_number": { "type": "number" }, "timestamp": { "type": "string", "format": "date-time" } }, "nullable": true } }, "required": [ "credential_id", "type", "issued_at", "proof" ] }, "examples": { "successful_credential_issuance": { "summary": "Successful Credential Issuance", "description": "A credential issued for a software engineer at Acme Corp.", "value": { "credential_id": "cred-abcdef123456", "type": [ "VerifiableCredential", "ProofOfEmployment" ], "issued_at": "2023-10-01T12:00:00Z", "proof": { "type": "Ed25519Signature2020", "created": "2023-10-01T12:00:00Z", "verificationMethod": "did:human:issuer456#keys-attest-1", "proofValue": "base64encodedsignature==" }, "ledger_anchor": { "transaction_id": "tx-1234567890", "block_number": 12345, "timestamp": "2023-10-01T12:01:00Z" } } } } } } }, "400": { "description": "Validation errors in the request payload.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_subject_did": { "summary": "Invalid Subject DID", "description": "The subject_did must start with 'did:human:'.", "value": { "type": "/errors/validation", "title": "Validation Error", "status": 400, "detail": "Invalid request body.", "errors": [ { "field": "subject_did", "code": "REQUIRED_FIELD_MISSING", "message": "subject_did must be a human DID (did:human:...)", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication failures due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request is missing authentication headers.", "value": { "type": "/errors/authentication", "title": "Authentication Error", "status": 401, "detail": "Authentication required." } } } } } }, "403": { "description": "Authorization errors when the issuer is not permitted to submit the credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_issuer": { "summary": "Unauthorized Issuer", "description": "The issuer_did does not match the authenticated user.", "value": { "type": "/errors/authorization", "title": "Authorization Error", "status": 403, "detail": "Only the issuing human may submit a client-signed credential." } } } } } }, "404": { "description": "The specified passport was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "The subject_did does not correspond to an active passport.", "value": { "type": "/errors/not_found", "title": "Resource Not Found", "status": 404, "detail": "Passport not found." } } } } } }, "500": { "description": "Unexpected server error during credential creation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An error occurred on the server while processing the request.", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/identities/:did/devices/authorization-options": { "post": { "summary": "Authorize a device for identity verification", "description": "In the HUMAN protocol, safeguarding your cryptographic identity is crucial. This endpoint allows users to initiate device authorization for a DID, setting the stage for secure WebAuthn interactions. By leveraging this, users can ensure their identity is protected and verified through trusted devices.", "operationId": "authorizeDeviceForIdentityVerification", "tags": [ "Identity Management", "Security" ], "x-code-hash": "0d6a6fe6eaf94984", "x-generated-at": "2026-04-11T01:57:04.611Z", "responses": { "200": { "description": "Device authorization options successfully generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "Unique identifier for the authorization challenge" }, "options": { "type": "object", "description": "WebAuthn options required to complete device authorization" } }, "required": [ "challenge_id", "options" ] }, "examples": { "successfuldeviceauthorizationexample": { "summary": "SuccessfulDeviceAuthorizationExample", "description": "An example where the device authorization options are successfully generated for a valid DID.", "value": { "challenge_id": "c1234567890", "options": { "rpId": "acme.human", "userVerification": "required", "timeout": 60000 } } } } } } }, "400": { "description": "Validation error when required credentials are missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missingwebauthncredentialsexample": { "summary": "MissingWebAuthnCredentialsExample", "description": "No WebAuthn credentials registered, prompting the user to complete primary passkey enrollment.", "value": { "type": "https://example.com/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "No WebAuthn credentials are registered for this passport. Complete primary passkey enrollment first.", "errors": [ { "field": "passport", "code": "NO_WEBAUTHN_CREDENTIAL", "message": "No WebAuthn credentials are registered for this passport. Complete primary passkey enrollment first.", "expected": "primary or bound device credential", "received": "none" } ] } } } } } }, "401": { "description": "Unauthorized error when authentication is missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authenticationrequiredexample": { "summary": "AuthenticationRequiredExample", "description": "An example where the request is missing authentication credentials.", "value": { "type": "https://example.com/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden error when authorization is insufficient", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authorizationselfrequestexample": { "summary": "AuthorizationSelfRequestExample", "description": "An example of a request attempting to generate device proof for a DID that is not the requester's own.", "value": { "type": "https://example.com/problems/authorization-error", "title": "Authorization Error", "status": 403, "detail": "You may only request device proof for your own passport." } } } } } }, "404": { "description": "Not Found error when DID is invalid or not present", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "didnotfoundexample": { "summary": "DidNotFoundExample", "description": "An example where the provided DID does not start with 'did:human:' or does not exist.", "value": { "type": "https://example.com/problems/not-found", "title": "Resource Not Found", "status": 404, "detail": "The specified passport was not found. Please verify the DID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "genericinternalerrorexample": { "summary": "GenericInternalErrorExample", "description": "An example of a server error with a unique incident ID.", "value": { "type": "https://example.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please contact support with incident ID: inc_1697043561234." } } } } } } } } }, "/v1/passport/identities/:did/devices/register-options": { "post": { "summary": "Register device options for a passport", "description": "In the HUMAN ecosystem, binding devices to digital identities is crucial for secure interactions. This endpoint generates registration options, allowing a device to be securely linked to a human passport. It ensures that only the rightful owner of the passport can initiate this process, preserving the integrity of the system.", "operationId": "registerDeviceOptions", "tags": [ "Identity", "Device Management" ], "x-code-hash": "64dc325dea54d254", "x-generated-at": "2026-04-11T01:57:14.720Z", "responses": { "200": { "description": "Returns WebAuthn registration options for a human passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "registration_id": { "type": "string", "description": "Unique identifier for the device registration session." }, "options": { "type": "object", "description": "WebAuthn registration options for the device." } }, "required": [ "registration_id", "options" ] }, "examples": { "successful_device_registration_options": { "summary": "Successful Device Registration Options", "description": "Alice from Acme Corp is registering a new device.", "value": { "registration_id": "reg-123456", "options": { "challenge": "random-challenge", "rp": { "name": "Acme Corp" }, "user": { "id": "alice-id", "name": "Alice" } } } } } } } }, "400": { "description": "Validation error when attempting to register a device for a non-human passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_person_type_error": { "summary": "Invalid Person Type Error", "description": "Attempting to register a device on a non-human passport.", "value": { "type": "https://humanprotocol.org/errors/invalid-person-type", "title": "Validation Error", "status": 400, "detail": "Device binding is only for human passports.", "errors": [ { "field": "person_type", "code": "INVALID_VALUE", "message": "Device binding is only for human passports", "expected": "Human", "received": "AI" } ] } } } } } }, "401": { "description": "Authentication error due to missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required_error": { "summary": "Authentication Required Error", "description": "User attempts to register a device without being authenticated.", "value": { "type": "https://humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required to register devices." } } } } } }, "403": { "description": "Authorization error due to attempting to register on another's passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authorization_error": { "summary": "Authorization Error", "description": "User tries to register a device on a passport they do not own.", "value": { "type": "https://humanprotocol.org/errors/authorization-error", "title": "Authorization Error", "status": 403, "detail": "You may only register devices on your own passport." } } } } } }, "404": { "description": "Passport not found error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found_error": { "summary": "Passport Not Found Error", "description": "User attempts to register a device for a non-existent passport.", "value": { "type": "https://humanprotocol.org/errors/passport-not-found", "title": "Passport Not Found", "status": 404, "detail": "No active passport found with DID: did:human:123456." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Unexpected error occurred during registration options generation.", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/identities/:did/devices": { "post": { "summary": "Add a new device to a passport identity", "description": "Empower your digital identity by securely adding a new device to your HUMAN Passport. This endpoint ensures that only authorized devices can be associated, maintaining the integrity and security of your digital interactions.", "operationId": "addDeviceToPassportIdentity", "tags": [ "Passport", "Device Management" ], "x-code-hash": "128c2ddf2c256f11", "x-generated-at": "2026-04-11T01:57:26.752Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "credential": { "type": "object" } }, "required": [ "challenge_id", "credential" ] }, "new_device": { "type": "object", "properties": { "registration_id": { "type": "string" }, "credential": { "type": "object" } }, "required": [ "registration_id", "credential" ] }, "device_type": { "type": "string" } }, "required": [ "authorization", "new_device" ] }, "examples": { "add_new_device_example": { "summary": "Add New Device Example", "description": "Illustrates adding a new device with valid authorization and registration.", "value": { "authorization": { "challenge_id": "auth-challenge-123", "credential": { "id": "credential-id-001", "signature": "signature-data" } }, "new_device": { "registration_id": "reg-id-456", "credential": { "id": "credential-id-002", "publicKey": "public-key-data" } }, "device_type": "smartphone" } } } } } }, "responses": { "201": { "description": "The device was successfully added to the passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string" }, "added_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "device_id": "device-789", "added_at": "2023-10-01T12:34:56.789Z", "status": "active" } } } } } }, "400": { "description": "Invalid request format or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-request", "title": "Invalid JSON Body", "status": 400, "detail": "Request body must be JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication required to add a device.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required to add a device." } } } } } }, "403": { "description": "You lack permission to add a device to this passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/authorization-failed", "title": "Authorization Failed", "status": 403, "detail": "You may only add devices to your own passport." } } } } } }, "404": { "description": "The specified passport identity was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Passport Not Found", "status": 404, "detail": "The requested passport identity was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/identities/:did/devices/:device_id": { "delete": { "summary": "Revoke a Device from a Passport", "description": "In the complex dance of digital identity, sometimes a device needs to gracefully exit the stage. This endpoint allows you to revoke a device from a user's Passport, ensuring that access is controlled and secure. Whether it's a lost device or a change in access policy, this operation keeps your digital space safe.", "operationId": "revokeDeviceFromPassport", "tags": [ "Identity", "Security" ], "x-code-hash": "3de51ca4d6daab2c", "x-generated-at": "2026-04-12T15:44:16.405Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "authorization": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "credential": { "type": "object" } }, "required": [ "challenge_id", "credential" ] }, "revocation_reason": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "authorization" ] }, { "properties": { "authorization_proof": { "type": "object", "properties": { "challengeId": { "type": "string" }, "credential": { "type": "object" } }, "required": [ "challengeId", "credential" ] }, "revocationReason": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "authorization_proof" ] } ] }, "examples": { "basic_revocation_example": { "summary": "Basic Revocation Example", "description": "Revoking a device with a reason and request ID", "value": { "authorization": { "challenge_id": "123456", "credential": { "type": "public-key", "id": "webauthn-credential-id" } }, "revocation_reason": "Device lost", "request_id": "req-789" } } } } } }, "responses": { "200": { "description": "The device has been successfully revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string" }, "revoked_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "revocation_event_id": { "type": "string", "nullable": true } } }, "examples": { "default": { "summary": "Example", "value": { "device_id": "device-abc", "revoked_at": "2023-10-05T14:48:00.000Z", "status": "revoked", "revocation_event_id": "rev-event-123" } } } } } }, "400": { "description": "Bad Request due to missing authorization fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Revocation requires authorization { challenge_id, credential } from a different active passkey than the device being removed (kb/96). Call POST .../devices/authorization-options first.", "errors": [ { "field": "authorization", "code": "REQUIRED_FIELD_MISSING", "message": "Revocation requires authorization { challenge_id, credential } from a different active passkey than the device being removed (kb/96).", "expected": "{ challenge_id, credential }", "received": "missing" } ] } } } } } }, "401": { "description": "Authentication is required to perform this operation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required to revoke a device. Please provide valid credentials." } } } } } }, "403": { "description": "Authorization error when attempting to revoke a device on another's passport", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You may only revoke devices on your own passport." } } } } } }, "404": { "description": "Device or passport not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "The device or passport specified could not be found." } } } } } }, "500": { "description": "An internal server error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/passport/identities/:did": { "get": { "summary": "Retrieve a user’s cryptographic identity", "description": "Delve into the realm of digital authenticity by fetching a user’s cryptographic identity from the HUMAN ecosystem. This endpoint allows authenticated users to explore their unique digital footprint, encapsulating their identity and associated devices, ensuring a seamless blend of privacy and transparency.", "operationId": "getPassportIdentity", "tags": [ "Identity", "Passport" ], "x-code-hash": "5429985f0f2187d4", "x-generated-at": "2026-04-11T01:57:52.547Z", "responses": { "200": { "description": "Successfully retrieved the passport identity details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier associated with the passport." }, "display_name": { "type": "string", "description": "The display name of the passport holder." }, "person_type": { "type": "string", "description": "Category of the person (e.g., individual, organization)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the passport was created." }, "is_active": { "type": "boolean", "description": "Indicates if the passport is currently active." }, "credential_count": { "type": "integer", "description": "Number of active attestations linked to this identity." }, "devices": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "Type of device (e.g., webauthn)." }, "has_credential": { "type": "boolean", "description": "Indicates if the device has a credential." }, "device_id": { "type": "string", "description": "Unique identifier for the device." }, "device_type": { "type": "string", "description": "Type of the device." }, "added_at": { "type": "string", "format": "date-time", "description": "Timestamp when the device was added." }, "last_used": { "type": "string", "format": "date-time", "description": "Timestamp of last usage of the device.", "nullable": true } } } } } }, "examples": { "successful_passport_identity_retrieval": { "summary": "Successful Passport Identity Retrieval", "description": "Retrieving John's digital passport details, including active devices and credential counts.", "value": { "did": "did:human:123456789abcdef", "display_name": "John Doe", "person_type": "individual", "created_at": "2023-01-15T12:34:56Z", "is_active": true, "credential_count": 3, "devices": [ { "kind": "webauthn", "has_credential": true, "device_id": "device-001", "device_type": "smartphone", "added_at": "2023-02-20T14:22:10Z", "last_used": null } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication Error", "description": "Attempt to access passport identity without authentication.", "value": { "type": "/problems/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Authentication is necessary to access the passport identity. Please ensure you provide valid credentials." } } } } } }, "403": { "description": "Access to the requested passport identity is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authorization_error": { "summary": "Authorization Error", "description": "Attempt to access another user's passport identity.", "value": { "type": "/problems/authorization-error", "title": "Forbidden", "status": 403, "detail": "You are only allowed to access your own passport identity. Verify that the DID matches your authenticated identity." } } } } } }, "404": { "description": "The requested passport identity could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_identity_not_found": { "summary": "Passport Identity Not Found", "description": "Attempt to access a non-existent passport identity.", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The passport identity for did:human:abcdef123456789 could not be found. Ensure the DID is correct and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server error occurred while processing the request.", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error (inc_1697649071000) occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passport/identities": { "post": { "summary": "Create a New Cryptographic Identity", "description": "Embark on a journey to establish a cryptographic identity through our Passport system, enabling secure and verifiable interactions within the HUMAN platform. This endpoint orchestrates the identity creation process with idempotent guarantees ensuring consistent outcomes.", "operationId": "createPassportIdentity", "tags": [ "Identity Management", "Passport" ], "x-code-hash": "fbaea925c679840e", "x-generated-at": "2026-04-11T01:58:03.776Z", "responses": { "200": { "description": "Successfully created a new cryptographic identity with idempotent guarantees.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the created identity." }, "enrollmentData": { "type": "object", "additionalProperties": true, "description": "Enrollment data for the newly created identity." } }, "required": [ "id", "enrollmentData" ] }, "examples": { "successful_identity_creation": { "summary": "Successful Identity Creation", "description": "A successful response showing the newly created identity and its enrollment data.", "value": { "id": "identity-12345", "enrollmentData": { "webauthnData": { "challenge": "randomChallengeString", "rp": { "name": "HUMAN Platform" }, "user": { "id": "user-67890", "name": "agent.acme" }, "pubKeyCredParams": [ { "type": "public-key", "alg": -7 } ] } } } } } } } }, "400": { "description": "The request was malformed or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_idempotency-key": { "summary": "Missing Idempotency-Key", "description": "A request without the required Idempotency-Key header.", "value": { "type": "https://humanprotocol.org/errors/required-field-missing", "title": "Bad Request", "status": 400, "detail": "Idempotency-Key header is required (kb/96). Retries with the same key return the same enrollment envelope for 24h.", "errors": [ { "field": "Idempotency-Key", "code": "REQUIRED_FIELD_MISSING", "message": "Idempotency-Key header is required (kb/96). Retries with the same key return the same enrollment envelope for 24h.", "expected": "non-empty string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_access": { "summary": "Unauthenticated Access", "description": "An attempt to create an identity without proper authentication.", "value": { "type": "https://humanprotocol.org/errors/authentication-required", "title": "Unauthorized", "status": 401, "detail": "Authentication required. Please ensure your request includes valid authentication credentials." } } } } } }, "409": { "description": "The Idempotency-Key was reused with a different request body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "idempotency_key_conflict": { "summary": "Idempotency Key Conflict", "description": "The Idempotency-Key was reused with a different request body.", "value": { "type": "https://humanprotocol.org/errors/idempotency-conflict", "title": "Conflict", "status": 409, "detail": "Idempotency-Key was reused with a different request body. Use a new Idempotency-Key or send the same body as the first request." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A general server error occurred.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try your request again later." } } } } } } } } }, "/v1/passport/disclosures/request": { "post": { "summary": "Request Passport Disclosure", "description": "Initiate a request for specific identity disclosures tied to a human DID. This endpoint empowers applications to verify identity attributes while maintaining control over privacy and consent. It's a gateway to a world where digital trust is built on human identity, not just numbers.", "operationId": "requestPassportDisclosures", "tags": [ "Identity", "Verification" ], "x-code-hash": "a1fac39eedb2a493", "x-generated-at": "2026-04-11T01:58:15.474Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_did": { "type": "string", "description": "The DID of the human whose attributes are being requested. Must start with 'did:human:'." }, "requested_attributes": { "type": "array", "items": { "type": "string" }, "description": "Array of attribute names to disclose." }, "purpose": { "type": "string", "description": "The purpose of the disclosure request." }, "expires_in": { "type": "integer", "description": "The time in seconds until the request expires, between 60 and 604800 (7 days)." } }, "required": [ "subject_did", "requested_attributes" ] }, "examples": { "requesting_user_attributes": { "summary": "Requesting User Attributes", "description": "A request to obtain the email and phone number of a user for account verification purposes.", "value": { "subject_did": "did:human:123456789abcdefghi", "requested_attributes": [ "email", "phone" ], "purpose": "Account verification", "expires_in": 3600 } } } } } }, "responses": { "201": { "description": "The disclosure request was successfully created and is pending authorization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique identifier for the disclosure request." }, "status": { "type": "string", "enum": [ "pending" ], "description": "The current status of the request." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the request was created." }, "expires_at": { "type": "string", "format": "date-time", "description": "The timestamp when the request will expire." }, "authorization_url": { "type": "string", "format": "uri", "description": "URL for the subject to authorize the request." } } }, "examples": { "default": { "summary": "Example", "value": { "request_id": "pdr_abcdef123456", "status": "pending", "created_at": "2023-10-01T12:34:56Z", "expires_at": "2023-10-01T13:34:56Z", "authorization_url": "https://example.com/authorize/pdr_abcdef123456" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body contains invalid JSON or missing fields.", "errors": [ { "field": "subject_did", "code": "REQUIRED_FIELD_MISSING", "message": "subject_did must be a human DID", "expected": "did:human:...", "received": "undefined" }, { "field": "requested_attributes", "code": "REQUIRED_FIELD_MISSING", "message": "requested_attributes must be a non-empty array", "expected": "string[]", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required. Please provide valid delegation credentials." } } } } } }, "404": { "description": "The specified passport does not exist or is inactive.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Passport Not Found", "status": 404, "detail": "The passport with DID did:human:123456789abcdefghi was not found or is inactive." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/disclosures/:request_id/grant/options": { "post": { "summary": "Request WebAuthn Options for Disclosure", "description": "Unlock the potential of secure identity verification by requesting WebAuthn options for a pending disclosure. This endpoint ensures that only the valid subject of a disclosure request can initiate the WebAuthn process, thus preserving the integrity and security of the HUMAN protocol.", "operationId": "requestDisclosureGrantOptions", "tags": [ "Passport", "Security" ], "x-code-hash": "f8e4fdc13bd85382", "x-generated-at": "2026-04-11T01:58:27.658Z", "responses": { "200": { "description": "Returns WebAuthn challenge options for the disclosure request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "Unique identifier for the WebAuthn challenge." }, "options": { "type": "object", "description": "WebAuthn options necessary for the client to complete authentication." } }, "required": [ "challenge_id", "options" ] }, "examples": { "successful_webauthn_options_retrieval": { "summary": "Successful WebAuthn Options Retrieval", "description": "An example where a subject successfully retrieves WebAuthn options for a pending disclosure request.", "value": { "challenge_id": "5f8d04b3-8d3d-4c2a-8a9e-1234567890ab", "options": { "rpId": "human.example.com", "userVerification": "preferred" } } } } } } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_disclosure_request_state": { "summary": "Invalid Disclosure Request State", "description": "An example of a failed attempt where the disclosure request is not in a pending state.", "value": { "type": "https://human.example.com/errors/invalid-state", "title": "Invalid Request State", "status": 400, "detail": "Disclosure request is not pending.", "errors": [ { "field": "request_id", "code": "INVALID_STATE", "message": "Disclosure request is not pending", "expected": "pending", "received": "completed" } ] } } } } } }, "401": { "description": "The user is not authenticated.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "An example of a failed attempt due to missing authentication credentials.", "value": { "type": "https://human.example.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You need to provide valid authentication credentials." } } } } } }, "403": { "description": "The user is forbidden from making this request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authorization_error": { "summary": "Authorization Error", "description": "An example where the request is forbidden because the user is not the subject of the disclosure request.", "value": { "type": "https://human.example.com/errors/authorization-error", "title": "Authorization Error", "status": 403, "detail": "Only the subject may request grant WebAuthn options for this request." } } } } } }, "404": { "description": "The disclosure request was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "disclosure_request_not_found": { "summary": "Disclosure Request Not Found", "description": "An example where the specified disclosure request ID does not exist.", "value": { "type": "https://human.example.com/errors/not-found", "title": "Disclosure Request Not Found", "status": 404, "detail": "The disclosure request with the given ID was not found." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An example of a generic server error.", "value": { "type": "https://human.example.com/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/disclosures/:request_id/grant": { "post": { "summary": "Grant Passport Disclosure Request", "description": "Empower digital identities by granting disclosure requests through secure WebAuthn verification. This endpoint ensures that only authorized parties can disclose sensitive attributes, maintaining the integrity and trust within the HUMAN platform.", "operationId": "grantPassportDisclosureRequest", "tags": [ "Passport", "Security" ], "x-code-hash": "f7cfbfc8763c0aba", "x-generated-at": "2026-04-11T01:58:42.887Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webauthn": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "The unique challenge identifier for WebAuthn verification." }, "credential": { "type": "object", "description": "The user's credential data required to complete WebAuthn verification." } }, "required": [ "challenge_id", "credential" ] }, "granted_attributes": { "type": "array", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The name of the attribute being granted." }, "value": { "type": "string", "description": "The value of the attribute." }, "proof": { "type": "string", "description": "A proof of the attribute's validity, formatted as a sha256_commit." } }, "required": [ "attribute", "value", "proof" ] }, "description": "A list of attributes that the subject is granting." }, "denied_attributes": { "type": "array", "items": { "type": "string", "description": "Attributes that the subject is choosing to deny." }, "description": "A list of attributes that the subject is denying." } }, "required": [ "webauthn", "granted_attributes" ] }, "examples": { "grant_disclosure_example": { "summary": "Grant Disclosure Example", "description": "Demonstrates granting disclosure with valid WebAuthn and attributes.", "value": { "webauthn": { "challenge_id": "challenge123", "credential": { "id": "credentialId", "rawId": "rawCredentialId", "response": { "clientDataJSON": "clientData", "authenticatorData": "authenticatorData", "signature": "signature", "userHandle": "userHandle" }, "type": "public-key" } }, "granted_attributes": [ { "attribute": "email", "value": "user@example.com", "proof": "sha256_commit:abcd1234" }, { "attribute": "name", "value": "John Doe", "proof": "sha256_commit:efgh5678" } ], "denied_attributes": [ "phone" ] } } } } } }, "responses": { "200": { "description": "The disclosure request was successfully granted, returning the request ID, status, and a disclosure token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The unique identifier of the disclosure request." }, "status": { "type": "string", "description": "The status of the request, indicating it was granted." }, "granted_at": { "type": "string", "format": "date-time", "description": "The timestamp when the request was granted." }, "disclosure_token": { "type": "string", "description": "A token representing the granted disclosure, used for future verification." }, "expires_at": { "type": "string", "format": "date-time", "description": "The expiration date of the disclosure request." } } }, "examples": { "default": { "summary": "Example", "value": { "request_id": "request123", "status": "granted", "granted_at": "2023-10-05T14:48:00.000Z", "disclosure_token": "pdt_exampletoken", "expires_at": "2023-10-06T14:48:00.000Z" } } } } } }, "400": { "description": "Bad Request - The request body is invalid or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized - Authentication is required to perform this request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required" } } } } } }, "403": { "description": "Forbidden - The subject passport is not authorized to grant this request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Only the subject passport may grant this disclosure request" } } } } } }, "404": { "description": "Not Found - The specified disclosure request does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Disclosure request not found" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/consents": { "get": { "summary": "Retrieve Passport Consent Records", "description": "Dive into the chronicles of your digital identity by exploring the consents associated with your Passport. This endpoint empowers you to audit the permissions granted to various agents, ensuring transparency and control over your digital footprint.", "operationId": "getPassportConsents", "tags": [ "Passport", "Consents" ], "x-code-hash": "61cec761640e0ef9", "x-generated-at": "2026-04-11T01:58:55.741Z", "responses": { "200": { "description": "Successfully retrieved the list of consents associated with the Passport DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "consents": { "type": "array", "items": { "type": "object", "properties": { "consent_id": { "type": "string" }, "requester": { "type": "string" }, "attributes_shared": { "type": "array", "items": { "type": "string" } }, "purpose": { "type": "string", "nullable": true }, "granted_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "granted": { "type": "boolean" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "consent_id", "requester", "attributes_shared", "granted_at", "status", "granted" ] } }, "limit": { "type": "integer" }, "cursor": { "type": "string", "nullable": true }, "total": { "type": "integer", "nullable": true } }, "required": [ "consents" ] }, "examples": { "consents_for_acme_corp": { "summary": "Consents for Acme Corp", "value": { "consents": [ { "consent_id": "c1f3eeb4-12af-4e9d-a654-4f0a7b4c3c8d", "requester": "did:example:123", "attributes_shared": [ "email", "phone" ], "purpose": "account_verification", "granted_at": "2023-10-01T10:00:00Z", "expires_at": null, "status": "active", "granted": true, "revoked_at": null } ], "limit": 10, "cursor": "eyJncmFudGVkX2F0IjogIjIwMjMtMTAtMDFUMTA6MDA6MDBaIiwgImNvbnNlbnRfaWQiOiAiYzFmM2VlYjQtMTJhZi00ZTlkLWE2NTQtNGYwYTdiNGMzYzhkIn0=", "total": 1 } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "value": { "type": "https://humanprotocol.org/errors/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor. Expected opaque cursor (granted_at + consent_id)." } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_example": { "summary": "Unauthenticated Example", "value": { "type": "https://humanprotocol.org/errors/unauthenticated", "title": "Authentication Required", "status": 401, "detail": "You must authenticate to access the consents." } } } } } }, "403": { "description": "Attempting to access consents of another DID is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized Access", "status": 403, "detail": "Listing consents for another DID is not allowed." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not Found Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/consents/:consent_id/revoke": { "post": { "summary": "Revoke a Passport Consent", "description": "When trust is no longer warranted, revoke a consent tied to a Passport. This endpoint ensures control over shared data and maintains user sovereignty.", "operationId": "revokePassportConsent", "tags": [ "Identity", "Consent Management" ], "x-code-hash": "22ede27ce014859c", "x-generated-at": "2026-04-11T01:59:08.267Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "revocation_reason": { "type": "string", "description": "The reason for revocation." } }, "required": [ "revocation_reason" ] }, { "properties": { "revocationReason": { "type": "string", "description": "The reason for revocation." } }, "required": [ "revocationReason" ] } ] }, "examples": { "revoke_consent_due_to_data_policy_change": { "summary": "Revoke consent due to data policy change", "description": "Shows how to revoke consent when data policy updates require it.", "value": { "revocation_reason": "Data policy changes require consent review." } } } } } }, "responses": { "200": { "description": "Consent successfully revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_id": { "type": "string", "description": "The ID of the revoked consent." }, "status": { "type": "string", "enum": [ "revoked" ], "description": "The status of the consent after revocation." }, "revoked_at": { "type": "string", "format": "date-time", "description": "The timestamp when the consent was revoked." } } }, "examples": { "default": { "summary": "Example", "value": { "consent_id": "consent-12345", "status": "revoked", "revoked_at": "2023-10-21T14:48:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body is malformed. Please ensure all required fields are present and formatted correctly.", "errors": [ "Missing revocation reason." ] } } } } } }, "401": { "description": "Authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to perform this action. Please log in and try again." } } } } } }, "403": { "description": "Unauthorized revocation attempt.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized-action", "title": "Unauthorized Action", "status": 403, "detail": "You do not have permission to revoke this consent. Only the subject passport can perform this action." } } } } } }, "404": { "description": "Consent not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Consent Not Found", "status": 404, "detail": "The specified consent ID does not exist. Please verify the ID and try again." } } } } } }, "500": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. If the problem persists, contact support with incident ID: inc_1678987654321." } } } } } } } } }, "/v1/passport/webhooks": { "post": { "summary": "Register a webhook for passport events", "description": "In a world where human and AI collaboration is key, webhooks allow organizations to seamlessly integrate and respond to passport events in real-time. This endpoint empowers you to subscribe to specific events, ensuring your systems are always in sync with the latest happenings.", "operationId": "registerPassportWebhook", "tags": [ "Webhooks", "Passport" ], "x-code-hash": "261a7c716c028e08", "x-generated-at": "2026-04-11T01:59:27.296Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Target URL for the webhook (must use http or https)." }, "secret": { "type": "string", "description": "Secret for HMAC signing of webhook payloads (min 8 characters)." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Array of passport event names to subscribe to." } }, "required": [ "url", "secret", "events" ] }, "examples": { "acme_corporation_webhook_setup": { "summary": "Acme Corporation Webhook Setup", "description": "Setting up a webhook for Acme Corporation to listen to passport creation and update events.", "value": { "url": "https://webhooks.acme.com/passport", "secret": "topsecret123", "events": [ "passport.created", "passport.updated" ] } } } } } }, "responses": { "201": { "description": "Webhook successfully registered, returning the unique identifiers and configuration details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_id": { "type": "string", "description": "Unique identifier for the newly created webhook." }, "subscription_ids": { "type": "array", "items": { "type": "string" }, "description": "List of subscription IDs corresponding to each event registered." }, "url": { "type": "string", "description": "The URL where webhook notifications will be sent." }, "events": { "type": "array", "items": { "type": "string" }, "description": "List of events the webhook is subscribed to." }, "signing_secret_stored": { "type": "boolean", "description": "Indicates that the signing secret is securely stored." } } }, "examples": { "default": { "summary": "Example", "value": { "webhook_id": "webhook-1234", "subscription_ids": [ "sub-5678", "sub-9012" ], "url": "https://webhooks.acme.com/passport", "events": [ "passport.created", "passport.updated" ], "signing_secret_stored": true } } } } } }, "400": { "description": "The request body contains invalid JSON or fails validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/validation", "title": "Invalid Request", "status": 400, "detail": "Request contains invalid fields.", "errors": [ { "field": "url", "code": "INVALID_URL", "message": "url must be a valid URL", "expected": "string", "received": "ftp://example.com" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication", "title": "Authentication Required", "status": 401, "detail": "Authentication required to register a webhook." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "Unexpected error occurred while registering the webhook. Please try again later." } } } } } } } } }, "/v1/ontology/packages/:id/manifest": { "get": { "summary": "Retrieve Ontology Package Manifest", "description": "Delve into the intricate details of an ontology package with its complete manifest and cryptographic signature. This endpoint empowers users to explore the capabilities within a package while ensuring secure and authorized access through HUMAN's robust identity protocols.", "operationId": "getOntologyPackageManifest", "tags": [ "Ontology", "Packages" ], "x-code-hash": "1282781c77dab032", "x-generated-at": "2026-03-24T22:41:28.535Z", "responses": { "200": { "description": "The complete manifest of the requested ontology package along with its cryptographic signature.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" }, "license": { "type": "string" }, "status": { "type": "string" }, "publisher": { "type": "object", "properties": { "did": { "type": "string" }, "name": { "type": "string" } } }, "signature": { "type": "string" }, "manifest_json": { "type": "object" }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "version", "name", "license", "status", "publisher", "signature", "manifest_json", "published_at" ] }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "description": "Retrieve the manifest of the 'acme' organization's latest published ontology package.", "value": { "id": "acme-invoice-processing", "version": "1.2.3", "name": "Invoice Processing with AI", "license": "open", "status": "published", "publisher": { "did": "did:example:123456789abcdefghi", "name": "Acme Corp" }, "signature": "MEUCIQD1z...", "manifest_json": { "skills": [ "ocr", "data-extraction" ] }, "published_at": "2023-10-11T12:00:00Z" } } } } } }, "400": { "description": "Bad request due to invalid input parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_package_id": { "summary": "Invalid Package ID", "description": "The package ID was missing or invalid.", "value": { "type": "https://human-protocol.org/problem/invalid-request", "title": "Invalid Request Parameters", "status": 400, "detail": "Package id is required and must be non-empty.", "errors": [ { "field": "id", "code": "INVALID_VALUE", "message": "Package id is required", "expected": "non-empty ontology package id", "received": "" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "User attempted access without valid delegation.", "value": { "type": "https://human-protocol.org/problem/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required to access the ontology package manifest. Ensure your request includes valid delegation credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "User lacks the necessary permissions to view the manifest.", "value": { "type": "https://human-protocol.org/problem/forbidden", "title": "Forbidden", "status": 403, "detail": "Manifest access requires publisher identity, an active installation by this passport, or an open published package. Verify your permissions and try again." } } } } } }, "404": { "description": "The requested ontology package or version could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "package_not_found": { "summary": "Package Not Found", "description": "The specified package ID and version do not exist.", "value": { "type": "https://human-protocol.org/problem/not-found", "title": "Ontology Package Not Found", "status": 404, "detail": "The ontology package manifest for 'acme-invoice-processing@1.2.3' could not be found. Check the ID and version for accuracy." } } } } } }, "500": { "description": "Internal server error during the processing of the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A server error occurred, preventing the retrieval of the manifest.", "value": { "type": "https://human-protocol.org/problem/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the ontology package manifest. Please try again later or contact support with incident ID: inc_1697040000000." } } } } } } } } }, "/v1/ontology/packages/:id/install": { "post": { "summary": "Install an Ontology Package for Organization", "description": "This endpoint allows organizations to seamlessly install or update ontology packages within the HUMAN platform. By ensuring only published package versions are used, it maintains integrity and provides a record of installation activities, helping organizations stay on top of their capabilities.", "operationId": "installOntologyPackage", "tags": [ "Ontology", "Installation" ], "x-code-hash": "92382f3cf866e6df", "x-generated-at": "2026-03-24T22:42:31.126Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "description": "Unique identifier for the organization." }, "org_slug": { "type": "string", "description": "Slug name for the organization." }, "package_version": { "type": "string", "description": "The version of the ontology package to install, must be a semantic version." }, "payment_id": { "type": "string", "description": "Optional payment identifier if payment processing is involved." } }, "required": [ "org_id", "org_slug", "package_version" ] }, "examples": { "install_published_package_for_acme_corp": { "summary": "Install Published Package for ACME Corp", "description": "This example demonstrates installing version 1.2.3 of a package for ACME Corporation.", "value": { "org_id": "org-12345", "org_slug": "acme-corp", "package_version": "1.2.3", "payment_id": "pay-6789" } } } } } }, "responses": { "200": { "description": "Ontology package was successfully updated for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "installation_id": { "type": "string" }, "package_id": { "type": "string" }, "package_version": { "type": "string" }, "org_id": { "type": "string" }, "org_slug": { "type": "string" }, "status": { "type": "string" }, "installed_by": { "type": "string" }, "installed_at": { "type": "string" }, "updated": { "type": "boolean" } } }, "examples": { "successful_update": { "summary": "Successful Update", "value": { "installation_id": "ont_inst_001", "package_id": "pkg-123", "package_version": "1.2.3", "org_id": "org-12345", "org_slug": "acme-corp", "status": "active", "installed_by": "user-789", "installed_at": "2023-10-01T12:00:00Z", "updated": true } } } } } }, "400": { "description": "Validation error due to invalid or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_required_fields": { "summary": "Missing Required Fields", "value": { "type": "https://example.com/probs/validation-error", "title": "Invalid request body.", "status": 400, "detail": "Request body contains invalid data.", "errors": [ { "field": "org_id", "code": "REQUIRED_FIELD_MISSING", "message": "org_id is required", "expected": "non-empty string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication error due to missing delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication required.", "status": 401, "detail": "Delegation required to perform this action." } } } } } }, "403": { "description": "Authorization error due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://example.com/probs/authorization-error", "title": "Permission denied.", "status": 403, "detail": "Insufficient permissions to install ontology packages. Ensure your Passport includes the necessary scopes." } } } } } }, "404": { "description": "Not found error when the package version is not published.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "package_not_found": { "summary": "Package Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Resource not found.", "status": 404, "detail": "The requested ontology package version pkg-123@1.2.3 is not published." } } } } } }, "500": { "description": "Internal server error due to unexpected issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "installation_error": { "summary": "Installation Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error.", "status": 500, "detail": "An unexpected error occurred while installing the ontology package. Please try again later or contact support with incident ID inc_1696350047." } } } } } } } } }, "/v1/academy/courses/:courseId": { "get": { "summary": "Retrieve detailed course information", "description": "Unlock the potential of learning by fetching detailed information about a specific course within the HUMAN academy. This endpoint allows you to delve into the intricacies of a course, from its skill capabilities to its duration and difficulty, empowering learners and educators to make informed decisions.", "operationId": "getCourseDetails", "tags": [ "Academy", "Courses" ], "x-code-hash": "8ec51cfc2821a35e", "x-generated-at": "2026-03-24T23:15:53.389Z", "responses": { "200": { "description": "Successful retrieval of course details, including title, description, and more.", "content": { "application/json": { "schema": { "type": "object", "properties": { "course_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "capability_ids": { "type": "array", "items": { "type": "string" } }, "category": { "type": [ "string", "null" ] }, "duration_minutes": { "type": "integer" }, "difficulty": { "type": "string" }, "is_published": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "detailed_course_information": { "summary": "Detailed Course Information", "description": "Fetching the course details for 'AI Ethics 101'.", "value": { "course_id": "course_123", "title": "AI Ethics 101", "description": "An introductory course on ethical considerations in AI.", "capability_ids": [ "capability://ai-ethics", "capability://data-privacy" ], "category": "Ethics", "duration_minutes": 90, "difficulty": "Intermediate", "is_published": true, "created_at": "2023-01-15T13:45:30Z", "updated_at": "2023-02-10T09:35:45Z" } } } } } }, "400": { "description": "Invalid request due to malformed course ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_course_id": { "summary": "Malformed Course ID", "description": "The course ID provided is not in the correct format.", "value": { "type": "https://example.com/probs/invalid-course-id", "title": "Invalid Course ID", "status": 400, "detail": "The course ID 'course_!@#' is not valid. Ensure the ID is alphanumeric and retry." } } } } } }, "401": { "description": "Unauthorized access when authentication credentials are missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "No valid authentication credentials provided.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Please provide valid authentication credentials to access this resource." } } } } } }, "403": { "description": "Forbidden access when the user does not have permission to view the course.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have permission to view this course.", "value": { "type": "https://example.com/probs/insufficient-permissions", "title": "Access Denied", "status": 403, "detail": "You do not have the necessary permissions to access course 'course_123'. Contact your administrator for access." } } } } } }, "404": { "description": "Course not found when a non-existent course ID is provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "course_not_found": { "summary": "Course Not Found", "description": "The specified course ID does not exist in the system.", "value": { "type": "https://example.com/probs/course-not-found", "title": "Course Not Found", "status": 404, "detail": "Course 'course_999' could not be found. Verify the course ID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/academy/enrollments": { "get": { "summary": "Retrieve learner enrollments with filters", "description": "Dive into the world of learning by exploring enrollments filtered by status or learner. This endpoint empowers organizations to seamlessly track and manage educational journeys, ensuring learners are on the right path to success.", "operationId": "getAcademyEnrollments", "tags": [ "Academy", "Enrollments" ], "x-code-hash": "3e11be21eba1c74c", "x-generated-at": "2026-03-24T23:16:26.100Z", "responses": { "200": { "description": "Successfully retrieved enrollments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "enrollment_id": { "type": "string" }, "did": { "type": "string" }, "learner_id": { "type": "string" }, "course_id": { "type": "string" }, "course_title": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "enrolled_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "score": { "type": [ "number", "null" ] } }, "required": [ "enrollment_id", "did", "learner_id", "course_id", "status", "progress", "enrolled_at" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "summary": "Example", "value": { "data": [ { "enrollment_id": "e12345", "did": "did:human:acme123", "learner_id": "acme123", "course_id": "c67890", "course_title": "Introduction to AI", "status": "enrolled", "progress": 45, "enrolled_at": "2023-10-01T12:00:00Z", "completed_at": null, "score": null } ], "limit": 10, "cursorField": "enrolled_at", "hasMore": false } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid query parameter", "status": 400, "detail": "The 'status' query parameter must be one of 'active', 'enrolled', or 'completed'.", "errors": [ { "field": "status", "code": "INVALID_ENUM", "message": "status must be active, enrolled, or completed", "expected": "active|enrolled|completed", "received": "in_progress" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "Access token is missing or invalid." } } } } } }, "403": { "description": "Forbidden access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these enrollments." } } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } }, "post": { "summary": "Enroll Learner in Academy Course", "description": "Embark on a journey of knowledge with the HUMAN platform's Academy. This endpoint allows learners to enroll in courses, leveraging their digital identity. Whether you're a seasoned professional or a curious novice, track your progress and elevate your skills seamlessly.", "operationId": "enrollLearnerInCourse", "tags": [ "Academy", "Enrollment" ], "x-code-hash": "534ee3ae4067912e", "x-generated-at": "2026-03-24T23:16:43.073Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier for the learner." }, "learner_id": { "type": "string", "description": "Unique identifier of the learner." }, "passport_id": { "type": "string", "description": "Passport ID representing the learner's identity." }, "course_id": { "type": "string", "description": "The course identifier in which the learner wishes to enroll." } }, "required": [ "course_id" ] }, "examples": { "enroll_with_did": { "summary": "Enroll with DID", "description": "A learner enrolls using their Decentralized Identifier.", "value": { "did": "did:human:12345", "course_id": "course-101" } } } } } }, "responses": { "201": { "description": "The learner has been successfully enrolled in the course.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollment_id": { "type": "string", "description": "Unique identifier for the enrollment record." }, "did": { "type": "string", "description": "Decentralized Identifier of the enrolled learner." }, "course_id": { "type": "string", "description": "Identifier of the course." }, "status": { "type": "string", "description": "Enrollment status, typically 'enrolled'." }, "enrolled_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the enrollment occurred." }, "progress": { "type": "integer", "description": "Initial progress of the learner, set to 0." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.platform/errors/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "404": { "description": "The specified course could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.platform/errors/not-found", "title": "Course Not Found", "status": 404, "detail": "Course course-101 not found" } } } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.platform/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred, please try again later." } } } } } } } } }, "/v1/academy/enrollments/:id/complete": { "patch": { "summary": "Complete an Enrollment and Anchor to Ledger", "description": "This endpoint finalizes a learner's enrollment by marking it as complete and issuing a cryptographic certification on the Distributed Ledger. This ensures an immutable proof of completion, paving the way for capability grants and further learning opportunities.", "operationId": "completeEnrollment", "tags": [ "Academy", "Enrollment" ], "x-code-hash": "a2fd01e206be568c", "x-generated-at": "2026-04-27T16:25:12.287Z", "responses": { "200": { "description": "The enrollment was successfully completed, and the ledger was updated with a cryptographic proof.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollment_id": { "type": "string", "description": "The unique identifier of the completed enrollment." }, "status": { "type": "string", "enum": [ "completed" ], "description": "The current status of the enrollment." }, "completed_at": { "type": "string", "format": "date-time", "description": "The timestamp when the enrollment was marked as completed." } } }, "examples": { "successful_completion_example": { "summary": "Successful Completion Example", "description": "Marks the enrollment as complete and returns the completion details.", "value": { "enrollment_id": "123e4567-e89b-12d3-a456-426614174000", "status": "completed", "completed_at": "2023-10-12T08:45:00Z" } } } } } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_enrollment_id_format": { "summary": "Invalid Enrollment ID Format", "description": "Occurs when the provided enrollment ID does not match the expected format.", "value": { "type": "https://api.human.com/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The enrollment ID format is invalid." } } } } } }, "401": { "description": "Unauthorized access to the resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "Occurs when authentication headers are absent.", "value": { "type": "https://api.human.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_enrollment_completion": { "summary": "Unauthorized Enrollment Completion", "description": "Occurs when the user lacks the necessary permissions to complete the enrollment.", "value": { "type": "https://api.human.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to complete this enrollment." } } } } } }, "404": { "description": "The specified enrollment was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "enrollment_not_found": { "summary": "Enrollment Not Found", "description": "Occurs when the enrollment ID does not match any records in the database.", "value": { "type": "https://api.human.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The enrollment with ID '123e4567-e89b-12d3-a456-426614174000' was not found." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "Occurs when an unexpected error is encountered on the server.", "value": { "type": "https://api.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/academy/progress": { "post": { "summary": "Update Learner's Academic Progress", "description": "Track learners' journey through your educational content with precision. This endpoint empowers educators by recording progress metrics, enabling tailored learning paths and ensuring every student reaches their full potential.", "operationId": "postAcademyProgress", "tags": [ "Education", "ProgressTracking" ], "x-code-hash": "29ba2daa085b6b9a", "x-generated-at": "2026-03-24T23:17:03.175Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollment_id": { "type": "string", "description": "Unique identifier for the learner's enrollment." }, "overall_progress": { "type": "integer", "description": "Progress percentage, must be an integer between 0 and 100." }, "lesson_id": { "type": "string", "description": "Identifier of the last lesson accessed by the learner." }, "completed": { "type": "boolean", "description": "Indicates if the last lesson was completed." }, "time_spent_seconds": { "type": "integer", "description": "Time spent on the last lesson in seconds." }, "interactions": { "type": "object", "description": "Additional data regarding learner interactions during the lesson." } }, "required": [ "enrollment_id", "overall_progress" ] }, "examples": { "typical_progress_update": { "summary": "Typical Progress Update", "description": "This example illustrates a progress update for a learner who completed the lesson with some interaction data.", "value": { "enrollment_id": "enroll_12345", "overall_progress": 75, "lesson_id": "lesson_6789", "completed": true, "time_spent_seconds": 3600, "interactions": { "questions_answered": 5, "notes_taken": 3 } } } } } } }, "responses": { "201": { "description": "Progress successfully updated, returning the recorded progress details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "progress_id": { "type": "string", "description": "Unique identifier for the recorded progress entry." }, "enrollment_id": { "type": "string", "description": "Reflects the enrollment ID from the request." }, "lesson_id": { "type": "string", "description": "Reflects the lesson ID from the request." }, "completed": { "type": "boolean", "description": "Reflects the completion status from the request." }, "recorded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the progress was recorded." }, "overall_progress": { "type": "integer", "description": "Reflects the overall progress percentage from the request." }, "next_lesson": { "type": "string", "description": "Identifier of the next lesson, if applicable." } } }, "examples": { "default": { "summary": "Example", "value": { "progress_id": "prog_rec_98765", "enrollment_id": "enroll_12345", "lesson_id": "lesson_6789", "completed": true, "recorded_at": "2023-10-08T14:53:00Z", "overall_progress": 75, "next_lesson": null } } } } } }, "400": { "description": "Invalid request parameters due to malformed or missing data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "404": { "description": "The specified enrollment was not found, indicating a potential ID error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/enrollment-not-found", "title": "Enrollment Not Found", "status": 404, "detail": "Enrollment enroll_12345 not found" } } } } } }, "500": { "description": "An unexpected server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/academy/progress/:enrollmentId": { "get": { "summary": "Retrieve enrollment progress details", "description": "Unlock the journey of learning by delving into the progress of a specific enrollment. This endpoint provides a window into a learner's path within a course, offering insights into their current status, progress milestones, and activity history. It's a tool for educators to tailor support and for learners to reflect on their educational voyage.", "operationId": "getAcademyEnrollmentProgress", "tags": [ "Academy", "Progress Tracking" ], "x-code-hash": "02de136bf186f060", "x-generated-at": "2026-04-02T13:13:52.829Z", "responses": { "200": { "description": "A detailed report of the enrollment progress, including course metadata and activity timestamps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollment_id": { "type": "string", "description": "Unique identifier for the enrollment." }, "course_id": { "type": "string", "description": "ID of the enrolled course." }, "course_title": { "type": "string", "description": "Title of the course, if available." }, "overall_progress": { "type": "number", "description": "Current progress percentage of the enrollment." }, "modules": { "type": "array", "items": { "type": "object" }, "description": "Array of module progress details." }, "next_lesson": { "type": "string", "nullable": true, "description": "Identifier for the next lesson, if available." }, "total_time_spent_minutes": { "type": "number", "nullable": true, "description": "Total time spent in minutes on the course." }, "last_activity": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp of the last recorded activity." }, "on_track": { "type": "boolean", "description": "Whether the enrollment is on track based on current progress." }, "status": { "type": "string", "description": "Current status of the enrollment (e.g., enrolled, completed)." }, "enrolled_at": { "type": "string", "format": "date-time", "description": "Timestamp when the learner was enrolled." }, "completed_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the course was completed, if applicable." }, "progress_context": { "type": "object", "description": "Additional context about the progress, if available." } } }, "examples": { "progress_of_an_active_enrollment": { "summary": "Progress of an Active Enrollment", "description": "A learner enrolled in the 'Advanced Data Science' course showing significant progress.", "value": { "enrollment_id": "enroll123", "course_id": "course456", "course_title": "Advanced Data Science", "overall_progress": 75, "modules": [], "next_lesson": "lesson789", "total_time_spent_minutes": 1200, "last_activity": "2023-10-05T14:48:00Z", "on_track": true, "status": "enrolled", "enrolled_at": "2023-01-10T10:00:00Z", "completed_at": null, "progress_context": {} } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_enrollment_id": { "summary": "Malformed Enrollment ID", "description": "The request fails because the enrollment ID is improperly formatted.", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The enrollment ID provided is not valid. Ensure the ID format is correct and try again." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request fails due to missing authentication credentials.", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid. Please provide valid credentials and try again." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user is trying to access an enrollment without the necessary permissions.", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this enrollment. Contact your administrator for access." } } } } } }, "404": { "description": "Enrollment not found with the provided ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "enrollment_not_found": { "summary": "Enrollment Not Found", "description": "The request fails because the enrollment ID does not exist.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Enrollment enroll123 not found. Verify the enrollment ID and try again." } } } } } }, "500": { "description": "Internal server error due to unforeseen issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_issue": { "summary": "Unexpected Server Issue", "description": "An internal server error occurs unexpectedly.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/workforce/workers/:did/availability": { "get": { "summary": "Retrieve worker availability status", "description": "Discover the availability of a worker within the HUMAN network by querying their Passport DID. This endpoint empowers task coordinators to efficiently allocate human resources, ensuring balanced workloads and optimal performance across organizations.", "operationId": "getWorkerAvailability", "tags": [ "Workforce", "Availability" ], "x-code-hash": "d6016366201c1c0d", "x-generated-at": "2026-03-24T23:18:22.693Z", "responses": { "200": { "description": "The worker's availability details by organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The Passport DID of the worker." }, "status": { "type": "string", "description": "Overall availability status of the worker." }, "current_load": { "type": "object", "properties": { "active_tasks": { "type": "integer", "description": "Current number of active tasks." }, "max_concurrent_tasks": { "type": "integer", "description": "Maximum concurrent tasks the worker can handle." } } }, "by_org": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string", "description": "Organization identifier." }, "worker_id": { "type": "string", "description": "Unique identifier for the worker." }, "status": { "type": "string", "description": "Worker's status within the organization." }, "active_assignments": { "type": "integer", "description": "Number of active assignments." }, "max_concurrent": { "type": "integer", "description": "Maximum concurrent tasks allowed." }, "available_slots": { "type": "integer", "description": "Number of available slots for additional tasks." } } } }, "schedule": { "type": [ "object", "null" ], "description": "Future implementation for worker's schedule." }, "performance_metrics": { "type": [ "object", "null" ], "description": "Future implementation for performance metrics." } } }, "examples": { "worker_availability_example": { "summary": "Worker availability example", "description": "An example response showing a worker with available capacity.", "value": { "did": "did:human:abc123", "status": "available", "current_load": { "active_tasks": 3, "max_concurrent_tasks": 5 }, "by_org": [ { "org_id": "acme", "worker_id": "worker-001", "status": "active", "active_assignments": 3, "max_concurrent": 5, "available_slots": 2 } ], "schedule": null, "performance_metrics": null } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_did_example": { "summary": "Missing DID Example", "description": "Example response when the DID path parameter is missing.", "value": { "type": "https://example.com/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "Worker DID path parameter is required", "errors": [ { "field": "did", "code": "REQUIRED_FIELD_MISSING", "message": "Worker DID path parameter is required", "expected": "non-empty string (Passport DID)", "received": "empty" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_example": { "summary": "Unauthorized Example", "description": "Example response for unauthorized access due to missing credentials.", "value": { "type": "https://example.com/probs/auth-error", "title": "Unauthorized", "status": 401, "detail": "Invalid or missing authentication credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_example": { "summary": "Forbidden Example", "description": "Example response when access is forbidden due to insufficient permissions.", "value": { "type": "https://example.com/probs/permission-error", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not found response when the worker's DID is not registered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not Found Example", "description": "Example response for a DID that does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The worker with the specified DID was not found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "Example response for an unexpected server error.", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred." } } } } } } } } }, "/v1/workforce/workflows": { "post": { "summary": "Create a new workflow definition", "description": "Launch the orchestration of human and AI tasks by defining a new workflow. This endpoint allows you to specify a series of steps, each identified by a unique step_id, aimed at automating complex processes with precision and safety through the HUMAN protocol.", "operationId": "createWorkflow", "tags": [ "Workforce", "Orchestration" ], "x-code-hash": "1a9de3ca2dac8d0e", "x-generated-at": "2026-03-24T23:18:43.699Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_name": { "type": "string", "description": "The human-readable name of the workflow." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "string", "description": "A unique identifier for the step." } }, "required": [ "step_id" ] }, "description": "An ordered list of steps that make up the workflow." }, "escalation_rules": { "type": "object", "description": "Optional rules for handling task escalations." } }, "required": [ "workflow_name", "steps" ] }, "examples": { "basic_workflow_creation": { "summary": "Basic Workflow Creation", "description": "Define a simple workflow with two steps to process invoices.", "value": { "workflow_name": "Invoice Processing", "steps": [ { "step_id": "verify_document" }, { "step_id": "approve_payment" } ], "escalation_rules": { "on_timeout": "notify_manager" } } } } } } }, "responses": { "201": { "description": "Workflow successfully created with an estimated throughput.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string", "description": "The unique identifier of the newly created workflow." }, "status": { "type": "string", "enum": [ "created" ], "description": "The status of the workflow creation process." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the workflow was created." }, "estimated_throughput": { "type": "string", "description": "Estimate of the workflow's processing capacity." } } }, "examples": { "default": { "summary": "Example", "value": { "workflow_id": "wf_1234567890", "status": "created", "created_at": "2023-10-12T14:48:00.000Z", "estimated_throughput": "~100 items/hour (MVP estimate)" } } } } } }, "400": { "description": "Invalid request due to missing or malformed fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid JSON Body", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-failed", "title": "Authentication Required", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "Permission denied for the requested operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to create workflows." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The specified workflow resource could not be found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/workforce/workflows/:workflowId/execute": { "post": { "summary": "Execute a workflow in the workforce system", "description": "Embark on a seamless journey of workflow execution within the HUMAN platform. This endpoint breathes life into your workflows, orchestrating tasks with precision and tracking their progress meticulously. It serves as the beating heart of operations, ensuring that tasks are not only executed but also monitored for efficiency and success.", "operationId": "executeWorkflow", "tags": [ "Workforce", "Execution" ], "x-code-hash": "d26b69fbd61ed1cf", "x-generated-at": "2026-03-30T18:01:44.412Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input_data": { "type": "array", "items": { "type": "object" }, "description": "Array of data items to process within the workflow" }, "priority": { "type": "string", "enum": [ "high", "normal", "low" ], "description": "Priority level of the execution" } }, "required": [ "input_data" ] }, "examples": { "standard_execution": { "summary": "Standard Execution", "description": "Executing a workflow with standard priority", "value": { "input_data": [ { "invoiceId": "12345", "amount": 200 }, { "invoiceId": "12346", "amount": 450 } ], "priority": "normal" } } } } } }, "responses": { "201": { "description": "Workflow execution initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string", "description": "Unique identifier for this execution" }, "workflow_id": { "type": "string", "description": "Identifier of the workflow being executed" }, "status": { "type": "string", "enum": [ "running" ], "description": "Current status of the execution" }, "started_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution started" }, "items_in_progress": { "type": "integer", "description": "Number of items currently being processed" }, "estimated_completion": { "type": "string", "format": "date-time", "description": "Estimated completion time for the execution" }, "progress_url": { "type": [ "string", "null" ], "description": "URL to track the progress of the execution" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid. Ensure you have valid credentials and try again." } } } } } }, "403": { "description": "Forbidden execution attempt due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to execute this workflow. Check your access rights or contact the administrator." } } } } } }, "404": { "description": "Workflow not found or inactive", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Workflow wf_12345 not found. Ensure the workflow ID is correct and that the workflow is active." } } } } } }, "500": { "description": "Internal server error during workflow execution", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while executing the workflow. Please try again later or contact support." } } } } } } } } }, "/v1/workforce/payments/tasks/:taskId": { "get": { "summary": "Retrieve Task Payment Details", "description": "Uncover the financial journey of a task through its payment details. This endpoint is your key to understanding the monetary status of a task, revealing insights about payments made and pending, tied to the workers' identities. Dive into the ledger of a task's lifecycle and manage your workforce with precision.", "operationId": "getWorkforcePaymentsTask", "tags": [ "Finance", "Workforce" ], "x-code-hash": "e2dcd673ee9ca754", "x-generated-at": "2026-03-24T23:19:36.247Z", "responses": { "200": { "description": "Successfully retrieved the payment details for a specific task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid" }, "payment_status": { "type": "string", "enum": [ "none", "pending", "completed" ] }, "worker_did": { "type": "string", "format": "uri" }, "amount": { "type": "number", "nullable": true }, "currency": { "type": "string" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "payment_method": { "type": "string", "nullable": true }, "transaction_id": { "type": "string", "nullable": true } } }, "examples": { "successful_payment_details_retrieval": { "summary": "Successful payment details retrieval", "description": "Fetches payment details for a task completed by a worker with all payment attributes filled.", "value": { "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "payment_status": "completed", "worker_did": "did:example:123456789abcdefghi", "amount": 150.75, "currency": "USD", "paid_at": "2023-11-01T15:30:45Z", "payment_method": "credit_card", "transaction_id": "txn_1A2B3C4D5E" } } } } } }, "400": { "description": "Invalid request due to malformed task ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_task_id_format": { "summary": "Invalid Task ID Format", "description": "Occurs when the provided task ID is not a valid UUID.", "value": { "type": "https://example.com/probs/invalid-task-id", "title": "Invalid Task ID", "status": 400, "detail": "The task_id must be a valid UUID.", "errors": [ { "field": "task_id", "code": "INVALID_FORMAT", "message": "task_id must be a UUID", "expected": "uuid", "received": "12345" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization": { "summary": "Missing Authorization", "description": "Occurs when the request lacks valid authentication credentials.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authorization credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Occurs when the user does not have the right permissions to access the task payment details.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access the payment details for this task." } } } } } }, "404": { "description": "Task not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "task_not_found": { "summary": "Task Not Found", "description": "Occurs when the task ID provided does not match any existing task.", "value": { "type": "https://example.com/probs/task-not-found", "title": "Task Not Found", "status": 404, "detail": "Task f47ac10b-58cc-4372-a567-0e02b2c3d479 not found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Occurs due to an unexpected condition that prevented the server from fulfilling the request.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } } }, "/v1/workforce/payments/earnings/:did": { "get": { "summary": "Retrieve earnings for a specific agent", "description": "Dive into the earnings of an agent over a specified period, allowing organizations to track performance and pending payments seamlessly. This endpoint exists to provide transparency and accountability in payment processing, ensuring agents are rewarded accurately for their contributions.", "operationId": "getWorkforcePaymentsEarnings", "tags": [ "Payments", "Workforce" ], "x-code-hash": "3c39a821f4d01ecf", "x-generated-at": "2026-03-24T23:19:58.052Z", "responses": { "200": { "description": "Successfully retrieved the earnings and payment breakdown for the specified DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier of the agent" }, "period": { "type": "string", "description": "The period for which earnings are calculated" }, "total_earnings": { "type": "number", "format": "float", "description": "Total earnings within the specified period" }, "currency": { "type": "string", "description": "The currency of the earnings, default is USD" }, "tasks_completed": { "type": "integer", "description": "Number of tasks completed in the period" }, "avg_earnings_per_task": { "type": "number", "format": "float", "description": "Average earnings per completed task" }, "payment_breakdown": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date of the earnings breakdown" }, "earnings": { "type": "number", "format": "float", "description": "Earnings for the day" }, "tasks_completed": { "type": "integer", "description": "Tasks completed on that day" } } } }, "pending_payments": { "type": "number", "format": "float", "description": "Total amount of pending payments" } } }, "examples": { "acme_corporation_agent_earnings": { "summary": "Acme Corporation Agent Earnings", "description": "Earnings details for an agent from Acme Corporation over the last 30 days.", "value": { "did": "did:example:123456789abcdefghi", "period": "30 days", "total_earnings": 1500.75, "currency": "USD", "tasks_completed": 50, "avg_earnings_per_task": 30.01, "payment_breakdown": [ { "date": "2023-10-20", "earnings": 100, "tasks_completed": 3 }, { "date": "2023-10-19", "earnings": 200, "tasks_completed": 5 } ], "pending_payments": 300.5 } } } } } }, "400": { "description": "Bad request due to validation errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_did_parameter": { "summary": "Missing DID Parameter", "description": "The DID path parameter is required but was not provided.", "value": { "type": "https://example.com/probs/validation-error", "title": "Bad Request", "status": 400, "detail": "The provided request has validation errors.", "errors": [ { "field": "did", "code": "REQUIRED_FIELD_MISSING", "message": "did path parameter is required", "expected": "string", "received": "empty" } ] } }, "invalid_period_format": { "summary": "Invalid Period Format", "description": "The 'period' query parameter was not in a valid format.", "value": { "type": "https://example.com/probs/validation-error", "title": "Bad Request", "status": 400, "detail": "The provided request has validation errors.", "errors": [ { "field": "period", "code": "INVALID_FORMAT", "message": "period must be like 7d, 30d, or 90d", "expected": "7d|30d|90d", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "No authentication token provided.", "value": { "type": "https://example.com/probs/authentication-error", "title": "Unauthorized", "status": 401, "detail": "Authentication token is missing or invalid. Please provide a valid token." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have permission to access this resource.", "value": { "type": "https://example.com/probs/permission-error", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "Resource not found because DID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "did_not_found": { "summary": "DID Not Found", "description": "The specified DID does not correspond to any agent.", "value": { "type": "https://example.com/probs/not-found-error", "title": "Not Found", "status": 404, "detail": "The requested DID was not found. Please verify the DID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/workforce/payments/payout": { "post": { "summary": "Initiate a payout for workforce members", "description": "Embark on the journey of rewarding your workforce. This endpoint allows organizations to seamlessly initiate payouts to their workforce with the assurance of cryptographic identity verification and provenance tracking. It's designed to ensure that the right amount reaches the right individual securely and efficiently.", "operationId": "initiatePayout", "tags": [ "Payments", "Workforce" ], "x-code-hash": "5f6a7a3cb4324330", "x-generated-at": "2026-03-24T23:20:18.373Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The Decentralized Identifier (DID) of the recipient's Passport." }, "amount": { "type": "number", "minimum": 0.01, "description": "The amount to be paid out." }, "currency": { "type": "string", "description": "The currency in which the payout will be made. Defaults to USD." }, "destination": { "type": "object", "description": "Destination details for the payout." } }, "required": [ "did", "amount", "destination" ] }, "examples": { "standard_payout": { "summary": "Standard Payout", "description": "A typical payout request for an employee with a specific DID.", "value": { "did": "did:example:123456789abcdefghi", "amount": 1500, "currency": "USD", "destination": { "bankAccount": "123456789", "bankName": "Acme Bank" } } } } } } }, "responses": { "201": { "description": "Payout successfully initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "payout_id": { "type": "string", "description": "Unique identifier for the payout." }, "status": { "type": "string", "description": "Current status of the payout." }, "amount": { "type": "number", "description": "The amount being paid out." }, "currency": { "type": "string", "description": "Currency of the payout." }, "estimated_arrival": { "type": "string", "format": "date-time", "description": "Estimated arrival time of the payout." }, "fee": { "type": "number", "description": "Transaction fee for the payout." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request format or data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body must be valid JSON.", "errors": [ { "field": "body", "message": "Request body must be valid JSON" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Valid authentication credentials are required." } } } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have permission to initiate payouts." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/server-error", "title": "Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/workforce/analytics/metrics": { "get": { "summary": "Retrieve workforce analytics metrics", "description": "In the realm of Human-AI collaboration, understanding workforce dynamics is crucial. This endpoint provides a window into the metrics that matter—how tasks are flowing, who's active, and financial summaries—over selectable periods. It's a vital tool for organizations like 'acme' to optimize their human and AI resources.", "operationId": "getWorkforceAnalyticsMetrics", "tags": [ "Analytics", "Workforce" ], "x-code-hash": "3b8b5bd107a56ba2", "x-generated-at": "2026-03-24T23:20:47.721Z", "responses": { "200": { "description": "Successfully retrieved workforce analytics metrics for the specified period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "example": "7 days" }, "total_tasks": { "type": "integer", "example": 120 }, "completed_tasks": { "type": "integer", "example": 100 }, "completion_rate": { "type": "number", "format": "float", "example": 0.833 }, "avg_completion_time": { "type": "integer", "example": 360 }, "avg_quality_score": { "type": [ "number", "null" ], "example": null }, "active_workers": { "type": "integer", "example": 25 }, "total_payments": { "type": "number", "format": "float", "example": 1500.5 }, "currency": { "type": "string", "example": "USD" }, "task_breakdown": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "data_entry": 60, "quality_check": 40 } } } }, "examples": { "acme_workforce_analytics": { "summary": "Acme Workforce Analytics", "description": "An example showing metrics for the 'acme' organization over a 7-day period.", "value": { "period": "7 days", "total_tasks": 120, "completed_tasks": 100, "completion_rate": 0.833, "avg_completion_time": 360, "avg_quality_score": null, "active_workers": 25, "total_payments": 1500.5, "currency": "USD", "task_breakdown": { "data_entry": 60, "quality_check": 40 } } } } } } }, "400": { "description": "Invalid request due to incorrect parameter format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_period_format": { "summary": "Invalid Period Format", "description": "Example of a malformed request with incorrect 'period' parameter.", "value": { "type": "https://humanprotocol.org/error/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'period' query parameter is incorrectly formatted.", "errors": [ { "field": "period", "code": "INVALID_FORMAT", "message": "period must be like 7d, 30d, or 90d", "expected": "7d|30d|90d", "received": "" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport": { "summary": "Missing Passport", "description": "Example of a request made without valid authentication, resulting in a 401 error.", "value": { "type": "https://humanprotocol.org/error/unauthorized", "title": "Unauthorized", "status": 401, "detail": "The request lacks valid authentication credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Example of a request made with valid credentials but insufficient permissions.", "value": { "type": "https://humanprotocol.org/error/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "endpoint_not_found": { "summary": "Endpoint Not Found", "description": "Example of accessing an endpoint that does not exist, resulting in a 404 error.", "value": { "type": "https://humanprotocol.org/error/not-found", "title": "Not Found", "status": 404, "detail": "The requested endpoint does not exist." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Example of an internal server error due to a system malfunction.", "value": { "type": "https://humanprotocol.org/error/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/workforce/analytics/quality/:taskId": { "get": { "summary": "Retrieve Task Quality Analytics", "description": "Dive into the heart of HUMAN's task quality analytics to uncover the intricate balance of human and AI decision-making. This endpoint provides a snapshot of the quality metrics for a specific task, offering insights into reviewer consensus, accuracy metrics, and worker performance. It's a window into the orchestration of human and AI interactions, ensuring tasks meet the highest standards.", "operationId": "getWorkforceAnalyticsQuality", "tags": [ "Analytics", "Quality" ], "x-code-hash": "ac01f8242a121e59", "x-generated-at": "2026-03-24T23:21:06.712Z", "responses": { "200": { "description": "Returns the quality metrics and insights for the specified task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid" }, "quality_score": { "type": [ "number", "null" ] }, "reviewer_consensus": { "type": [ "number", "null" ] }, "accuracy_metrics": { "type": "object", "properties": { "precision": { "type": [ "number", "null" ] }, "recall": { "type": [ "number", "null" ] }, "f1_score": { "type": [ "number", "null" ] } } }, "worker_performance": { "type": [ "object", "null" ], "properties": { "did": { "type": "string" }, "historical_quality": { "type": [ "number", "null" ] }, "improvement_trend": { "type": [ "string", "null" ] } } }, "feedback": { "type": [ "string", "null" ] } } }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "value": { "task_id": "123e4567-e89b-12d3-a456-426614174000", "quality_score": 0.96, "reviewer_consensus": 0.96, "accuracy_metrics": { "precision": null, "recall": null, "f1_score": null }, "worker_performance": { "did": "did:human:passport:abc123", "historical_quality": null, "improvement_trend": null }, "feedback": "Excellent work, minor adjustments needed." } } } } } }, "400": { "description": "Invalid request due to malformed task ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_uuid": { "summary": "Invalid UUID", "value": { "type": "https://humanprotocol.org/errors/invalid-format", "title": "Invalid Task ID Format", "status": 400, "detail": "The provided task_id is not a valid UUID. Ensure task_id is correctly formatted.", "errors": [ { "field": "task_id", "code": "INVALID_FORMAT", "message": "task_id must be a UUID", "expected": "uuid", "received": "abc" } ] } } } } } }, "404": { "description": "The specified task was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "task_not_found": { "summary": "Task Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Task Not Found", "status": 404, "detail": "Task 123e4567-e89b-12d3-a456-426614174000 not found. Verify the task_id and try again." } } } } } }, "500": { "description": "Server error while processing request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/templates": { "get": { "summary": "Retrieve Agent Templates from Marketplace", "description": "Uncover the treasure trove of agent templates available in the HUMAN marketplace. This endpoint empowers you to explore a collection of predefined task orchestrations, essential for any organization looking to optimize human-AI collaboration swiftly.", "operationId": "getMarketplaceTemplates", "tags": [ "Marketplace", "Templates" ], "x-code-hash": "1b95b27a52449e3d", "x-generated-at": "2026-03-24T23:27:59.993Z", "responses": { "200": { "description": "Successfully retrieved a list of agent templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the template." }, "name": { "type": "string", "description": "Name of the agent template." }, "description": { "type": "string", "description": "Brief description of the template's purpose." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the template was created." } }, "required": [ "id", "name", "created_at" ] } }, "limit": { "type": "integer", "description": "Maximum number of items returned." }, "cursor": { "type": "string", "description": "Cursor for pagination to the next set of results." }, "hasMore": { "type": "boolean", "description": "Indicates if there are more templates available beyond the current page." } } }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "description": "Fetching the first page of templates for organization 'acme'.", "value": { "data": [ { "id": "template-001", "name": "Invoice Processor", "description": "Automates invoice processing using AI.", "created_at": "2023-08-15T14:30:00Z" }, { "id": "template-002", "name": "Customer Feedback Analyzer", "description": "Analyzes customer feedback for sentiment analysis.", "created_at": "2023-08-12T09:00:00Z" } ], "limit": 2, "cursor": "opaque-cursor-string", "hasMore": true } } } } } }, "400": { "description": "Invalid request due to incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "A request with an invalid cursor.", "value": { "type": "https://api.human.com/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The pagination cursor is invalid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor from previous response", "received": "invalid-cursor" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Attempt to access without valid credentials.", "value": { "type": "https://api.human.com/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Access attempt by a user without required roles.", "value": { "type": "https://api.human.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Attempt to retrieve a non-existent template.", "value": { "type": "https://api.human.com/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested templates could not be found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "Unexpected error during request processing.", "value": { "type": "https://api.human.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/installed": { "get": { "summary": "Retrieve Installed Marketplace Assets", "description": "In the bustling ecosystem of HUMAN, knowing what assets your organization has harnessed is crucial. This endpoint unveils the list of marketplace assets currently powering an organization, offering insights into the tools and capabilities actively in play. By maintaining a current view of installed assets, organizations can ensure alignment with their strategic goals and optimize their operational efficiency.", "operationId": "getInstalledMarketplaceAssets", "tags": [ "Marketplace", "Assets" ], "x-code-hash": "92e92f4f1aaf342e", "x-generated-at": "2026-03-24T23:28:32.741Z", "responses": { "200": { "description": "A comprehensive list of marketplace assets installed for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "asset_type": { "type": "string" }, "trust_tier": { "type": "string" }, "installed_at": { "type": "string", "format": "date-time" } } } } } }, "examples": { "installed_assets_example": { "summary": "Installed Assets Example", "description": "Shows a list of installed assets for an organization.", "value": { "data": [ { "id": "asset-123", "name": "AI Data Processor", "asset_type": "data_processing", "trust_tier": "high", "installed_at": "2023-10-01T12:34:56Z" }, { "id": "asset-456", "name": "Blockchain Verifier", "asset_type": "verification", "trust_tier": "medium", "installed_at": "2023-09-15T09:21:00Z" } ] } } } } } }, "400": { "description": "The request is missing required parameters or includes invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_example": { "summary": "Missing orgDid Example", "description": "Illustrates the error when 'orgDid' is not provided.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing orgDid", "status": 400, "detail": "orgDid query parameter is required." } } } } } }, "401": { "description": "Authentication failed due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "Demonstrates the scenario where authentication is required but not provided.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Access is forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Occurs when the user lacks the necessary permissions to view the installed assets.", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "description": "Illustrates the error when the specified organization does not exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested organization was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "Demonstrates a scenario where an internal server error occurs.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/:assetId": { "get": { "summary": "Retrieve a marketplace asset by ID", "description": "Dive into the dynamic world of HUMAN's marketplace by exploring a specific asset through its unique identifier. This endpoint not only unveils the asset's details but also provides a glimpse into its latest user feedback, fostering an informed decision-making process.", "operationId": "getMarketplaceAsset", "tags": [ "Marketplace", "Assets" ], "x-code-hash": "1c634d62feba90f4", "x-generated-at": "2026-03-24T23:28:52.320Z", "responses": { "200": { "description": "Successfully retrieved the asset details along with the latest review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the asset." }, "name": { "type": "string", "description": "The name of the asset." }, "description": { "type": "string", "description": "A brief description of the asset." }, "latest_review": { "type": "object", "nullable": true, "properties": { "reviewer": { "type": "string", "description": "The name of the reviewer." }, "comment": { "type": "string", "description": "The content of the review." }, "created_at": { "type": "string", "format": "date-time", "description": "The time when the review was created." } } } }, "required": [ "id", "name", "description" ] }, "examples": { "successful_asset_retrieval": { "summary": "Successful Asset Retrieval", "value": { "id": "asset-12345", "name": "AI Invoice Processor", "description": "An AI tool that automates invoice processing for enterprises.", "latest_review": { "reviewer": "John Doe", "comment": "Extremely efficient and easy to integrate.", "created_at": "2023-10-05T14:48:00Z" } } } } } } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_asset_id": { "summary": "Invalid Asset ID", "value": { "type": "https://humanplatform.com/problem/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The asset ID provided is not a valid format. Ensure the asset ID is alphanumeric and try again." } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "value": { "type": "https://humanplatform.com/problem/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided. Please include a valid Passport token in the request headers." } } } } } }, "403": { "description": "The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://humanplatform.com/problem/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this asset. Please contact your administrator to request access." } } } } } }, "404": { "description": "The requested resource could not be found but may be available in the future.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "asset_not_found": { "summary": "Asset Not Found", "value": { "type": "https://humanplatform.com/problem/not-found", "title": "Not Found", "status": 404, "detail": "Asset 'asset-12345' not found. Please verify the asset ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanplatform.com/problem/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/control-plane/marketplace/:assetId/reviews": { "get": { "summary": "Fetch reviews for a marketplace asset", "description": "Discover the insights and feedback from users for a specific asset on the Developer Home page. This endpoint exists to provide transparency and assist developers in improving their offerings by learning from user experiences.", "operationId": "getAssetReviews", "tags": [ "Marketplace", "Reviews" ], "x-code-hash": "645738ad0b5039dc", "x-generated-at": "2026-03-24T23:29:13.079Z", "responses": { "200": { "description": "Successfully retrieved the reviews for the specified asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "reviewId": { "type": "string" }, "userId": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "comment": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "reviewId", "userId", "rating", "created_at" ] } }, "limit": { "type": "integer" }, "cursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "hasMore" ] }, "examples": { "successful_review_fetch": { "summary": "Successful Review Fetch", "description": "A list of reviews for the asset with ID 'asset123'.", "value": { "data": [ { "reviewId": "rev001", "userId": "user789", "rating": 4, "comment": "Great asset, very useful!", "created_at": "2023-10-01T12:00:00Z" } ], "limit": 10, "cursor": null, "hasMore": false } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "An example of an invalid cursor error.", "value": { "type": "https://developer.humanprotocol.org/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters are invalid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor from previous response", "received": "invalid_cursor_value" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_example": { "summary": "Missing Authentication Example", "description": "An example where the user has not provided authentication credentials.", "value": { "type": "https://developer.humanprotocol.org/probs/auth-required", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied_example": { "summary": "Access Denied Example", "description": "An example where the user is denied access to the resource.", "value": { "type": "https://developer.humanprotocol.org/probs/access-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Asset not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "asset_not_found_example": { "summary": "Asset Not Found Example", "description": "An example where the asset ID does not exist.", "value": { "type": "https://developer.humanprotocol.org/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified asset ID was not found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An example of a server error during the request.", "value": { "type": "https://developer.humanprotocol.org/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/install": { "post": { "summary": "Install Marketplace Asset to Organization", "description": "Seamlessly integrate pre-approved marketplace assets into your organization using the HUMAN platform. This endpoint facilitates the installation process by ensuring assets meet organizational policies and trust tiers, empowering organizations to expand their capabilities securely.", "operationId": "installMarketplaceAsset", "tags": [ "Marketplace", "Assets", "Installation" ], "x-code-hash": "e93b968dab1bcd5f", "x-generated-at": "2026-03-29T14:49:42.316Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "description": "Unique identifier for the asset to be installed." }, "org_did": { "type": "string", "description": "Decentralized identifier (DID) of the organization." }, "config_overrides": { "type": "object", "additionalProperties": true, "description": "Configuration overrides specific to the asset installation." }, "preset": { "type": "string", "description": "Preset configuration for the asset, defaults to 'safe'.", "default": "safe" }, "custom_scopes": { "type": "array", "items": { "type": "string" }, "description": "Custom scopes required for asset installation." } }, "required": [ "asset_id", "org_did" ] }, "examples": { "basic_installation": { "summary": "Basic Installation", "description": "Install a simple extension asset to an organization.", "value": { "asset_id": "asset-12345", "org_did": "did:org:acme", "config_overrides": {}, "preset": "safe" } } } } } }, "responses": { "201": { "description": "Asset installed successfully with all policies adhered to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "Confirmation of successful installation." } } }, "examples": { "default": { "summary": "Example", "value": { "result": "Asset 'asset-12345' successfully installed for organization 'did:org:acme'." } } } } } }, "400": { "description": "Request is missing required fields or has invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing required fields", "status": 400, "detail": "asset_id and org_did are required." } } } } } }, "403": { "description": "Installation blocked due to organizational policy restrictions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/policy-blocked", "title": "Blocked by Org Policy", "status": 403, "detail": "Asset blocked by org marketplace policy: asset_type 'extension' is in deny list." } } } } } }, "404": { "description": "Asset not found in the marketplace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Asset Not Found", "status": 404, "detail": "Asset 'asset-12345' not found." } } } } } }, "422": { "description": "Asset is not approved for installation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/asset-not-approved", "title": "Asset Not Approved", "status": 422, "detail": "Asset is in review_status 'pending', not approved for installation." } } } } } }, "500": { "description": "Server encountered an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/delegation-issuance-failed", "title": "Delegation Issuance Failed", "status": 500, "detail": "An unexpected error occurred while issuing a delegation." } } } } } } } } }, "/v1/control-plane/marketplace/uninstall": { "post": { "summary": "Uninstall asset with delegation revocation", "description": "Uninstall a marketplace asset, cascading the removal of associated delegations. This endpoint is vital for maintaining clean operational environments by ensuring that unused assets do not retain lingering permissions, thus upholding security and efficiency.", "operationId": "uninstallMarketplaceAsset", "tags": [ "Marketplace", "Asset Management" ], "x-code-hash": "4073ee7d21a8e2df", "x-generated-at": "2026-03-24T23:30:21.220Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "description": "The unique identifier of the asset to be uninstalled." }, "org_did": { "type": "string", "description": "The decentralized identifier for the organization." } }, "required": [ "asset_id", "org_did" ] }, "examples": { "uninstall_asset_example": { "summary": "Uninstall Asset Example", "description": "Uninstall an asset from the 'acme' organization.", "value": { "asset_id": "asset_12345", "org_did": "did:example:acme" } } } } } }, "responses": { "200": { "description": "The asset has been successfully uninstalled, and delegations have been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uninstalled": { "type": "boolean", "description": "Indicates if the uninstallation was successful." }, "installation": { "type": "object", "description": "Details of the uninstalled asset installation.", "properties": { "asset_id": { "type": "string" }, "org_did": { "type": "string" }, "uninstalled_at": { "type": "string", "format": "date-time" } } } } }, "examples": { "successful_uninstallation": { "summary": "Successful Uninstallation", "value": { "uninstalled": true, "installation": { "asset_id": "asset_12345", "org_did": "did:example:acme", "uninstalled_at": "2023-10-01T12:34:56Z" } } } } } } }, "400": { "description": "The request is missing required fields or is malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_fields_example": { "summary": "Missing Fields Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing required fields", "status": 400, "detail": "asset_id and org_did are required.", "errors": [ "asset_id is required", "org_did is required" ] } } } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Permission denied for this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_operation_example": { "summary": "Forbidden Operation Example", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to uninstall this asset." } } } } } }, "404": { "description": "The specified asset installation could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "asset_not_found_example": { "summary": "Asset Not Found Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Installation not found for asset 'asset_12345' in org 'did:example:acme'." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error_example": { "summary": "Unexpected Server Error Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/review-queue": { "get": { "summary": "Retrieve pending marketplace asset reviews", "description": "In the vibrant ecosystem of the HUMAN platform, the review queue serves as a crucial checkpoint for marketplace assets awaiting human scrutiny. This endpoint invites administrators to survey the pending and escalated items, ensuring that each asset aligns with the platform's standards and values. By scrutinizing these assets, administrators uphold the integrity and safety that HUMAN users rely upon.", "operationId": "getMarketplaceReviewQueue", "tags": [ "Marketplace", "Review" ], "x-code-hash": "00c4ccd1575c7dd7", "x-generated-at": "2026-03-24T23:30:47.803Z", "responses": { "200": { "description": "A successful response containing a list of marketplace assets pending review along with their latest review details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "latest_review": { "type": "object", "properties": { "decision": { "type": "string" }, "risk_assessment": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "id", "created_at", "latest_review" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": "string" } } }, "examples": { "pending_reviews_-_acme_corp": { "summary": "Pending Reviews - Acme Corp", "description": "An example showing a list of assets from Acme Corp awaiting review.", "value": { "data": [ { "id": "asset-123", "submitted_at": "2023-10-01T12:34:56Z", "created_at": "2023-09-30T11:33:55Z", "latest_review": { "decision": "pending", "risk_assessment": {}, "created_at": "2023-09-30T11:34:56Z" } } ], "hasMore": true, "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMy0wOS0zMFQxMTozMzo1NVoiLCJpZCI6ImFzc2V0LTEyMyJ9" } } } } } }, "400": { "description": "The request parameters were invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "value": { "type": "https://example.com/probs/invalid-param", "title": "Invalid Request Parameter", "status": 400, "detail": "The 'limit' query parameter must be a positive integer.", "errors": [ "limit must be a positive integer" ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "You must authenticate to access the review queue." } } } } } }, "403": { "description": "The user does not have permission to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://example.com/probs/access-denied", "title": "Access Denied", "status": 403, "detail": "You do not have the required permissions to view the review queue." } } } } } }, "404": { "description": "No assets found matching the query criteria.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "assets_not_found": { "summary": "Assets Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Assets Not Found", "status": 404, "detail": "No assets were found matching the specified criteria." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while fetching the review queue. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/:assetId/decide": { "post": { "summary": "Decide on Asset Review Outcome", "description": "Empower human reviewers to influence the marketplace by approving, rejecting, or requesting changes to assets. This decision-making endpoint is pivotal in ensuring asset quality and compliance, particularly when AI alone cannot guarantee safety or fairness.", "operationId": "postMarketplaceAssetDecide", "tags": [ "Marketplace", "Asset Control" ], "x-code-hash": "096c79d5e44a1786", "x-generated-at": "2026-03-30T18:03:40.671Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "reject", "request_changes" ], "description": "The decision made by the reviewer." }, "bypass_compute_billing_gate": { "type": "boolean", "description": "Flag to bypass the compute billing gate, requires admin scope." }, "bypass_iframe_trust_gate": { "type": "boolean", "description": "Flag to bypass the iframe trust gate, requires admin scope." }, "notes": { "type": "string", "description": "Additional notes from the reviewer about the decision." }, "risk_assessment": { "type": "object", "description": "Optional JSON object for any risk assessments conducted." } }, "required": [ "decision" ] }, "examples": { "approve_agent_asset": { "summary": "Approve Agent Asset", "description": "Approving an agent asset with a valid cost profile.", "value": { "decision": "approve", "notes": "The asset meets all criteria and is ready for approval.", "risk_assessment": { "level": "low", "comments": "Thoroughly vetted and deemed secure." } } } } } } }, "responses": { "200": { "description": "Successfully updated the asset's review status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the asset." }, "review_status": { "type": "string", "description": "The new review status of the asset." }, "approved_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the asset was approved." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad request due to invalid decision input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid decision", "status": 400, "detail": "Must be one of: approve, reject, request_changes" } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Valid credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden due to lack of necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Asset not found for the given assetId.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Asset not found", "status": 404, "detail": "Asset 'asset123' not found." } } } } } }, "422": { "description": "Unprocessable Entity due to approval conditions not met.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/compute-billing-gate", "title": "Cost profile required for approval", "status": 422, "detail": "Agent and muscle assets must have a measured cost_profile (sample_count ≥ 1 or p50/p95 token or cost metrics) before approval. Admins with marketplace:admin:global may set bypass_compute_billing_gate: true to override." } } } } } }, "500": { "description": "Internal server error during the decision process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the decision." } } } } } } } } }, "/v1/control-plane/marketplace/:assetId/promote-tier": { "post": { "summary": "Elevate an asset's trust tier", "description": "Promote the trust tier of a marketplace asset to enhance its credibility and unlock new capabilities. This operation is critical for assets aspiring to reach higher levels of trust and visibility, reflecting their reliability and adherence to safety standards.", "operationId": "promoteTierForMarketplaceAsset", "tags": [ "Marketplace", "Trust Management" ], "x-code-hash": "9970622714c6ed93", "x-generated-at": "2026-03-24T23:31:28.521Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trust_tier": { "type": "string", "enum": [ "community", "verified", "certified", "enterprise" ], "description": "The trust level to promote the asset to" } }, "required": [ "trust_tier" ] }, "examples": { "promote_to_enterprise_tier": { "summary": "Promote to Enterprise Tier", "description": "Example of promoting an asset to the 'enterprise' trust tier.", "value": { "trust_tier": "enterprise" } } } } } }, "responses": { "200": { "description": "The asset's trust tier was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the asset" }, "trust_tier": { "type": "string", "description": "The updated trust tier of the asset" } } }, "examples": { "successful_promotion": { "summary": "Successful Promotion", "description": "The asset was successfully promoted to the 'enterprise' tier.", "value": { "id": "asset-12345", "trust_tier": "enterprise" } } } } } }, "400": { "description": "Invalid input data provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_trust_tier": { "summary": "Invalid Trust Tier", "description": "Provided trust tier is not recognized.", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid trust_tier", "status": 400, "detail": "Must be one of: community, verified, certified, enterprise" } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication token is missing or invalid." } } } } } }, "403": { "description": "The client does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The client lacks the 'marketplace:admin:global' scope.", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to promote asset tiers." } } } } } }, "404": { "description": "The specified asset was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "asset_not_found": { "summary": "Asset Not Found", "description": "The asset ID provided does not exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Asset Not Found", "status": 404, "detail": "Asset 'asset-12345' not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected condition was encountered.", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/:assetId/promote-lifecycle": { "post": { "summary": "Promote asset lifecycle stage within marketplace", "description": "Elevate the lifecycle stage of a marketplace asset, ensuring it meets the necessary criteria for progression. This endpoint is crucial for managing asset readiness and compliance in a structured, verifiable manner.", "operationId": "promoteLifecycleStage", "tags": [ "Marketplace", "Lifecycle Management" ], "x-code-hash": "40445ee7fd821e2a", "x-generated-at": "2026-03-24T23:31:45.825Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "The desired lifecycle stage to promote the asset to.", "enum": [ "staging", "production" ] } }, "required": [ "to" ] }, "examples": { "promote_to_production": { "summary": "Promote to production", "description": "Promoting an asset from staging to production.", "value": { "to": "production" } } } } } }, "responses": { "200": { "description": "Successfully promoted the asset to the specified lifecycle stage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "publisher_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "successful_promotion": { "summary": "Successful Promotion", "value": { "id": "asset-123", "lifecycle_stage": "production", "publisher_id": "org-789", "updated_at": "2023-10-15T12:45:30Z" } } } } } }, "400": { "description": "Bad request due to invalid lifecycle stage or inappropriate transition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_transition": { "summary": "Invalid Transition", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid promote", "status": 400, "detail": "Can only promote from staging to production" } } } } } }, "401": { "description": "Authentication required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://haio.run/errors/authentication", "title": "Authentication Error", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Insufficient permissions to promote the asset.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "value": { "type": "https://haio.run/errors/permission", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to promote this asset" } } } } } }, "404": { "description": "The asset with the specified ID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "asset_not_found": { "summary": "Asset Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Asset Not Found", "status": 404, "detail": "No asset found with the ID 'asset-123'" } } } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/:assetId/rollback-lifecycle": { "post": { "summary": "Rollback asset lifecycle stage", "description": "Navigate the complex journey of digital assets within HUMAN's marketplace by rolling back their lifecycle stage. This endpoint empowers you to manage asset transitions with precision, ensuring the continuity and safety of AI-orchestrated tasks.", "operationId": "rollbackLifecycleStage", "tags": [ "Marketplace", "Lifecycle Management" ], "x-code-hash": "e58040a91c24ab79", "x-generated-at": "2026-03-24T23:32:04.237Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "The desired stage to rollback to (e.g., 'staging').", "enum": [ "staging", "development", "production" ] } }, "required": [ "to" ] }, "examples": { "rollback_to_staging": { "summary": "Rollback to Staging", "description": "This example rolls back the asset lifecycle stage to 'staging'.", "value": { "to": "staging" } } } } } }, "responses": { "200": { "description": "The asset's lifecycle stage was successfully rolled back.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the asset." }, "lifecycle_stage": { "type": "string", "description": "The current lifecycle stage of the asset." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid to", "status": 400, "detail": "Must be one of: staging, development, production" } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Delegation required", "status": 401, "detail": "No valid delegation was provided. Ensure your request includes a delegation token in the headers." } } } } } }, "403": { "description": "The user is authenticated but does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have permission to modify the lifecycle stage of this asset." } } } } } }, "404": { "description": "The specified asset could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Asset not found", "status": 404, "detail": "No asset with id '12345' exists in the marketplace. Verify the asset ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/assets/:assetId/analytics": { "get": { "summary": "Retrieve analytics for a marketplace asset", "description": "Dive into the heart of your asset's performance with this endpoint. Designed for publishers and administrators, it surfaces valuable metrics like installations, usage, and pseudo-revenue. Understanding these analytics helps you optimize your asset's presence in the marketplace, driving strategic decisions and growth.", "operationId": "getAssetAnalytics", "tags": [ "Analytics", "Marketplace" ], "x-code-hash": "9529ef8270a05018", "x-generated-at": "2026-04-02T20:11:41.466Z", "responses": { "200": { "description": "Successfully retrieved asset analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "description": "Unique identifier for the asset" }, "asset_name": { "type": "string", "description": "Name of the asset" }, "asset_type": { "type": "string", "description": "Type of the asset" }, "trust_tier": { "type": "string", "description": "Trust tier of the asset" }, "period": { "type": "object", "properties": { "label": { "type": "string", "description": "Period label" }, "days": { "type": "integer", "description": "Number of days in the period" }, "since": { "type": "string", "format": "date-time", "description": "Start date for the period" } } }, "installs": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of installs" }, "active": { "type": "integer", "description": "Number of active installs" } } }, "usage": { "type": "object", "properties": { "invocations": { "type": "integer", "description": "Number of invocations" }, "total_units": { "type": "number", "description": "Total units consumed" }, "platform_cost_usd": { "type": "number", "description": "Platform cost in USD" } } }, "revenue": { "type": "object", "properties": { "revenue_usd": { "type": "number", "description": "Revenue in USD" }, "is_projection": { "type": "boolean", "description": "Indicates if the revenue is a projection" }, "projection_note": { "type": "string", "nullable": true, "description": "Note about the revenue projection" } } }, "top_orgs_by_usage": { "type": "array", "items": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Organization DID" }, "invocations": { "type": "integer", "description": "Number of invocations by the organization" }, "total_units": { "type": "number", "description": "Total units consumed by the organization" } } } } } }, "examples": { "successful_response_example": { "summary": "Successful Response Example", "description": "An example showing analytics for an asset over a 30-day period.", "value": { "asset_id": "asset123", "asset_name": "AI Invoice Processor", "asset_type": "application", "trust_tier": "high", "period": { "label": "30d", "days": 30, "since": "2023-09-01T00:00:00.000Z" }, "installs": { "total": 1500, "active": 1450 }, "usage": { "invocations": 12000, "total_units": 12000, "platform_cost_usd": 12 }, "revenue": { "revenue_usd": 12, "is_projection": true, "projection_note": "Billing not yet live. Projection uses $0.001/invocation placeholder rate." }, "top_orgs_by_usage": [ { "org_did": "org:acme", "invocations": 5000, "total_units": 5000 }, { "org_did": "org:beta", "invocations": 3000, "total_units": 3000 } ] } } } } } }, "400": { "description": "Invalid period parameter or request format", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_period_parameter": { "summary": "Invalid Period Parameter", "value": { "type": "/errors/invalid-period", "title": "Invalid Request Parameter", "status": 400, "detail": "The 'period' query parameter must be one of '7d', '30d', or '90d'." } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization": { "summary": "Missing Authorization", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided. Please provide a valid Passport or authorization token." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Publisher identity or marketplace:admin:global scope is required to view asset analytics." } } } } } }, "404": { "description": "Asset not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "asset_not_found": { "summary": "Asset Not Found", "value": { "type": "/errors/not-found", "title": "Asset Not Found", "status": 404, "detail": "The asset with ID 'asset123' was not found. Please verify the asset ID and try again." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/control-plane/marketplace/sync": { "get": { "summary": "Synchronize Marketplace Assets", "description": "In the vast ecosystem of human and AI collaboration, staying updated is crucial. This endpoint allows self-hosted platforms to synchronize with the latest approved and globally visible assets from haio.run. By leveraging this, organizations can ensure they have the most current tools and resources at their disposal, enhancing their capability graph and ensuring seamless operations.", "operationId": "getMarketplaceSync", "tags": [ "Marketplace", "Synchronization" ], "x-code-hash": "81f75a7cb5bde1fe", "x-generated-at": "2026-03-24T23:33:01.376Z", "responses": { "200": { "description": "Successfully retrieved the list of approved and globally visible marketplace assets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "asset_type": { "type": "string" }, "trust_tier": { "type": "string" }, "review_status": { "type": "string" }, "visibility": { "type": "string" }, "manifest_json": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "synced_at": { "type": "string", "format": "date-time" } } }, "examples": { "successful_synchronization": { "summary": "Successful Synchronization", "description": "The response includes a list of assets that have been updated since the last sync.", "value": { "assets": [ { "id": "asset-123", "name": "AI-Powered Invoice Processor", "asset_type": "tool", "trust_tier": "high", "review_status": "approved", "visibility": "global", "manifest_json": "{\"version\": \"1.0\", \"features\": [\"OCR\", \"Auto-Categorization\"]}", "updated_at": "2023-10-01T12:34:56Z" } ], "synced_at": "2023-10-07T14:35:00Z" } } } } } }, "400": { "description": "Request validation failed due to incorrect query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_date_format": { "summary": "Invalid Date Format", "description": "The 'since' query parameter is not a valid date.", "value": { "type": "https://humanprotocol.org/errors/invalid-query", "title": "Invalid query parameter", "status": 400, "detail": "'since' parameter must be a valid ISO 8601 date-time string.", "errors": [ "since: Invalid date format" ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The user has not provided valid authentication credentials.", "value": { "type": "https://humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "User does not have permission to access marketplace assets.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "The user's role does not permit access to the marketplace synchronization.", "value": { "type": "https://humanprotocol.org/errors/insufficient-permissions", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "The endpoint or resource could not be located.", "value": { "type": "https://humanprotocol.org/errors/resource-not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found. Please check the URL and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server error occurred that prevented fulfilling the request.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/": { "get": { "summary": "Discover the HUMAN API's live status", "description": "This root discovery endpoint is your gateway to the HUMAN API, offering real-time insights into its operational status. It serves as the heartbeat of the HUMAN platform, ensuring that the trust layer between human decisions and machine execution remains robust and transparent.", "operationId": "getRootDiscovery", "tags": [ "Discovery", "Status" ], "x-code-hash": "25c2a13cf03ce77f", "x-generated-at": "2026-03-24T21:26:06.360Z", "responses": { "200": { "description": "The API is operational and ready to serve requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string", "enum": [ "operational", "degraded" ] }, "endpoints": { "type": "object", "properties": { "health": { "type": "string" }, "ready": { "type": "string" }, "openapi": { "type": "string" }, "docs": { "type": "string" }, "sdk": { "type": "string" } } }, "resources": { "type": "object", "properties": { "passports": { "type": "string" }, "delegations": { "type": "string" }, "agents": { "type": "string" }, "marketplace": { "type": "string" }, "sessions": { "type": "string" } } }, "links": { "type": "object", "properties": { "website": { "type": "string" }, "console": { "type": "string" }, "status": { "type": "string" } } } } }, "examples": { "operational_status_example": { "summary": "Operational Status Example", "description": "An example where the HUMAN API is fully operational.", "value": { "name": "HUMΛN API", "description": "The trust layer between human decisions and machine execution.", "version": "v1", "status": "operational", "endpoints": { "health": "/health", "ready": "/ready", "openapi": "/v1/openapi.json", "docs": "https://builtwithhuman.com/api-reference", "sdk": "https://builtwithhuman.com/docs/sdk" }, "resources": { "passports": "/v1/passports", "delegations": "/v1/delegations", "agents": "/v1/agents", "marketplace": "/v1/marketplace", "sessions": "/v1/sessions" }, "links": { "website": "https://builtwithhuman.com", "console": "https://console.haio.run", "status": "https://status.builtwithhuman.com" } } } } } } }, "503": { "description": "The API is degraded due to database connectivity issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "degraded_status_example": { "summary": "Degraded Status Example", "description": "An example where the HUMAN API is degraded due to a database connectivity issue.", "value": { "type": "about:blank", "title": "Service Unavailable", "status": 503, "detail": "The HUMAN API is currently experiencing database connectivity issues, resulting in degraded service." } } } } } } } } }, "/v1/openapi.json": { "get": { "summary": "Fetch the HUMAN OpenAPI Specification", "description": "Unlock the full potential of HUMAN's protocol by accessing its OpenAPI specification. This endpoint serves as the key to understanding and integrating with HUMAN's complex orchestration of human and AI capabilities.", "operationId": "getOpenapiJson", "tags": [ "Documentation", "Integration" ], "x-code-hash": "07fd8911524bff53", "x-generated-at": "2026-03-24T21:26:14.948Z", "responses": { "200": { "description": "Successfully retrieves the OpenAPI specification in JSON format, allowing developers to explore and integrate with HUMAN's robust protocol.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "default": { "summary": "Example", "value": { "openapi": "3.0.1", "info": { "title": "HUMAN Protocol API", "version": "1.0.0" }, "paths": { "/v1/passport": { "get": { "summary": "Retrieve a Passport", "responses": { "200": { "description": "A JSON object representing a user's Passport." } } } } } } } } } } }, "404": { "description": "The requested OpenAPI specification could not be found. This might occur if the specification hasn't been generated.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/openapi-not-found", "title": "OpenAPI Specification Not Found", "status": 404, "detail": "The OpenAPI specification is missing. Please ensure that it has been generated by running 'pnpm openapi:generate'." } } } } } }, "503": { "description": "Service unavailable due to missing OpenAPI specification. This usually means the server couldn't find the specification file.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/service-unavailable", "title": "Service Unavailable", "status": 503, "detail": "OpenAPI spec not found. Run 'pnpm openapi:generate' to regenerate the specification." } } } } } } } } }, "/health/workers": { "get": { "summary": "Retrieve worker health and status overview", "description": "This endpoint provides a snapshot of the current health and status of workers within your HUMAN orchestration system. By accessing real-time connections to the Redis backend and queue statistics, you ensure seamless task execution and AI safety. This proactive insight helps maintain operational efficiency.", "operationId": "getHealthWorkers", "tags": [ "System Health", "Workers" ], "x-code-hash": "5cd6bf6ae4f78867", "x-generated-at": "2026-04-09T21:36:09.557Z", "responses": { "200": { "description": "A detailed status report of current workers and their associated queues.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redis": { "type": "object", "properties": { "extension_events": { "type": "string", "enum": [ "connected", "disconnected" ] }, "agent_execution": { "type": "string", "enum": [ "connected", "disconnected" ] } } }, "queues": { "type": "object", "additionalProperties": { "type": "object", "properties": { "taskCount": { "type": "integer", "description": "Number of tasks in the queue." }, "completedCount": { "type": "integer", "description": "Number of tasks successfully completed." } } } }, "workers": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of active worker instances." }, "instances": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the worker." }, "name": { "type": "string", "description": "Name of the worker instance." } } } } } }, "timestamp": { "type": "string", "format": "date-time", "description": "Time when the health check was performed." } } }, "examples": { "default": { "summary": "Example", "value": { "redis": { "extension_events": "connected", "agent_execution": "connected" }, "queues": { "invoiceProcessing": { "taskCount": 42, "completedCount": 100 } }, "workers": { "count": 3, "instances": [ { "id": "worker-123", "name": "invoice-processor-1" }, { "id": "worker-456", "name": "invoice-processor-2" } ] }, "timestamp": "2023-10-15T14:48:00.000Z" } } } } } }, "400": { "description": "Invalid parameters provided. Check your request for typos.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters are invalid due to incorrect syntax." } } } } } }, "401": { "description": "Authentication required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be logged in to access worker health status." } } } } } }, "403": { "description": "You do not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Your account lacks the necessary privileges to view worker health." } } } } } }, "404": { "description": "The requested health data was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "No worker health data available for the given query." } } } } } }, "500": { "description": "Internal server error encountered. Please try again later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/orgs/:orgDid/members": { "get": { "summary": "Retrieve paginated list of organization members", "description": "Discover who is part of your organization with this endpoint. It serves as a gateway to explore the human network within an organization, empowering you to manage and collaborate with your members effectively. This endpoint ensures that only authorized users can access information, maintaining privacy and data integrity.", "operationId": "getOrganizationMembers", "tags": [ "Organization", "Members" ], "x-code-hash": "05c717e512562093", "x-generated-at": "2026-03-27T15:31:26.985Z", "responses": { "200": { "description": "A paginated list of organization members, with their roles and status updates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier of the organization" }, "human_did": { "type": "string", "description": "Decentralized Identifier of the human member" }, "work_agent_did": { "type": "string", "description": "Decentralized Identifier of the work agent" }, "role": { "type": "string", "description": "Role of the member within the organization" }, "joined_at": { "type": "string", "format": "date-time", "description": "Timestamp when the member joined the organization" }, "terminated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the member was terminated, or null if active" }, "terminated_by": { "type": [ "string", "null" ], "description": "DID of the agent who terminated the member, if applicable" }, "termination_reason": { "type": [ "string", "null" ], "description": "Reason for termination, if applicable" } }, "required": [ "org_did", "human_did", "work_agent_did", "role", "joined_at" ] } }, "limit": { "type": "integer", "description": "Number of records returned in this page" }, "cursorField": { "type": "string", "description": "Field used for pagination cursor" } } }, "examples": { "successful_response_with_members": { "summary": "Successful response with members", "value": { "data": [ { "org_did": "org:acme-corp", "human_did": "human:john-doe", "work_agent_did": "agent:john-doe-agent", "role": "developer", "joined_at": "2023-01-15T08:00:00Z", "terminated_at": null, "terminated_by": null, "termination_reason": null } ], "limit": 10, "cursorField": "joined_at" } } } } } }, "400": { "description": "Bad request due to invalid status filter.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_status_parameter": { "summary": "Invalid status parameter", "value": { "type": "https://example.com/probs/invalid-status", "title": "Invalid request parameter", "status": 400, "detail": "Status must be 'active', 'terminated', or 'all'", "errors": [ { "field": "status", "code": "INVALID_VALUE", "message": "Status must be 'active', 'terminated', or 'all'", "expected": "'active' | 'terminated' | 'all'", "received": "inactive" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing delegation context", "value": { "type": "https://example.com/probs/missing-delegation", "title": "Authentication required", "status": 401, "detail": "Missing delegation context. Ensure your request includes valid authentication credentials." } } } } } }, "403": { "description": "Authorization error when attempting to access another organization's members.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_to_organization": { "summary": "Unauthorized access to organization", "value": { "type": "https://example.com/probs/unauthorized-org-access", "title": "Access forbidden", "status": 403, "detail": "You can only list members of your own organization. Check your organization DID and permissions." } } } } } }, "500": { "description": "Internal server error due to unexpected server-side issue.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support with incident ID: inc_1696988300000." } } } } } } } }, "post": { "summary": "Add member to organization", "description": "Empower your organization's growth by adding new members who bring diverse skills and expertise. This endpoint allows you to expand your team by securely adding individuals to your organization, ensuring that only authorized personnel can perform this task.", "operationId": "addOrganizationMember", "tags": [ "Organization", "Membership" ], "x-code-hash": "73cd5f72bc545f5e", "x-generated-at": "2026-03-27T15:31:49.480Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "human_did": { "type": "string", "description": "The Passport DID of the human being added" }, "role": { "type": "string", "description": "The role assigned to the new member within the organization" } }, "required": [ "human_did", "role" ] }, "examples": { "adding_a_senior_engineer": { "summary": "Adding a Senior Engineer", "description": "This example demonstrates adding a new member as a Senior Engineer to the organization.", "value": { "human_did": "did:human:123456", "role": "senior_engineer" } } } } } }, "responses": { "201": { "description": "The member was successfully added to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The DID of the organization" }, "human_did": { "type": "string", "description": "The Passport DID of the member" }, "work_agent_did": { "type": "string", "description": "The DID of the created work agent" }, "role": { "type": "string", "description": "The role assigned to the member" }, "joined_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the member joined" }, "terminated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp if the member was terminated" }, "terminated_by": { "type": [ "string", "null" ], "description": "Who terminated the member" }, "termination_reason": { "type": [ "string", "null" ], "description": "Reason for termination" } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:org:acme", "human_did": "did:human:123456", "work_agent_did": "did:agent:123456-work-acme", "role": "senior_engineer", "joined_at": "2023-10-05T14:48:00.000Z", "terminated_at": null, "terminated_by": null, "termination_reason": null } } } } } }, "400": { "description": "Request body is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/validation-error", "title": "Request body is not valid", "status": 400, "detail": "The request contains invalid fields", "errors": [ { "field": "human_did", "code": "REQUIRED_FIELD_MISSING", "message": "This field is required", "expected": "Passport DID (did:human:...)", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication credentials were missing or incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/authentication-error", "title": "Authentication Failed", "status": 401, "detail": "Missing delegation context. Ensure you have the correct credentials." } } } } } }, "403": { "description": "Authorization required to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/authorization-error", "title": "Authorization Denied", "status": 403, "detail": "You can only add members to your own organization. Check your permissions and try again." } } } } } }, "404": { "description": "The specified organization was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The organization with the provided DID does not exist. Verify the organization DID and try again." } } } } } }, "409": { "description": "The member is already part of this organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/conflict", "title": "Conflict", "status": 409, "detail": "This human is already a member of this organization." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1696510140000" } } } } } } } } }, "/v1/orgs/:orgDid/members/:humanDid": { "delete": { "summary": "Terminate a member's employment", "description": "In the intricate ballet of organizational management, there comes a time when a member must exit the stage. This endpoint gracefully orchestrates the termination of a member's employment within the HUMAN platform, ensuring proper documentation and provenance. It exists to maintain order and clarity in the dynamic interplay between human and AI roles.", "operationId": "terminateMember", "tags": [ "Organization", "Membership" ], "x-code-hash": "43c7af416ff3ca2e", "x-generated-at": "2026-03-27T15:32:09.786Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "A brief explanation for the termination" } }, "required": [] }, "examples": { "termination_with_cause": { "summary": "Termination with Cause", "description": "Provides a reason for the member's termination", "value": { "reason": "Position redundancy due to restructuring" } } } } } }, "responses": { "200": { "description": "Member successfully terminated with details of the termination", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier of the organization" }, "human_did": { "type": "string", "description": "Decentralized Identifier of the terminated member" }, "work_agent_did": { "type": "string", "description": "DID of the work agent associated with the member" }, "role": { "type": "string", "description": "Role of the member within the organization" }, "joined_at": { "type": "string", "format": "date-time", "description": "Timestamp when the member joined" }, "terminated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the member was terminated" }, "terminated_by": { "type": "string", "description": "DID of the entity that processed the termination" }, "termination_reason": { "type": "string", "description": "Reason provided for termination, if any" } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:org:acme", "human_did": "did:human:john_doe", "work_agent_did": "did:agent:agent123", "role": "Software Engineer", "joined_at": "2022-01-15T08:00:00Z", "terminated_at": "2023-10-10T09:00:00Z", "terminated_by": "did:agent:manager456", "termination_reason": "Position redundancy due to restructuring" } } } } } }, "400": { "description": "Invalid request due to malformed syntax", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body contains malformed JSON syntax.", "errors": [ "Ensure the JSON is correctly structured." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation context", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context. Include a valid delegation token in your request." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You can only terminate members of your own organization. Ensure your delegation matches the organization DID." } } } } } }, "404": { "description": "Member not found within the organization", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "Member with DID did:human:jane_doe not found in the organization." } } } } } }, "409": { "description": "Conflict due to member already being terminated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/conflict", "title": "Conflict", "status": 409, "detail": "This member has already been terminated.", "errors": [ "Check the termination status before attempting to terminate again." ] } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1609459200." } } } } } } } } }, "/v1/orgs/:did/profile": { "get": { "summary": "Retrieve an organization's profile information", "description": "Explore the digital tapestry of an organization’s identity with this endpoint. It unveils the public profile of an organization, including its unique cryptographic identity (DID), branding elements, and provenance data. This ensures transparency and trust in interactions, vital for seamless Human-AI collaboration.", "operationId": "getOrgProfile_1", "tags": [ "Organization", "Profile" ], "x-code-hash": "68c53fb5be89a6e3", "x-generated-at": "2026-03-27T15:32:37.910Z", "responses": { "200": { "description": "Successfully retrieved the organization's profile details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier for the organization" }, "display_name": { "type": "string", "description": "Public display name of the organization" }, "description": { "type": "string", "description": "Short description of the organization", "nullable": true }, "website_url": { "type": "string", "description": "URL to the organization's website", "nullable": true }, "logo_url": { "type": "string", "description": "URL to the organization's logo", "nullable": true }, "brand_tokens": { "type": "string", "description": "Unique branding tokens for the organization", "nullable": true }, "updated_by": { "type": "string", "description": "Identifier of the last updater", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of profile creation" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of last profile update" } }, "required": [ "org_did", "display_name", "created_at", "updated_at" ] }, "examples": { "acme_corp_profile": { "summary": "Acme Corp Profile", "description": "Retrieving the profile for the fictional Acme Corporation.", "value": { "org_did": "did:example:acme123", "display_name": "Acme Corporation", "description": "Leading provider of innovative solutions.", "website_url": "https://www.acme.com", "logo_url": "https://www.acme.com/logo.png", "brand_tokens": "acme2023", "updated_by": "did:example:agent456", "created_at": "2023-01-15T08:00:00Z", "updated_at": "2023-10-05T12:00:00Z" } } } } } }, "404": { "description": "The requested organization profile could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "org_did_not_found": { "summary": "Org DID Not Found", "description": "A request for a non-existent organization's profile results in a 404 error.", "value": { "type": "https://api.humanprotocol.org/problems/org-not-found", "title": "Organization Not Found", "status": 404, "detail": "The organization with DID 'did:example:unknown123' could not be located. Ensure the DID is correct and try again." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_connection_error": { "summary": "Database Connection Error", "description": "An unexpected issue with the database connection results in a 500 error.", "value": { "type": "https://api.humanprotocol.org/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the organization profile. Please try again later or contact support if the problem persists." } } } } } } } }, "patch": { "summary": "Update Organization Profile Details", "description": "This endpoint empowers organizations to maintain accurate and up-to-date profiles by allowing authenticated updates to their profile details. It ensures that only the rightful owner of the organization can modify its profile, safeguarding against unauthorized changes.", "operationId": "updateOrgProfile_1", "tags": [ "Organization", "Profile Management" ], "x-code-hash": "272294ef05d97e54", "x-generated-at": "2026-03-27T15:33:31.955Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "brand_tokens": { "type": [ "object", "null" ] } }, "anyOf": [ { "required": [ "display_name" ] }, { "required": [ "description" ] }, { "required": [ "website_url" ] }, { "required": [ "logo_url" ] }, { "required": [ "brand_tokens" ] } ] }, "examples": { "update_display_name": { "summary": "Update Display Name", "description": "This example demonstrates updating the display name of an organization.", "value": { "display_name": "Acme Corporation" } } } } } }, "responses": { "200": { "description": "Successfully updated organization profile with the new details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "brand_tokens": { "type": [ "object", "null" ] }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:example:123456789abcdefghi", "display_name": "Acme Corporation", "description": "Innovator in industry solutions", "website_url": "https://acme.example.com", "logo_url": "https://acme.example.com/logo.png", "brand_tokens": { "color": "blue" }, "updated_by": "did:example:agent12345", "created_at": "2023-01-01T12:00:00Z", "updated_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-json", "title": "Invalid JSON format", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "unparseable" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/missing-delegation", "title": "Authentication Error", "status": 401, "detail": "Missing delegation context. Ensure the request includes a valid delegation." } } } } } }, "403": { "description": "Forbidden action due to unauthorized profile update attempt.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized-profile-update", "title": "Authorization Error", "status": 403, "detail": "You can only update the profile of your own organization. Ensure you are authorized for org:profile:write." } } } } } }, "404": { "description": "Organization not found for the given DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/org-not-found", "title": "Not Found", "status": 404, "detail": "Organization profile not found for DID: did:example:123456789abcdefghi. Verify the DID and try again." } } } } } }, "500": { "description": "Internal server error during the update process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to update org profile due to a server issue. Please try again later." } } } } } } } } }, "/v1/orgs/:did/comms_settings": { "get": { "summary": "Retrieve organization communication settings", "description": "Dive into the communication preferences of an organization with this endpoint. Fetching these settings allows you to understand how the organization presents itself in communications, ensuring consistent messaging and proper routing of replies. This is crucial for maintaining a polished and professional external appearance.", "operationId": "getOrgCommsSettings_1", "tags": [ "Organizations", "Communication" ], "x-code-hash": "2946a6bb042e911a", "x-generated-at": "2026-03-27T15:32:54.579Z", "responses": { "200": { "description": "Successfully retrieved the communication settings for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The Decentralized Identifier (DID) of the organization." }, "send_mode": { "type": "string", "description": "The mode used for sending communications (e.g., 'batch', 'individual')." }, "from_display_name": { "type": "string", "description": "The display name used in the 'from' field of communications." }, "from_email": { "type": "string", "description": "The email address shown in the 'from' field." }, "reply_to_email": { "type": "string", "nullable": true, "description": "The email address to which replies are directed." }, "legal_footer": { "type": "string", "nullable": true, "description": "Legal text appended to communications." }, "updated_at": { "type": "string", "format": "date-time", "description": "The last time these settings were updated." } } }, "examples": { "acme_corporation": { "summary": "Acme Corporation", "description": "Communication settings for Acme Corporation, illustrating a typical setup.", "value": { "org_did": "did:human:acme123", "send_mode": "batch", "from_display_name": "Acme Support", "from_email": "support@acme.com", "reply_to_email": "noreply@acme.com", "legal_footer": "© 2023 Acme Corporation. All rights reserved.", "updated_at": "2023-09-15T14:00:00Z" } } } } } }, "400": { "description": "The request is malformed, possibly due to an invalid DID format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_did_format": { "summary": "Invalid DID Format", "value": { "type": "https://example.com/probs/invalid-did", "title": "Invalid DID Format", "status": 400, "detail": "The DID format is incorrect. Ensure the DID is a valid decentralized identifier." } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://example.com/probs/auth-required", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid. Please log in or provide valid credentials." } } } } } }, "403": { "description": "You do not have permission to access these settings.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You don't have permission to view these communication settings. Contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "The specified organization's communication settings could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "settings_not_found": { "summary": "Settings Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No communication settings found for the organization with DID 'did:human:unknown'. Please verify the organization DID." } } } } } }, "500": { "description": "An internal server error occurred while fetching the communication settings.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected condition was encountered. Our team has been notified and is working on a resolution." } } } } } } } } }, "/v1/marketplace/connectors/:id": { "get": { "summary": "Retrieve detailed connector information", "description": "Dive into the rich details of any public connector available on the HUMAN marketplace. This endpoint allows you to explore the capabilities and statistics of connectors, empowering informed decisions about integration and usage.", "operationId": "getMarketplaceConnectorById", "tags": [ "Marketplace", "Connectors" ], "x-code-hash": "2b7572dbdaf9850d", "x-generated-at": "2026-03-24T21:28:59.741Z", "responses": { "200": { "description": "Successfully retrieved connector details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connector_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "description": { "type": "string" }, "long_description": { "type": "string" }, "icon_url": { "type": "string" }, "version": { "type": "string" }, "publisher": { "type": "object", "properties": { "publisher_id": { "type": "string" }, "name": { "type": "string" }, "verified": { "type": "boolean" } } }, "certified": { "type": "boolean" }, "pricing_model": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "oauth": { "type": "object", "properties": { "required": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "authorization_url": { "type": "string" }, "token_url": { "type": "string" } } }, "deployment_modes": { "type": "array", "items": { "type": "string" } }, "configuration_schema": { "type": "object", "properties": {} }, "health_status": { "type": "string" }, "last_health_check_at": { "type": [ "string", "null" ], "format": "date-time" }, "statistics": { "type": "object", "properties": { "install_count": { "type": "integer" }, "rating_average": { "type": [ "number", "null" ] }, "rating_count": { "type": "integer" }, "invocation_count_30d": { "type": "integer" } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "examples": { "successful_connector_retrieval": { "summary": "Successful Connector Retrieval", "value": { "connector_id": "b7d2e9f1", "name": "Invoice Processor", "provider": "Acme Corp", "description": "Automates invoice processing tasks", "long_description": "The Invoice Processor streamlines the handling of invoices by leveraging AI to ensure accuracy and speed.", "icon_url": "https://example.com/icons/invoice-processor.png", "version": "1.4.2", "publisher": { "publisher_id": "acme", "name": "Acme Corp", "verified": true }, "certified": true, "pricing_model": "subscription", "capabilities": [ "invoicing", "ocr", "integration" ], "oauth": { "required": true, "scopes": [ "invoices.read", "invoices.write" ], "authorization_url": "https://auth.acme.com/oauth/authorize", "token_url": "https://auth.acme.com/oauth/token" }, "deployment_modes": [ "cloud", "on-premise" ], "configuration_schema": { "type": "object", "properties": {} }, "health_status": "healthy", "last_health_check_at": "2023-10-01T12:00:00Z", "statistics": { "install_count": 1345, "rating_average": 4.5, "rating_count": 102, "invocation_count_30d": 523 }, "created_at": "2022-06-15T08:30:00Z", "updated_at": "2023-09-10T14:45:00Z" } } } } } }, "400": { "description": "Bad Request due to invalid connector ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_connector_id": { "summary": "Invalid Connector ID", "value": { "type": "https://humanprotocol.org/errors/invalid-parameter", "title": "Invalid Request", "status": 400, "detail": "The provided connector ID is invalid. Please check the ID and try again.", "errors": [ "connector_id must be a valid UUID." ] } } } } } }, "404": { "description": "Connector not found or is not publicly visible.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_not_found": { "summary": "Connector Not Found", "value": { "type": "https://humanprotocol.org/errors/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "No connector found with the specified ID, or it is not publicly visible. Please verify the connector ID and its visibility." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/marketplace/connectors/:id/install": { "post": { "summary": "Install a Connector for Organization", "description": "In the HUMAN ecosystem, connectors are bridges that allow organizations to integrate external services seamlessly. This endpoint empowers your organization to install a connector, ensuring a smooth flow of operations across platforms. The installation process is authenticated via a Passport delegation token, safeguarding your organization's integrity.", "operationId": "installConnector", "tags": [ "Marketplace", "Connectors" ], "x-code-hash": "16404e588589b46e", "x-generated-at": "2026-04-30T20:06:17.476Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment_mode": { "type": "string", "enum": [ "cloud", "hybrid", "self-hosted" ], "description": "The mode in which the connector will be deployed." }, "granted_permissions": { "type": "array", "items": { "type": "string" }, "description": "A list of permissions the connector is granted upon installation." }, "config": { "type": "object", "additionalProperties": true, "description": "Optional configuration settings specific to the connector." } }, "required": [ "deployment_mode", "granted_permissions" ] }, "examples": { "install_cloud_connector": { "summary": "Install Cloud Connector", "description": "This example demonstrates installing a connector with cloud deployment mode and specific permissions.", "value": { "deployment_mode": "cloud", "granted_permissions": [ "read_data", "write_data" ], "config": { "endpoint": "https://api.example.com", "api_key": "securekey123" } } } } } } }, "responses": { "201": { "description": "Connector successfully installed, pending OAuth if required.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "installation_id": { "type": "string", "description": "The unique identifier for the connector installation." }, "connector_id": { "type": "string", "description": "The identifier of the connector being installed." }, "status": { "type": "string", "enum": [ "active" ], "description": "The status of the installation." }, "installed_at": { "type": "string", "format": "date-time", "description": "The timestamp when the connector was installed." } } }, { "type": "object", "properties": { "installation_id": { "type": "string", "description": "The unique identifier for the connector installation." }, "connector_id": { "type": "string", "description": "The identifier of the connector being installed." }, "status": { "type": "string", "enum": [ "pending_oauth" ], "description": "The status of the installation, indicating OAuth authorization is pending." }, "oauth_authorization_url": { "type": "string", "format": "uri", "description": "The URL where the user can authorize the OAuth application." }, "oauth_state": { "type": "string", "description": "The state parameter used in OAuth for request validation." }, "redirect_uri": { "type": "string", "format": "uri", "description": "The URI to redirect to after OAuth authorization." }, "expires_at": { "type": "string", "format": "date-time", "description": "The timestamp when the OAuth authorization will expire." } } } ] }, "examples": { "active_installation": { "summary": "Active Installation", "description": "An example response when a connector is installed and active.", "value": { "installation_id": "install_123456", "connector_id": "connector_7890", "status": "active", "installed_at": "2023-10-15T12:00:00Z" } }, "pending_oauth_installation": { "summary": "Pending OAuth Installation", "description": "An example response when a connector installation is pending OAuth authorization.", "value": { "installation_id": "install_123456", "connector_id": "connector_7890", "status": "pending_oauth", "oauth_authorization_url": "https://auth.example.com/authorize", "oauth_state": "state_abc123", "redirect_uri": "https://example.com/v1/oauth/callback", "expires_at": "2023-10-15T12:15:00Z" } } } } } }, "400": { "description": "The request was invalid and could not be understood by the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_deployment_mode": { "summary": "Missing Deployment Mode", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body is missing required fields.", "errors": [ { "field": "deployment_mode", "code": "REQUIRED_FIELD_MISSING", "message": "deployment_mode is required", "expected": "cloud | hybrid | self-hosted", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation token required." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to install connectors in this organization." } } } } } }, "404": { "description": "The specified connector could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_not_found": { "summary": "Connector Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Connector 'connector_7890' not found." } } } } } }, "409": { "description": "Conflict due to the connector already being installed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_already_installed": { "summary": "Connector Already Installed", "value": { "type": "https://example.com/probs/conflict", "title": "Conflict", "status": 409, "detail": "Connector 'connector_7890' is already installed." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/marketplace/connectors/:id/uninstall": { "post": { "summary": "Uninstall a marketplace connector", "description": "This endpoint allows you to seamlessly remove a connector from your organization's ecosystem, ensuring that only relevant tools remain active. By managing your connectors effectively, you maintain a streamlined and secure operational environment, fostering both innovation and governance.", "operationId": "uninstallMarketplaceConnector", "tags": [ "Marketplace", "Connectors" ], "x-code-hash": "100da0fa8258aa3c", "x-generated-at": "2026-03-24T21:29:53.402Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "The unique identifier of the entity within the organization." } }, "required": [] }, "examples": { "uninstall_from_specific_entity": { "summary": "Uninstall from specific entity", "description": "Uninstalls a connector for the 'acme' organization.", "value": { "entity_id": "acme-organization-123" } } } } } }, "responses": { "200": { "description": "Connector successfully uninstalled from the specified entity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connector_id": { "type": "string", "description": "The ID of the connector that was uninstalled." }, "status": { "type": "string", "enum": [ "uninstalled" ], "description": "The current status of the connector." }, "uninstalled_at": { "type": "string", "format": "date-time", "description": "The timestamp when the connector was uninstalled." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid input or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The entity_id provided is not valid.", "errors": [ "entity_id must be a valid string." ] } } } } } }, "401": { "description": "Authentication is required to uninstall a connector.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation token required. Please include a valid token." } } } } } }, "403": { "description": "You do not have permission to uninstall this connector.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have the required permissions to uninstall this connector." } } } } } }, "404": { "description": "The specified connector or entity was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "Connector with ID 'connector-456' was not found." } } } } } }, "500": { "description": "An internal server error occurred while attempting to uninstall the connector.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1696519200." } } } } } } } } }, "/v1/marketplace/connectors/publish": { "post": { "summary": "Publish a connector to the marketplace", "description": "In the HUMAN ecosystem, publishing a connector is more than just uploading code—it's about establishing a trusted identity and sharing innovations with the world. This endpoint allows verified developers to publish their connectors, ensuring that their creations carry their identity and reputation across the HUMAN network. With a focus on integrity and security, published connectors must meet identity verification standards, ensuring that every contribution is backed by a real person.", "operationId": "publishMarketplaceConnector", "tags": [ "Marketplace", "Connectors" ], "x-code-hash": "589ad8c542e41540", "x-generated-at": "2026-04-02T13:28:55.022Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connector_id": { "type": "string", "description": "Unique identifier for the connector" }, "name": { "type": "string", "description": "Human-readable name of the connector", "example": "acme-invoice-processor" }, "description": { "type": "string", "description": "Detailed description of the connector's functionality" }, "version": { "type": "string", "description": "Semantic version of the connector", "example": "1.0.0" }, "manifest": { "type": "object", "description": "Connector manifest details", "additionalProperties": true }, "handles_sensitive_data": { "type": "boolean", "description": "Indicates if the connector handles sensitive data" }, "pricing_model": { "type": "string", "enum": [ "free", "paid", "freemium" ], "description": "The pricing model for the connector" }, "deployment_modes": { "type": "array", "items": { "type": "string", "enum": [ "cloud", "hybrid", "self-hosted" ] }, "description": "Supported deployment modes" } }, "required": [ "name", "version" ] }, "examples": { "basic_connector_publication": { "summary": "Basic Connector Publication", "description": "Publishing a simple connector with a free pricing model and cloud deployment.", "value": { "name": "acme-invoice-processor", "version": "1.0.0", "description": "Processes invoices for the Acme organization", "manifest": { "provider": "Acme Corp" }, "pricing_model": "free", "deployment_modes": [ "cloud" ] } } } } } }, "responses": { "201": { "description": "Connector successfully published", "content": { "application/json": { "schema": { "type": "object", "properties": { "publish_id": { "type": "string", "description": "Unique publish identifier" }, "status": { "type": "string", "description": "Status of the publication", "example": "published" }, "publisher_did": { "type": "string", "description": "Decentralized identifier of the publisher" }, "connector_id": { "type": "string", "description": "Unique identifier of the connector" }, "name": { "type": "string", "description": "Name of the connector" }, "version": { "type": "string", "description": "Version of the connector" }, "message": { "type": "string", "description": "Success message" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of creation" } } }, "examples": { "default": { "summary": "Example", "value": { "publish_id": "pub-123456", "status": "published", "publisher_did": "did:human:1234abcd", "connector_id": "acme-invoice-processor", "name": "Acme Invoice Processor", "version": "1.0.0", "message": "You're verified. Your published work carries your identity — it's your reputation, portable and permanent.", "created_at": "2023-10-12T07:20:50.52Z" } } } } } }, "400": { "description": "Bad Request - Validation errors", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Validation failed for one or more fields.", "errors": [ { "field": "name", "code": "REQUIRED_FIELD_MISSING", "message": "Connector name is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized - Delegation token required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation token required for authentication." } } } } } }, "403": { "description": "Forbidden - Insufficient verification level", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Insufficient identity verification level. Identity Tier 1 is required." } } } } } }, "500": { "description": "Internal Server Error - Unexpected issue", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/marketplace/connectors/gates": { "get": { "summary": "Retrieve the Natural Gate Map", "description": "In your journey through the HUMAN ecosystem, understanding the access gates is crucial. This endpoint unveils the natural gate map, illustrating which capabilities demand specific verification levels. It's designed to empower frontends with the intelligence to guide users smoothly through their tasks, ensuring they are prepared before encountering a gate.", "operationId": "getMarketplaceGates", "tags": [ "Marketplace", "Gates" ], "x-code-hash": "aa0308604d839468", "x-generated-at": "2026-03-24T21:30:38.413Z", "responses": { "200": { "description": "Successfully retrieved the gate map, detailing each gate's requirements and messaging theme.", "content": { "application/json": { "schema": { "type": "object", "properties": { "gates": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "required_layer": { "type": "integer" }, "required_identity_tier": { "type": "integer" }, "message_theme": { "type": "string" }, "description": { "type": "string" } }, "required": [ "action", "required_layer", "required_identity_tier", "message_theme", "description" ] } } }, "required": [ "gates" ] }, "examples": { "example_gate_map": { "summary": "Example Gate Map", "description": "A snapshot of various gates including actions and their requirements.", "value": { "gates": [ { "action": "companion.basic", "required_layer": 1, "required_identity_tier": 0, "message_theme": "Just works", "description": "Use the Companion for basic interactions" }, { "action": "marketplace.publish", "required_layer": 1, "required_identity_tier": 1, "message_theme": "Accountability for shared code", "description": "Publish connectors and agents to the marketplace" }, { "action": "workforce.premium", "required_layer": 2, "required_identity_tier": 1, "message_theme": "High-value tasks need higher trust", "description": "Access premium workforce tasks" } ] } } } } } }, "400": { "description": "Request was malformed or invalid; check syntax and parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request_example": { "summary": "Invalid Request Example", "description": "Example of an invalid request due to incorrect parameters.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The parameters provided were not valid. Please refer to the documentation.", "errors": [ "Parameter 'x' is missing", "Parameter 'y' is invalid" ] } } } } } }, "401": { "description": "Authentication is required and has failed or not been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_request_example": { "summary": "Unauthenticated Request Example", "description": "Example of a response when authentication credentials are missing.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must authenticate to access this resource. Please provide valid credentials." } } } } } }, "403": { "description": "You do not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Example response when the user lacks the necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource. Please contact support if you believe this is an error." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "description": "Example when the requested resource is unavailable.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The resource you are looking for could not be found. Please check the endpoint and try again." } } } } } }, "500": { "description": "The server encountered an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "Example when the server fails to process the request due to an internal error.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/marketplace/review": { "post": { "summary": "Automate Marketplace Review Process", "description": "Embark on a journey to ensure your marketplace listings meet HUMAN platform standards through automated checks. This endpoint not only verifies your agent's installation manifest but also assesses eligibility for the prestigious Autonomous badge. This pre-submission tool is your ally in maintaining high-quality entries.", "operationId": "postMarketplaceReview", "tags": [ "Marketplace", "Review" ], "x-code-hash": "7660f361d7aee8dc", "x-generated-at": "2026-03-26T16:01:42.769Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Unique identifier for the agent" }, "manifest": { "type": "object", "description": "Agent's installation manifest", "properties": { "autonomous_eligible": { "type": "boolean", "description": "Eligibility for autonomous operations" }, "learning_contract": { "type": "object", "description": "Learning contract details" } }, "required": [ "autonomous_eligible" ] }, "openapi_spec": { "type": "object", "description": "OpenAPI specification for the agent" }, "request_badge": { "type": "boolean", "description": "Flag to request Autonomous badge check" } }, "required": [ "agent_id", "manifest" ] }, "examples": { "standard_agent_review": { "summary": "Standard Agent Review", "description": "Reviewing a standard agent's manifest with a request for an Autonomous badge.", "value": { "agent_id": "agent_12345", "manifest": { "autonomous_eligible": true, "learning_contract": { "terms": "Agreed" } }, "openapi_spec": { "info": { "title": "Sample API", "version": "1.0.0" } }, "request_badge": true } } } } } }, "responses": { "200": { "description": "Successfully processed the review and returned results", "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": "object", "description": "Results of the review checks" }, "badge": { "type": "object", "description": "Details of the Autonomous badge, if applicable" } } }, "examples": { "default": { "summary": "Example", "value": { "review": { "checks_passed": 13, "warnings": [] }, "badge": { "status": "granted", "badge_id": "badge_6789" } } } } } } }, "400": { "description": "Invalid request due to malformed syntax", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/validation-error", "title": "Invalid Request", "status": 400, "detail": "Request body is required", "errors": [ { "field": "body", "code": "REQUIRED_FIELD_MISSING", "message": "Request body is required", "expected": "object", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with the incident ID." } } } } } } } } }, "/v1/marketplace/submit": { "post": { "summary": "Submit a new marketplace listing", "description": "The marketplace submission endpoint is your gateway to showcasing your AI's capabilities to the world. Here, you validate your submission, undergo a rigorous automated review, and, if successful, enter the submission queue. This ensures only the best and most compliant agents make it to the HUMAN platform.", "operationId": "submitMarketplaceListing", "tags": [ "Marketplace", "AI Submission" ], "x-code-hash": "49ceef210bb59adf", "x-generated-at": "2026-04-02T13:29:11.279Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "A unique identifier for the submitting agent." }, "publisher_did": { "type": "string", "description": "The decentralized identifier (DID) of the publisher." }, "manifest": { "type": "object", "description": "The detailed manifest of the agent, conforming to the InstallManifest schema." }, "openapi_spec": { "type": "object", "description": "An optional OpenAPI specification for the agent." } }, "required": [ "agent_id", "publisher_did", "manifest" ] }, "examples": { "acme_corp_submission": { "summary": "Acme Corp Submission", "description": "A submission by Acme Corp for their invoice processing AI agent.", "value": { "agent_id": "acme-invoice-processor", "publisher_did": "did:example:acme123", "manifest": { "name": "Acme Invoice Processor", "version": "1.0.0", "description": "Processes invoices with AI precision." }, "openapi_spec": { "info": { "title": "Acme Invoice Processor API", "version": "1.0.0" }, "paths": {} } } } } } } }, "responses": { "202": { "description": "Submission accepted and queued for review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "submission_id": { "type": "string", "description": "A unique identifier for the submission." }, "agent_id": { "type": "string", "description": "The agent ID of the submitted listing." }, "status": { "type": "string", "enum": [ "review_pending" ], "description": "The current status of the submission." }, "review_eta_seconds": { "type": "integer", "description": "Estimated time in seconds until review completion." }, "review_report_url": { "type": "string", "description": "URL to access the review report." } } }, "examples": { "default": { "summary": "Example" } } } } }, "422": { "description": "Validation errors occurred during submission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/marketplace-review-failed", "title": "Automated Review Failed", "status": 422, "detail": "The submission failed 3 checks.", "review_report": { "failCount": 3, "issues": [ "Invalid manifest format", "Missing required fields", "Non-compliant API endpoints" ] }, "remediation": [ { "step": 1, "description": "Fix the 3 failing check(s) listed in the review_report." }, { "step": 2, "description": "Re-run POST /v1/marketplace/review to verify your fixes before resubmitting.", "link": "/v1/marketplace/review" } ] } } } } } }, "500": { "description": "Internal server error encountered during submission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later.", "incidentId": "inc_1698412345678" } } } } } } } } }, "/v1/marketplace/connectors/:id/ratings": { "post": { "summary": "Submit a rating for a marketplace connector", "description": "In the vibrant ecosystem of HUMAN's marketplace, connectors are the lifeblood that enable seamless integration. This endpoint empowers users to express their satisfaction or critique by rating connectors they have installed. A rating not only influences the connector's reputation but also guides future users in their decision-making process.", "operationId": "rateConnector_1", "tags": [ "Marketplace", "Connectors" ], "x-code-hash": "21975e231142323b", "x-generated-at": "2026-03-24T21:31:34.213Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "integer", "description": "The rating score given to the connector, must be between 1 and 5.", "minimum": 1, "maximum": 5 }, "installation_id": { "type": "string", "description": "The unique identifier of the connector installation being rated." }, "review_text": { "type": "string", "description": "An optional textual review providing more context about the rating." } }, "required": [ "rating", "installation_id" ] }, "examples": { "acme_corp_connector_rating": { "summary": "Acme Corp Connector Rating", "description": "A rating example where Acme Corp rates a connector they use for invoice processing.", "value": { "rating": 4, "installation_id": "inst_12345", "review_text": "The connector works well but could use more features." } } } } } }, "responses": { "200": { "description": "Rating updated successfully. This response indicates that an existing rating has been updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rating_id": { "type": "string" }, "connector_id": { "type": "string" }, "rating": { "type": "integer" }, "review_text": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example", "value": { "rating_id": "rat_67890", "connector_id": "con_54321", "rating": 4, "review_text": "The connector works well but could use more features.", "updated_at": "2023-10-05T14:48:00.000Z" } } } } } }, "201": { "description": "Rating created successfully. This response indicates that a new rating has been created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rating_id": { "type": "string" }, "connector_id": { "type": "string" }, "rating": { "type": "integer" }, "review_text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example", "value": { "rating_id": "rat_67891", "connector_id": "con_54321", "rating": 5, "review_text": "Exceptional performance and reliability!", "created_at": "2023-10-05T14:50:00.000Z" } } } } } }, "400": { "description": "Invalid input. The request contains one or more invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/invalid-input", "title": "Invalid input", "status": 400, "detail": "The request contains invalid input fields.", "errors": [ { "field": "rating", "code": "INVALID_RATING", "message": "Rating must be between 1 and 5", "expected": "number (1-5)", "received": "6" } ] } } } } } }, "401": { "description": "Unauthorized. The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation token required to rate connectors." } } } } } }, "403": { "description": "Forbidden. The user does not have permission to rate this connector.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "Installation does not belong to your organization or account." } } } } } }, "404": { "description": "Not Found. The specified connector or installation was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/not-found", "title": "Not Found", "status": 404, "detail": "Connector not found for ID 'con_54321'." } } } } } }, "500": { "description": "Internal Server Error. An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve ratings for a specific connector", "description": "Explore the diverse perspectives of users by accessing ratings for any given connector on the HUMAN marketplace. This endpoint offers a glimpse into the community's feedback, essential for refining and optimizing AI-human collaboration tools. Dive into the data to understand the connector's performance and user satisfaction, while contributing to an open ecosystem of trust and innovation.", "operationId": "getConnectorRatings_1", "tags": [ "Marketplace", "Connectors" ], "x-code-hash": "1fdb59d522817185", "x-generated-at": "2026-03-24T21:31:48.437Z", "responses": { "200": { "description": "Successfully retrieved the ratings and summary statistics for the specified connector.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "rating_id": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "review_text": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "user_id": { "type": "string" }, "display_name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "summary": { "type": "object", "properties": { "average": { "type": "number", "format": "float" }, "count": { "type": "integer" }, "distribution": { "type": "object", "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } } } } } } }, "examples": { "sample_connector_ratings": { "summary": "Sample Connector Ratings", "description": "Ratings for connector showing user feedback and summary statistics.", "value": { "data": [ { "rating_id": "abc123", "rating": 5, "review_text": "Exceptional tool for automation!", "user": { "user_id": "user789", "display_name": "Anonymous" }, "created_at": "2023-10-01T12:34:56Z", "updated_at": "2023-10-02T13:45:00Z" } ], "has_more": false, "next_cursor": null, "summary": { "average": 4.8, "count": 150, "distribution": { "1": 2, "2": 3, "3": 5, "4": 20, "5": 120 } } } } } } } }, "400": { "description": "Returned when the request contains invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid cursor", "status": 400, "detail": "The cursor parameter is invalid or malformed." } } } } } }, "404": { "description": "Returned when the specified connector does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_not_found": { "summary": "Connector Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Connector not found", "status": 404, "detail": "The connector with ID 'connector123' does not exist." } } } } } }, "500": { "description": "Returned when an unexpected error occurs on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/connectors/installations/:id": { "patch": { "summary": "Update Connector Installation Details", "description": "This endpoint allows organizations to update the configuration or status of a specific connector installation. By enabling such updates, organizations can ensure their integrations remain effective and responsive to changing business needs.", "operationId": "updateConnectorInstallation", "tags": [ "Connectors", "Installations" ], "x-code-hash": "61b28bda195018d3", "x-generated-at": "2026-03-24T21:32:07.333Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "suspended" ], "description": "The desired status for the installation." }, "config": { "type": "object", "description": "The configuration settings for the installation." } }, "required": [] }, "examples": { "update_installation_status": { "summary": "Update Installation Status", "description": "This example demonstrates updating an installation's status to 'active'.", "value": { "status": "active" } }, "update_installation_configuration": { "summary": "Update Installation Configuration", "description": "This example shows updating the connector's configuration settings.", "value": { "config": { "endpoint": "https://api.acme.com/v2", "retry_policy": "aggressive" } } } } } } }, "responses": { "200": { "description": "The connector installation was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "installation_id": { "type": "string", "description": "The unique identifier of the updated installation." }, "status": { "type": "string", "description": "The current status of the installation." }, "config": { "type": "object", "description": "The updated configuration of the installation." }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp of when the installation was updated." } } }, "examples": { "successful_update_response": { "summary": "Successful Update Response", "value": { "installation_id": "install-12345", "status": "active", "config": { "endpoint": "https://api.acme.com/v2", "retry_policy": "aggressive" }, "updated_at": "2023-10-01T14:48:00.000Z" } } } } } }, "400": { "description": "The request was invalid due to incorrect input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_status_value": { "summary": "Invalid Status Value", "value": { "type": "/errors/validation", "title": "Bad Request", "status": 400, "detail": "Invalid field values.", "errors": [ { "field": "status", "message": "Status must be active or suspended" } ] } } } } } }, "401": { "description": "Authentication failed due to a missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "value": { "type": "/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Delegation token required." } } } } } }, "403": { "description": "Access to the installation is forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Access denied to the resource." } } } } } }, "404": { "description": "The specified installation could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "installation_not_found": { "summary": "Installation Not Found", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Installation not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred." } } } } } } } } }, "/v1/connectors/installations/:id/usage": { "get": { "summary": "Retrieve Installation Usage Statistics", "description": "Uncover the journey of your connector's performance over the last 30 days. This endpoint provides an insightful peek into the success, challenges, and costs associated with your installations, ensuring you have the information needed to optimize your operations.", "operationId": "getInstallationUsage_1", "tags": [ "Connectors", "Usage" ], "x-code-hash": "d39abeee855e924d", "x-generated-at": "2026-03-24T21:32:24.084Z", "responses": { "200": { "description": "Successfully retrieved usage statistics for the specified installation, detailing invocation counts, costs, and daily breakdowns.", "content": { "application/json": { "schema": { "type": "object", "properties": { "installation_id": { "type": "string" }, "connector_id": { "type": "string" }, "period": { "type": "string", "example": "30d" }, "statistics": { "type": "object", "properties": { "total_invocations": { "type": "integer" }, "successful_invocations": { "type": "integer" }, "failed_invocations": { "type": "integer" }, "average_duration_ms": { "type": "number" }, "total_cost_usd": { "type": "number" }, "last_invocation_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "daily_breakdown": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "invocations": { "type": "integer" }, "cost_usd": { "type": "number" } } } } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request parameters, such as malformed installation ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The installation ID provided is malformed.", "errors": [ "Ensure the installation ID follows the expected format." ] } } } } } }, "401": { "description": "Missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication", "title": "Authentication Required", "status": 401, "detail": "A valid delegation token is required. Please ensure your token is correct and try again." } } } } } }, "403": { "description": "Access denied due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access usage statistics for this installation. Please contact your administrator." } } } } } }, "404": { "description": "Installation not found or does not belong to your organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No installation found with the provided ID. Please verify the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID inc_1696512000." } } } } } } } } }, "/v1/connectors/:connectorId/credentials": { "post": { "summary": "Store connector credentials securely", "description": "This endpoint empowers organizations by securely storing credentials for connectors, ensuring proper authentication and authorization. It is crucial for maintaining seamless integration and automated workflows across varied systems, embodying the dynamic nature of modern orchestration.", "operationId": "storeConnectorCredentials", "tags": [ "Connectors", "Credentials" ], "x-code-hash": "b358d80440498b7f", "x-generated-at": "2026-03-30T18:00:17.169Z", "responses": { "201": { "description": "Credential successfully stored, returning the credential details.", "content": { "application/json": {} } }, "400": { "description": "Bad Request due to validation errors. The response details the specific issues found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden due to lack of necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Connector not found with the specified identifier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error due to unexpected issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "summary": "Retrieve Decrypted Connector Credentials", "description": "Unlock the power of seamless integration by retrieving decrypted credentials for a specified connector. This endpoint ensures that entities can securely access credentials, enabling the orchestration of tasks without compromising security. By tailoring retrieval to specific scopes, it maximizes flexibility while maintaining stringent control over sensitive data.", "operationId": "getConnectorCredentials", "tags": [ "Connectors", "Credentials" ], "x-code-hash": "8fbc2030a17f0626", "x-generated-at": "2026-03-24T21:33:09.408Z", "responses": { "200": { "description": "Credentials retrieved successfully, providing decrypted information for the specified connector.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "properties": { "id": { "type": "string" }, "connector_id": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "type": "string" }, "scope": { "type": "string" }, "agent_id": { "type": "string" }, "instance_id": { "type": "string" }, "label": { "type": "string" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "last_used_at": { "type": "string", "format": "date-time" }, "last_used_by": { "type": "string" }, "use_count": { "type": "integer" } }, "required": [ "id", "connector_id", "entity_id", "created_by", "created_at", "updated_at", "status" ] }, "decrypted_credentials": { "type": "object" } }, "required": [ "credential", "decrypted_credentials" ] }, "examples": { "successful_credential_retrieval": { "summary": "Successful Credential Retrieval", "description": "A successful response showing decrypted credentials for the 'acme' organization connector.", "value": { "credential": { "id": "cred-123", "connector_id": "con-456", "entity_id": "org-acme", "entity_type": "organization", "scope": "org", "agent_id": "agt-jane", "instance_id": "inst-789", "label": "Acme Connector", "created_by": "did:human:creator", "created_at": "2023-02-20T12:00:00Z", "updated_at": "2023-03-01T12:00:00Z", "expires_at": "2024-02-20T12:00:00Z", "status": "active", "last_used_at": "2023-03-05T15:30:00Z", "last_used_by": "did:human:agent:agt-jane", "use_count": 42 }, "decrypted_credentials": { "api_key": "supersecretapikey", "api_secret": "supersecretapisecret" } } } } } } }, "400": { "description": "Invalid request due to missing or incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_entity_id": { "summary": "Missing entity_id", "description": "Attempt to retrieve credentials without specifying entity_id.", "value": { "type": "https://humanprotocol.org/errors/validation", "title": "Validation Error", "status": 400, "detail": "One or more fields are invalid.", "errors": [ { "field": "entity_id", "code": "REQUIRED_FIELD_MISSING", "message": "entity_id query parameter is required" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_token": { "summary": "Missing Passport Token", "description": "Access attempt without providing a valid Passport token.", "value": { "type": "https://humanprotocol.org/errors/authentication", "title": "Authentication Error", "status": 401, "detail": "Authentication required. Provide a valid Passport delegation token." } } } } } }, "403": { "description": "Forbidden access as the entity lacks necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Access attempt by an unauthorized entity.", "value": { "type": "https://humanprotocol.org/errors/authorization", "title": "Authorization Error", "status": 403, "detail": "You do not have permission to access credentials for this entity." } } } } } }, "404": { "description": "Connector or credentials not found for the given parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_not_found": { "summary": "Connector Not Found", "description": "Attempt to retrieve credentials for a non-existent connector.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "No credentials found for connector ID 'con-456'." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A server error occurred during credential retrieval.", "value": { "type": "https://humanprotocol.org/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/connectors/:connectorId/credentials/list": { "get": { "summary": "Retrieve Credential List for Connector", "description": "Unearth the hidden troves of credentials tied to a specific connector, a crucial step in managing your entity's digital keys. This endpoint allows the secure listing of credentials, providing transparency and control over who can access and perform operations within your system.", "operationId": "listConnectorCredentials", "tags": [ "Credentials", "Connectors" ], "x-code-hash": "78f4d3c38d6ade61", "x-generated-at": "2026-03-24T21:33:31.818Z", "responses": { "200": { "description": "A successful retrieval of credentials associated with the specified connector.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connector_id": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "type": "string" }, "scope": { "type": "string" }, "agent_id": { "type": "string" }, "instance_id": { "type": "string" }, "label": { "type": "string" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "last_used_at": { "type": "string", "format": "date-time" }, "last_used_by": { "type": "string" }, "use_count": { "type": "integer" } } } }, "count": { "type": "integer" } } }, "examples": { "list_of_credentials": { "summary": "List of Credentials", "description": "An example of credentials retrieved for a specific connector.", "value": { "credentials": [ { "id": "cred-123456", "connector_id": "connector-abc123", "entity_id": "entity-7890", "entity_type": "organization", "scope": "read:invoices", "agent_id": "agent-jdoe", "instance_id": "instance-x1", "label": "Finance Department Access", "created_by": "admin", "created_at": "2023-10-01T12:34:56Z", "updated_at": "2023-10-15T12:34:56Z", "expires_at": "2024-01-01T00:00:00Z", "status": "active", "last_used_at": "2023-10-20T08:00:00Z", "last_used_by": "agent-jdoe", "use_count": 42 } ], "count": 1 } } } } } }, "400": { "description": "The request is malformed or missing required query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_entity_id": { "summary": "Missing entity_id", "description": "Example of a response when the entity_id query parameter is missing.", "value": { "type": "https://humanprotocol.org/errors/missing-field", "title": "Bad Request", "status": 400, "detail": "entity_id query parameter is required.", "errors": [ { "field": "entity_id", "code": "REQUIRED_FIELD_MISSING", "message": "entity_id query parameter is required" } ] } } } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_passport": { "summary": "Invalid Passport", "description": "Example when the Passport authentication token is missing or invalid.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport token is invalid or not provided. Ensure your request includes a valid Passport token." } } } } } }, "403": { "description": "The user does not have permission to access the requested entity.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "Example when the user lacks permission to list credentials for the entity.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this entity's credentials. Verify your access rights and try again." } } } } } }, "404": { "description": "The specified connector or entity was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_not_found": { "summary": "Connector Not Found", "description": "Example when the connector ID does not exist.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified connector ID does not exist. Verify the connector ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Example when the server encounters an unexpected condition.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "The server encountered an unexpected condition. Please try your request again later." } } } } } } } } }, "/v1/connectors/:connectorId/credentials/:credentialId": { "delete": { "summary": "Revoke a connector's credential securely", "description": "In the intricate dance of data security, credentials sometimes lose their rhythm. This endpoint lets you gracefully revoke a credential, ensuring that your organization maintains its harmony. With the power of Passport delegation, only the maestro—the org admin or credential owner—can call the shots.", "operationId": "revokeCredential_1", "tags": [ "Security", "Credential Management" ], "x-code-hash": "a9105af40652719d", "x-generated-at": "2026-03-24T21:33:45.413Z", "responses": { "200": { "description": "The credential was successfully revoked, ensuring security integrity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential_id": { "type": "string" }, "status": { "type": "string" }, "revoked_by": { "type": "string" }, "revoked_at": { "type": "string", "format": "date-time" } }, "required": [ "credential_id", "status", "revoked_by", "revoked_at" ] }, "examples": { "successful_revocation": { "summary": "Successful Revocation", "value": { "credential_id": "cred-12345", "status": "revoked", "revoked_by": "passport-67890", "revoked_at": "2023-10-08T14:48:00.000Z" } } } } } }, "400": { "description": "The request was malformed, such as missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credential_id": { "summary": "Missing Credential ID", "value": { "type": "https://example.com/probs/missing-parameter", "title": "Missing Parameter", "status": 400, "detail": "The credentialId parameter is required.", "errors": [ "credentialId is missing" ] } } } } } }, "401": { "description": "Authentication failed. The Passport delegation token was not provided or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Failed", "status": 401, "detail": "Delegation token required. Please provide a valid Passport delegation token." } } } } } }, "403": { "description": "The actor is not authorized to revoke the credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_actor": { "summary": "Unauthorized Actor", "value": { "type": "https://example.com/probs/authorization-error", "title": "Authorization Failed", "status": 403, "detail": "You do not have permission to revoke this credential. Ensure you are either the org admin or the credential owner." } } } } } }, "404": { "description": "The credential or connector was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "credential_not_found": { "summary": "Credential Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The credential with the specified ID was not found. Check the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/connectors/:connectorId/credentials/:credentialId/stats": { "get": { "summary": "Retrieve 30-day credential usage statistics", "description": "Unlock insights into your system's performance by examining detailed 30-day usage statistics for a specific credential. This endpoint provides a comprehensive overview, including invocation counts, success and failure rates, and cost metrics, empowering you to optimize resource allocation and enhance operational efficiency.", "operationId": "getCredentialUsageStats", "tags": [ "Analytics", "Credentials" ], "x-code-hash": "7e13dc863406cbef", "x-generated-at": "2026-03-24T21:34:13.448Z", "responses": { "200": { "description": "Successfully retrieved credential usage statistics for the past 30 days.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential_id": { "type": "string", "description": "The unique identifier of the credential" }, "period": { "type": "string", "description": "The time period over which statistics are reported, fixed at '30_days'" }, "total_invocations": { "type": "integer", "description": "Total number of times the credential was invoked" }, "successful_invocations": { "type": "integer", "description": "Number of successful invocations" }, "failed_invocations": { "type": "integer", "description": "Number of failed invocations" }, "total_cost_usd": { "type": "number", "format": "float", "description": "Total cost incurred in USD" }, "total_tokens_used": { "type": "integer", "description": "Total number of tokens used" }, "avg_duration_ms": { "type": "number", "format": "float", "description": "Average duration of invocations in milliseconds" }, "last_used_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last invocation" }, "most_used_operation": { "type": "string", "description": "The operation most frequently invoked using this credential" } } }, "examples": { "acme_corp_credential_usage": { "summary": "Acme Corp Credential Usage", "description": "A snapshot of how Acme Corp's credential is performing over the last month", "value": { "credential_id": "cred-1234", "period": "30_days", "total_invocations": 1500, "successful_invocations": 1450, "failed_invocations": 50, "total_cost_usd": 123.45, "total_tokens_used": 7500, "avg_duration_ms": 235.67, "last_used_at": "2023-10-01T12:34:56Z", "most_used_operation": "processInvoice" } } } } } }, "400": { "description": "Invalid request format", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credential_id": { "summary": "Invalid Credential ID", "description": "The provided credential ID is not in a valid format", "value": { "type": "https://api.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided credential ID 'cred-xyz' is not valid. Ensure the ID is correctly formatted and try again." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_token": { "summary": "Missing Passport Token", "description": "Attempt to access the endpoint without a Passport token", "value": { "type": "https://api.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A valid Passport token is required to access this endpoint. Please provide a valid token and try again." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "User does not have access rights to view this credential's stats", "value": { "type": "https://api.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access these statistics. Please check your access rights or contact support." } } } } } }, "404": { "description": "Credential not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "credential_not_found": { "summary": "Credential Not Found", "description": "The specified credential ID does not exist in the system", "value": { "type": "https://api.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The credential with ID 'cred-5678' could not be found. Please verify the ID and try again." } } } } } }, "500": { "description": "Internal server error while retrieving statistics", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred on the server", "value": { "type": "https://api.humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/connectors/credentials/cache/stats": { "get": { "summary": "Retrieve credential cache statistics", "description": "Peel back the curtain on the performance of your credential caching system with this endpoint. Designed for system administrators, it provides a snapshot of cache efficiency, offering insights into hits, misses, and evictions. This data is crucial for optimizing the performance and reliability of your organization's credential handling.", "operationId": "getCredentialCacheStats", "tags": [ "Cache", "Credentials", "Admin" ], "x-code-hash": "d884406fd5f6daea", "x-generated-at": "2026-03-24T21:34:26.700Z", "responses": { "200": { "description": "Successfully retrieved credential cache statistics including hits, misses, evictions, and hit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "integer", "description": "Number of cache hits" }, "misses": { "type": "integer", "description": "Number of cache misses" }, "evictions": { "type": "integer", "description": "Number of cache evictions" }, "size": { "type": "integer", "description": "Current size of the cache" }, "hit_rate": { "type": "number", "format": "float", "description": "Hit rate as a decimal" }, "hit_rate_percent": { "type": "string", "description": "Hit rate as a percentage string" } } }, "examples": { "cache_statistics_example": { "summary": "Cache Statistics Example", "description": "An example response showing typical cache statistics.", "value": { "hits": 1200, "misses": 300, "evictions": 50, "size": 500, "hit_rate": 0.8, "hit_rate_percent": "80.00%" } } } } } }, "400": { "description": "Bad request due to malformed request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://yourapi.com/problems/bad-request", "title": "Bad Request", "status": 400, "detail": "The request parameters are malformed. Ensure all required fields are correctly formatted.", "errors": [ "Invalid query parameter 'foo'" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://yourapi.com/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required and has failed or has not yet been provided." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://yourapi.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource. Ensure your account has the appropriate roles." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://yourapi.com/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found. Check the URL and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected server conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://yourapi.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support." } } } } } } } } }, "/v1/reasoning/performance/:modelId": { "get": { "summary": "Retrieve AI Model Performance Metrics", "description": "Delve into the operational excellence of your AI model by retrieving performance metrics that span request volumes, success rates, latency, and cost. This endpoint empowers you to make data-driven decisions by providing insights into model efficiency over the past 30 days, dissected by complexity tiers.", "operationId": "getModelPerformanceStats", "tags": [ "AI Models", "Performance Metrics" ], "x-code-hash": "48faa0996315cb35", "x-generated-at": "2026-03-24T21:34:42.151Z", "responses": { "200": { "description": "Successfully retrieves the performance metrics for a specified model.", "content": { "application/json": { "schema": { "type": "object", "properties": { "model_id": { "type": "string" }, "total_requests": { "type": "integer" }, "success_rate": { "type": "number", "format": "float" }, "avg_latency_ms": { "type": "number", "format": "float" }, "avg_cost_usd": { "type": "number", "format": "float" }, "by_complexity": { "type": "object", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer" }, "success_rate": { "type": "number", "format": "float" }, "avg_cost": { "type": "number", "format": "float" } } } } } }, "examples": { "successful_performance_metrics_retrieval": { "summary": "Successful Performance Metrics Retrieval", "description": "Fetches detailed performance metrics for the 'gpt-4-turbo' model, offering insights into its operational behavior.", "value": { "model_id": "gpt-4-turbo", "total_requests": 1234, "success_rate": 0.98, "avg_latency_ms": 2500, "avg_cost_usd": 0.025, "by_complexity": { "simple": { "count": 800, "success_rate": 0.99, "avg_cost": 0.01 }, "medium": { "count": 300, "success_rate": 0.98, "avg_cost": 0.025 }, "complex": { "count": 134, "success_rate": 0.95, "avg_cost": 0.05 } } } } } } } }, "400": { "description": "The requested model ID is invalid or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_model_id": { "summary": "Invalid Model ID", "description": "The model ID provided does not conform to expected format.", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-model-id", "title": "Invalid Model ID", "status": 400, "detail": "The provided model ID '1234-@invalid' is not in the correct format. Ensure the model ID follows the pattern 'gpt-4-turbo'." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Access attempt without valid Passport credentials.", "value": { "type": "https://docs.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access is denied due to invalid Passport credentials. Please provide a valid Passport token." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Attempted access to a model's performance metrics without the required permissions.", "value": { "type": "https://docs.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to view this model's performance metrics. Please contact your administrator." } } } } } }, "404": { "description": "Model not found for the specified model ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "model_not_found": { "summary": "Model Not Found", "description": "No performance data available for the requested model ID.", "value": { "type": "https://docs.humanprotocol.org/errors/model-not-found", "title": "Model Not Found", "status": 404, "detail": "The model ID 'gpt-4-nonexistent' does not exist or has no performance data. Verify the model ID and try again." } } } } } }, "500": { "description": "Internal server error due to a problem on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://docs.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/secrets/:key": { "get": { "summary": "Retrieve encrypted secret value by key", "description": "Unravel the mystery behind secure data management by retrieving a secret value tied to your organization's cryptographic identity. This endpoint leverages a KMS-backed cascade approach to ensure that your sensitive information is accessible only within the right context, providing robust security and seamless integration.", "operationId": "getSecretValue", "tags": [ "Secrets", "Security" ], "x-code-hash": "8a3d19c710bce419", "x-generated-at": "2026-04-11T00:41:44.335Z", "responses": { "200": { "description": "Successfully retrieved the secret value for the specified key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The decrypted secret value associated with the given key." } }, "required": [ "value" ] }, "examples": { "successful_secret_retrieval": { "summary": "Successful secret retrieval", "description": "Retrieve the secret value for the 'api-token' key within the context of the 'acme' organization.", "value": { "value": "s3cr3tV4lu3" } } } } } }, "400": { "description": "Bad Request - The request could not be understood by the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_key_parameter": { "summary": "Missing Key Parameter", "description": "The request failed because the key parameter was missing.", "value": { "type": "/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The key parameter is missing or malformed. Please ensure you include a valid key in the request URL." } } } } } }, "401": { "description": "Unauthorized - The request did not include valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_authentication": { "summary": "Invalid Authentication", "description": "The request failed due to missing or invalid authentication credentials.", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing or invalid authentication token. Please provide a valid token and try again." } } } } } }, "403": { "description": "Forbidden - The client does not have permission to access the secret.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The request was denied due to insufficient permissions.", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this secret. Please check your access rights and try again." } } } } } }, "404": { "description": "Not Found - The specified key does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "secret_not_found": { "summary": "Secret Not Found", "description": "The request failed because the secret with the specified key was not found.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The secret with the specified key was not found. Please verify the key and try again." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the secret. Please try again later or contact support if the issue persists." } } } } } } } }, "put": { "summary": "Create or update a secret securely", "description": "Securely store or modify a secret using a cryptographic key, with optional details like expiration and rotatability. This endpoint ensures sensitive information is safeguarded while allowing controlled access and updates, crucial for dynamic environments where secrets must be frequently rotated.", "operationId": "setSecret", "tags": [ "Secrets Management", "Security" ], "x-code-hash": "a7cf009fd580c518", "x-generated-at": "2026-04-11T00:41:57.814Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The secret value to store. This is required." }, "description": { "type": "string", "description": "Optional description of the secret's purpose" }, "rotatable": { "type": "boolean", "description": "Indicates if the secret can be rotated" }, "expires_at": { "type": "string", "format": "date-time", "description": "The ISO 8601 date when the secret expires" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Legacy field for expiration date" } }, "required": [ "value" ] }, "examples": { "rotatable_api_key": { "summary": "Rotatable API Key", "description": "An example of an API key that can be rotated and has an expiration date.", "value": { "value": "supersecretapikey123", "description": "API key for external service integration", "rotatable": true, "expires_at": "2024-12-31T23:59:59Z" } } } } } }, "responses": { "204": { "description": "Secret stored or updated successfully", "content": { "application/json": {} } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized - Access token is missing or invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden - Insufficient permission to set secret", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found - Secret key not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "summary": "Delete Secret by Key", "description": "In the evolving landscape of digital orchestration, secrets securely guard access to sensitive operations. This endpoint empowers users to surgically delete a secret, purging it from the current scoped context. By doing so, it ensures that outdated or compromised credentials are swiftly retired, maintaining the integrity and security of the systems they protect.", "operationId": "deleteSecret", "tags": [ "Secrets", "Security" ], "x-code-hash": "718362af6dad4ed4", "x-generated-at": "2026-04-11T00:42:08.800Z", "responses": { "204": { "description": "The secret associated with the given key was successfully deleted.", "content": { "application/json": {} } }, "400": { "description": "The request was malformed. Ensure the key is properly formatted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication is required to delete the secret.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions to delete the secret.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The secret was not found for the provided key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/secrets/:key/rotate": { "post": { "summary": "Rotate a secret to a new value", "description": "Secrets are the lifeblood of secure systems, and rotating them periodically ensures their integrity. This endpoint allows you to rotate an existing secret to a new value, fortifying your security posture against potential vulnerabilities. The dual support for both `new_value` and `newValue` caters to modern and legacy clients alike, ensuring a smooth transition in your security practices.", "operationId": "rotateSecret", "tags": [ "Secrets", "Security" ], "x-code-hash": "9b247e44af6682a3", "x-generated-at": "2026-04-11T00:42:20.385Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "new_value": { "type": "string", "description": "The new secret value to replace the existing one." } }, "required": [ "new_value" ] }, { "type": "object", "properties": { "newValue": { "type": "string", "description": "The legacy field for new secret value, supported for backward compatibility." } }, "required": [ "newValue" ] } ] }, "examples": { "standard_new_value_rotation": { "summary": "Standard New Value Rotation", "description": "Rotating a secret using the modern `new_value` field.", "value": { "new_value": "newSecret123!" } }, "legacy_new_value_rotation": { "summary": "Legacy New Value Rotation", "description": "Rotating a secret using the legacy `newValue` field.", "value": { "newValue": "oldSecret456!" } } } } } }, "responses": { "204": { "description": "The secret was successfully rotated.", "content": { "application/json": {} } }, "400": { "description": "Bad Request due to validation errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found if the secret key does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/secrets": { "get": { "summary": "Retrieve organization's secret keys", "description": "Embark on a journey through the vault of secrets tailored for your organization. This endpoint is your key to uncovering cryptographic treasures, filtered by an optional prefix to hone in on specific secrets. Whether you're securing data or managing credentials, this is an essential tool for orchestrating human-AI interactions with precision.", "operationId": "getSecrets", "tags": [ "Secrets", "Organization", "Security" ], "x-code-hash": "d5a7cd2acf8579ad", "x-generated-at": "2026-04-11T00:42:32.986Z", "responses": { "200": { "description": "A successful retrieval of secret keys for the specified organization context, potentially filtered by a prefix.", "content": { "application/json": { "schema": { "type": "object", "description": "List of credential key names for the scoped org/context (`ConfigService.credentials.listKeys`). The `keys` array is always present (may be empty).", "properties": { "keys": { "type": "array", "items": { "type": "string" }, "description": "Secret key identifiers (values are never included)." } }, "required": [ "keys" ] }, "examples": { "successful_keys_retrieval": { "summary": "Successful keys retrieval", "description": "Organization retrieves secret key names to audit credentials.", "value": { "keys": [ "db-connection-string", "api-key-123", "s3-access-token" ] } } } } } }, "400": { "description": "Invalid request parameters, such as malformed prefix.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/validation-error", "title": "Invalid Request", "status": 400, "detail": "The 'prefix' query parameter is malformed.", "errors": [ "prefix must be a valid string" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/auth-error", "title": "Unauthorized", "status": 401, "detail": "Passport credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/permission-error", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these secrets." } } } } } }, "404": { "description": "The specified context or organization could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/not-found", "title": "Not Found", "status": 404, "detail": "The organization context specified does not exist." } } } } } }, "500": { "description": "A server-side error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while fetching secrets." } } } } } } } } }, "/v1/secrets/:key/info": { "get": { "summary": "Retrieve metadata for a secret key", "description": "Unlock the insights without the secrets. This endpoint provides metadata about a secret key, offering a glimpse into its lifecycle and attributes without revealing its value. It's a crucial tool for auditing and understanding the secrets you manage, ensuring your operations maintain transparency and control.", "operationId": "getSecretKeyInfo", "tags": [ "Secrets", "Metadata" ], "x-code-hash": "b6073cb49503c6ba", "x-generated-at": "2026-04-11T00:42:43.502Z", "responses": { "200": { "description": "Successfully retrieved secret key metadata.", "content": { "application/json": { "schema": { "type": "object", "description": "Credential metadata without the secret value (`CredentialInfo`). Same resolution cascade as GET /v1/secrets/:key.", "properties": { "key": { "type": "string", "description": "Secret key identifier (matches path parameter `:key`)." }, "description": { "type": "string", "nullable": true, "description": "Human-readable label when set; JSON null when unset." }, "rotatable": { "type": "boolean", "description": "Whether the credential supports rotation." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiration instant when set; JSON null when none." }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Creation time when known." }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update time when known." } }, "required": [ "key", "description", "rotatable", "expires_at", "created_at", "updated_at" ] }, "examples": { "secret_key_metadata": { "summary": "Secret metadata", "value": { "key": "api-key-1234", "description": "Production API key for payment processing", "rotatable": true, "expires_at": "2025-12-31T23:59:59.000Z", "created_at": "2023-01-15T12:34:56.000Z", "updated_at": "2023-06-10T08:22:44.000Z" } }, "secret_key_metadata_nullables": { "summary": "Metadata with null description and expiry", "value": { "key": "legacy-token", "description": null, "rotatable": false, "expires_at": null, "created_at": "2023-01-15T12:34:56.000Z", "updated_at": "2023-06-10T08:22:44.000Z" } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_key_format": { "summary": "Invalid Key Format", "value": { "type": "https://api.human/probs/invalid-request", "title": "Invalid Parameter", "status": 400, "detail": "The key parameter must be a valid string." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://api.human/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://api.human/probs/insufficient-permissions", "title": "Access Denied", "status": 403, "detail": "You do not have permission to view this secret key's metadata." } } } } } }, "404": { "description": "The secret key was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "secret_key_not_found": { "summary": "Secret Key Not Found", "value": { "type": "https://api.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "The secret key 'acme-api-key' was not found." } } } } } }, "500": { "description": "Internal server error while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the secret key info." } } } } } } } } }, "/v1/approvals/:id/messages": { "get": { "summary": "Retrieve Approval Request Conversation History", "description": "Dive into the narrative of an approval request by accessing its conversation history. This endpoint serves to illuminate the decision-making process, showcasing interactions and deliberations that led to an approval. It supports both delegation and signed token authentication, ensuring secure access to sensitive dialogues.", "operationId": "getApprovalMessages", "tags": [ "Approvals", "Messages" ], "x-code-hash": "2a5026ef65b90e35", "x-generated-at": "2026-03-24T21:36:38.827Z", "responses": { "200": { "description": "Successfully retrieved the conversation messages for the specified approval request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_id": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "examples": { "default": { "summary": "Example", "value": { "approval_id": "12345", "messages": [ { "id": "msg1", "role": "requester", "content": "Please approve this invoice.", "created_at": "2023-10-01T12:00:00Z" }, { "id": "msg2", "role": "approver", "content": "Can you provide more details?", "created_at": "2023-10-01T12:05:00Z" } ] } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The approval ID format is incorrect.", "errors": [ "approval_id must be a valid UUID." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing authentication. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access due to token approval ID mismatch.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Token is not valid for this approval. Ensure the token matches the approval ID." } } } } } }, "404": { "description": "Approval request not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Approval request with ID 12345 does not exist. Verify the approval ID." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Reference incident ID inc_1696343773000 for support." } } } } } } } }, "post": { "summary": "Send a Message in Approval Conversation", "description": "In the intricate ballet of task approvals, communication is key. This endpoint lets you send a message within an approval conversation, fostering collaboration and ensuring clarity. If the conversation doesn't exist yet, fear not—it gracefully creates one, ensuring no message goes unheard.", "operationId": "sendApprovalMessage", "tags": [ "Approvals", "Messaging" ], "x-code-hash": "af1188d0ee797c38", "x-generated-at": "2026-03-24T21:36:54.207Z", "responses": { "200": { "description": "Message sent successfully; includes both human and agent responses.", "content": { "application/json": {} } }, "400": { "description": "Validation error due to missing or invalid message content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Authorization error due to token scope mismatch.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified approval request was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict error due to the approval being in a non-pending state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/access-requests": { "post": { "summary": "Submit access request for investor portal", "description": "Empower your leadership to manage access with confidence. This endpoint allows you to submit a request for accessing the investor portal, ensuring that all requests are vetted by organizational leaders for security and compliance.", "operationId": "submitAccessRequest", "tags": [ "Access Management", "Investor Portal" ], "x-code-hash": "1f33166add979450", "x-generated-at": "2026-03-24T21:37:06.083Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Optional message to accompany the access request, limited to 1000 characters." } }, "required": [] }, "examples": { "request_access_to_investor_portal": { "summary": "Request access to investor portal", "description": "An example where a user provides a message explaining the reason for their access request.", "value": { "message": "Requesting access to manage investment portfolios and view real-time data insights." } } } } } }, "responses": { "201": { "description": "Access request accepted and pending leadership review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the created approval request." }, "status": { "type": "string", "description": "Current status of the approval request." } } }, "examples": { "default": { "summary": "Example", "value": { "id": "access-req-task-12345", "status": "pending" } } } } } }, "400": { "description": "Invalid request format or parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Bad Request", "status": 400, "detail": "Invalid JSON format or missing fields.", "errors": [ "The 'message' field must be a string." ] } } } } } }, "401": { "description": "Authentication required to submit an access request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to submit an access request. Please log in and try again." } } } } } }, "403": { "description": "Access request system is not configured properly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/system-not-configured", "title": "Configuration Error", "status": 403, "detail": "Leadership DIDs are not configured. Please contact the system administrator." } } } } } }, "429": { "description": "Rate limit exceeded for access requests.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "You have exceeded the maximum number of access requests allowed per hour. Please wait before trying again." } } } } } } } } }, "/v1/access-requests/mine": { "get": { "summary": "Retrieve User's Latest Access Request", "description": "In the complex dance between humans and AI, knowing the status of your access request is paramount. This endpoint grants you a window into your own access journey, revealing whether your plea for entry into the digital realm is pending, approved, or denied. Whether you're an investor checking your status or an AI ensuring compliance, this status update is your compass.", "operationId": "getUserAccessRequest", "tags": [ "AccessRequests", "UserStatus" ], "x-code-hash": "9366b811dfb6eb05", "x-generated-at": "2026-03-24T21:37:25.781Z", "responses": { "200": { "description": "Successfully retrieved the latest access request of the authenticated user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier of the access request." }, "status": { "type": "string", "description": "Current status of the access request." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the request was created." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Timestamp when the request will expire." }, "respondedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the request was responded to, if applicable." } } } } }, "examples": { "approved_access_request_example": { "summary": "Approved Access Request Example", "description": "The user has an approved access request.", "value": { "request": { "id": "req-12345", "status": "approved", "createdAt": "2023-09-15T12:00:00Z", "expiresAt": "2023-12-15T12:00:00Z", "respondedAt": "2023-09-16T14:30:00Z" } } } } } } }, "400": { "description": "Malformed request due to incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request_format": { "summary": "Invalid Request Format", "description": "The request could not be understood by the server due to malformed syntax.", "value": { "type": "https://api.humanprotocol.org/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters are incorrect. Please ensure your request follows the correct format." } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_access_attempt": { "summary": "Unauthenticated Access Attempt", "description": "User attempted to access the endpoint without authentication.", "value": { "type": "https://api.humanprotocol.org/problems/unauthenticated", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access this resource. Please log in and try again." } } } } } }, "403": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "User lacks permission to access this resource.", "value": { "type": "https://api.humanprotocol.org/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to view this resource. Please contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "No access request found for the authenticated user.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_request_not_found": { "summary": "Access Request Not Found", "description": "The system could not find an access request for the user.", "value": { "type": "https://api.humanprotocol.org/problems/not-found", "title": "Access Request Not Found", "status": 404, "detail": "No access request exists for your account. Consider initiating a new request if necessary." } } } } } }, "500": { "description": "An error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Unexpected conditions prevented the server from fulfilling the request.", "value": { "type": "https://api.humanprotocol.org/problems/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/provenance/log/fraud-decision": { "post": { "summary": "Log Fraud Decision for Provenance Tracking", "description": "In the delicate dance of fraud detection, ensuring the authenticity of decisions is paramount. This endpoint records fraud decisions into the HUMAN Distributed Ledger, providing an immutable provenance trail. By capturing these decisions, organizations can maintain transparency and accountability in their fraud detection processes.", "operationId": "logFraudDecision", "tags": [ "Provenance", "Fraud Detection" ], "x-code-hash": "da79f88450c74522", "x-generated-at": "2026-03-24T21:37:38.255Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "case_ref": { "type": "string", "description": "Reference ID of the fraud case." }, "decision_type": { "type": "string", "description": "Type of decision made regarding the case.", "default": "fraud_decision" } }, "required": [ "case_ref" ] }, "examples": { "fraud_case_logging": { "summary": "Fraud Case Logging", "description": "Logs a decision for a potential fraud case.", "value": { "case_ref": "INV-12345", "decision_type": "fraudulent" } } } } } }, "responses": { "201": { "description": "Fraud decision successfully logged in the provenance ledger.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provenance_entry_id": { "type": "string", "description": "Unique identifier for the logged provenance entry." }, "case_ref": { "type": "string", "description": "Reference ID of the fraud case." }, "decision_type": { "type": "string", "description": "Type of decision made regarding the case." }, "recorded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the decision was recorded." } } }, "examples": { "default": { "summary": "Example", "value": { "provenance_entry_id": "cp_fprov_67890", "case_ref": "INV-12345", "decision_type": "fraudulent", "recorded_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid Request", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "unparseable" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation context required." } } } } } }, "500": { "description": "Internal server error occurred while logging the fraud decision.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Record Failed", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/analytics/fraud-metrics": { "get": { "summary": "Retrieve Fraud Metrics for Organization", "description": "Discover insights into your organization's fraud management with a comprehensive overview of fraud metrics. Use this endpoint to access key statistics, ensuring your team stays one step ahead in the fight against fraud. The metrics are meticulously calculated based on recent activities, providing both cached results for efficiency and live data for accuracy.", "operationId": "getFraudMetrics", "tags": [ "Analytics", "Fraud" ], "x-code-hash": "de208f1c47593a80", "x-generated-at": "2026-03-24T21:37:54.655Z", "responses": { "200": { "description": "Successfully retrieved fraud metrics for the specified period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "description": "The period for which metrics are calculated, in the format 'Nd' (e.g., '30d')." }, "computed_at": { "type": "string", "format": "date-time", "description": "The timestamp when the metrics were computed." }, "source": { "type": "string", "enum": [ "cache", "live_aggregate" ], "description": "Indicates whether the data was retrieved from cache or computed live." }, "metrics": { "type": "object", "properties": { "fraud_policy_reviews": { "type": "integer", "description": "Number of fraud policy reviews conducted." }, "fraud_cases_routed": { "type": "integer", "description": "Number of fraud cases routed." }, "fraud_provenance_decisions": { "type": "integer", "description": "Number of fraud provenance decisions made." } } } } }, "examples": { "successful_metrics_retrieval": { "summary": "Successful Metrics Retrieval", "value": { "period": "30d", "computed_at": "2023-10-05T14:48:00Z", "source": "live_aggregate", "metrics": { "fraud_policy_reviews": 45, "fraud_cases_routed": 23, "fraud_provenance_decisions": 17 } } } } } } }, "400": { "description": "Invalid request due to incorrect period format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_period_format": { "summary": "Invalid Period Format", "value": { "type": "https://humanprotocol.org/errors/invalid-period-format", "title": "Invalid Period Format", "status": 400, "detail": "The period must match 'Nd' (e.g., 30d).", "errors": [ { "field": "period", "code": "INVALID_FORMAT", "message": "Period must match Nd (e.g. 30d).", "expected": "string like 30d", "received": "3 weeks" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://humanprotocol.org/errors/authentication", "title": "Delegation Required", "status": 401, "detail": "Delegation is required to access this endpoint. Ensure your request includes a valid delegation header." } } } } } }, "403": { "description": "Permission error due to insufficient rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://humanprotocol.org/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access these fraud metrics. Contact your administrator to request access." } } } } } }, "404": { "description": "Metrics not found for the given DID and period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "metrics_not_found": { "summary": "Metrics Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Metrics Not Found", "status": 404, "detail": "No fraud metrics found for the specified organization DID and period. Verify the DID and period and try again." } } } } } }, "500": { "description": "Internal server error during metrics retrieval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving fraud metrics. Please try again later." } } } } } } } } }, "/v1/orgs/orgs/:orgId/employees": { "post": { "summary": "Initiate Employee Onboarding with Verification", "description": "Embark on a seamless journey to onboard new employees by creating their records and initiating the verification process. This endpoint empowers organizations to swiftly integrate new members into their ranks, ensuring they are equipped with a digital identity that links them securely to their workplace.", "operationId": "createEmployeeRecord_1", "tags": [ "Organization Management", "Employee Onboarding" ], "x-code-hash": "b484accd64385ea8", "x-generated-at": "2026-03-27T00:41:10.375Z", "responses": { "201": { "description": "Employee record successfully created. Onboarding email sent.", "content": { "application/json": {} } }, "400": { "description": "Malformed request body or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "The requestor lacks permission to create employees.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified organization was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "summary": "Retrieve list of organization employees", "description": "Discover the diverse talent within your organization by listing all current employees. This endpoint empowers you with the ability to manage workforce data efficiently, ensuring you can make informed decisions quickly. It's a key tool for organizations like 'acme' to maintain a dynamic understanding of their human resources landscape.", "operationId": "listOrgEmployees", "tags": [ "Organization", "Employees" ], "x-code-hash": "dbf76a8aa883f7eb", "x-generated-at": "2026-03-27T00:41:29.100Z", "responses": { "200": { "description": "A paginated list of employees within the specified organization, complete with their roles, departments, and status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "employee_id": { "type": "string" }, "legal_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "employee_number": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "department": { "type": [ "string", "null" ] }, "linking_code": { "type": "string" }, "linking_code_expires_at": { "type": "string", "format": "date-time" }, "linked_passport_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" } } }, "examples": { "employee_list_for_acme_corporation": { "summary": "Employee list for Acme Corporation", "description": "A snapshot of the employee directory for Acme Corp, showcasing a diverse set of roles and departments.", "value": { "data": [ { "employee_id": "e123", "legal_name": "John Doe", "email": "john.doe@acme.org", "employee_number": "4567", "role": "Software Engineer", "department": "Engineering", "linking_code": "abcd-1234", "linking_code_expires_at": "2023-11-01T10:00:00Z", "linked_passport_id": null, "status": "active", "created_at": "2023-01-15T12:00:00Z" }, { "employee_id": "e124", "legal_name": "Jane Smith", "email": "jane.smith@acme.org", "employee_number": "4568", "role": "Product Manager", "department": "Product", "linking_code": "efgh-5678", "linking_code_expires_at": "2023-11-01T10:00:00Z", "linked_passport_id": "passport-9876", "status": "active", "created_at": "2023-02-20T09:30:00Z" } ], "limit": 50, "cursorField": "created_at" } } } } } }, "400": { "description": "The request could not be understood by the server due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "description": "The 'limit' query parameter was not a valid integer.", "value": { "type": "https://human/probs/invalid-query-param", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'limit' parameter must be an integer." } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://human/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "The server understood the request, but the client does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The client does not have the necessary permissions to list the employees.", "value": { "type": "https://human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Insufficient permissions to list employees. Ensure your delegation includes the 'org:employees:read' capability." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "The specified organization ID does not exist in the system.", "value": { "type": "https://human/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization with ID 'org_123' was not found." } } } } } }, "500": { "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An error occurred while processing the request.", "value": { "type": "https://human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID 'inc_1698765432100'." } } } } } } } } }, "/v1/orgs/orgs/:orgDid/slug": { "post": { "summary": "Register a unique organization slug", "description": "Organizations claim a globally unique slug, essential for agent URI addressing, ensuring seamless namespace resolution in the HUMAN ecosystem. This process fortifies your organization's identity, carving a distinct digital path with every agent interaction.", "operationId": "postOrgSlugRegistration", "tags": [ "Organization", "Namespace" ], "x-code-hash": "641968d0aed3d33c", "x-generated-at": "2026-03-27T00:41:52.676Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "The desired slug, must be 3-64 characters, lowercase alphanumeric with hyphens, starting and ending with an alphanumeric character." }, "display_name": { "type": "string", "description": "Optional human-readable name for the organization." } }, "required": [ "slug" ] }, "examples": { "acme_corporation_slug_registration": { "summary": "Acme Corporation Slug Registration", "description": "Claim a slug for Acme Corporation's namespace", "value": { "slug": "acme-corp", "display_name": "Acme Corporation" } } } } } }, "responses": { "201": { "description": "Slug successfully claimed and registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "org_did": { "type": "string" }, "display_name": { "type": "string" }, "claimed_by": { "type": "string" }, "status": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid slug format or missing parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.sh/errors/invalid-request", "title": "Invalid Request Parameters", "status": 400, "detail": "Slug must be 3-64 chars, lowercase alphanumeric + hyphens, starting and ending with alphanumeric.", "errors": [ { "field": "slug", "code": "INVALID_FORMAT", "message": "Expected pattern: /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/" } ] } } } } } }, "401": { "description": "Unauthorized access, admin delegation required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.sh/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be an org admin to claim a slug. Ensure you have the correct delegation." } } } } } }, "403": { "description": "Permission denied for slug registration", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.sh/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to register a slug for this organization." } } } } } }, "404": { "description": "Organization DID not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.sh/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified organization DID was not found. Verify the DID and try again." } } } } } }, "409": { "description": "Conflict due to existing slug or organization slug", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.sh/errors/conflict", "title": "Organization already has a slug", "status": 409, "detail": "Organization did:org:123456789abcdef already has a registered slug." } } } } } }, "500": { "description": "Internal server error during slug registration", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.sh/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1696423987." } } } } } } } }, "get": { "summary": "Retrieve organization's slug if claimed", "description": "Discover the unique and memorable slug associated with an organization, revealing its digital identity on the HUMAN platform. This endpoint addresses the need for distinct identification, ensuring seamless interaction and recognition in a distributed, AI-driven ecosystem.", "operationId": "getOrgSlug", "tags": [ "Organization", "Identity" ], "x-code-hash": "d219a6a4cd238dbf", "x-generated-at": "2026-03-27T00:42:11.321Z", "responses": { "200": { "description": "Returns the organization's slug and related details if claimed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "The unique slug representing the organization." }, "org_did": { "type": "string", "description": "The decentralized identifier (DID) of the organization." }, "display_name": { "type": "string", "description": "The display name of the organization, if available.", "nullable": true }, "claimed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the slug was claimed." } }, "required": [ "slug", "org_did", "claimed_at" ] }, "examples": { "successful_slug_retrieval": { "summary": "Successful Slug Retrieval", "description": "Fetching the slug for 'acme-corp'.", "value": { "slug": "acme-corp", "org_did": "did:human:example123", "display_name": "Acme Corporation", "claimed_at": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "Bad Request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_orgdid": { "summary": "Malformed OrgDID", "description": "Example of a 400 error when OrgDID is not formatted properly.", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The OrgDID provided is not valid. Ensure it is a correctly formatted DID." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing Credentials", "description": "Example of a 401 error due to missing authentication token.", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Please provide a valid authentication token to access this resource." } } } } } }, "403": { "description": "Forbidden access when user lacks permission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Example of a 403 error when the user does not have access rights.", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Ensure your account has the necessary permissions to access this organization's slug." } } } } } }, "404": { "description": "Slug not found for the given organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "slug_not_claimed": { "summary": "Slug Not Claimed", "description": "Example of a 404 error when no slug is found for the org.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The organization with DID 'did:human:example123' does not have a claimed slug. Verify the DID or claim a slug." } } } } } }, "500": { "description": "Internal server error during slug retrieval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_connection_issue": { "summary": "Database Connection Issue", "description": "Example of a 500 error due to a temporary database connection issue.", "value": { "type": "/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "There was a problem connecting to the database. Please retry your request or contact support if the issue persists." } } } } } } } } }, "/v1/resources/:id": { "get": { "summary": "Retrieve specific resource by ID or URI", "description": "Dive into the intricate world of resource management with this endpoint. Whether you possess a UUID or a URI, this call unravels the details of a singular resource, ensuring data integrity and precision in task orchestration through the HUMAN Protocol.", "operationId": "getResource", "tags": [ "Resources", "Data Retrieval" ], "x-code-hash": "e06831290fad8043", "x-generated-at": "2026-04-02T20:10:19.482Z", "responses": { "200": { "description": "Successfully retrieved resource details", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid" }, "uri": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "resource_id", "name", "created_at" ] }, "examples": { "default": { "summary": "Example", "value": { "resource_id": "123e4567-e89b-12d3-a456-426614174000", "uri": "http://acme.org/resources/financial-report", "name": "Financial Report", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T15:00:00Z" } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "No resource with ID '123e4567-e89b-12d3-a456-426614174000' was found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Reference ID: inc_1700000000" } } } } } } } }, "patch": { "summary": "Modify a resource's core attributes", "description": "In a world where data evolves, updating a resource's fundamental attributes ensures it's always aligned with current realities. This endpoint allows you to modify key aspects of a resource, such as its kind, schema identification, metadata, and provenance reference, while maintaining a secure and immutable ownership structure.", "operationId": "updateResource", "tags": [ "Resources" ], "x-code-hash": "de0ff731fc9e87d7", "x-generated-at": "2026-04-02T20:10:37.163Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "A new classification for the resource" }, "schema_id": { "type": "string", "nullable": true, "description": "Identifier for the resource's schema, if applicable" }, "metadata": { "type": "object", "description": "Additional data describing the resource" }, "provenance_ref": { "type": "string", "nullable": true, "description": "Reference to the resource's provenance" } }, "required": [] }, "examples": { "update_resource_kind_and_metadata": { "summary": "Update Resource Kind and Metadata", "description": "Changing the resource kind and adding metadata for better classification.", "value": { "kind": "core.invoice.document", "metadata": { "priority": "high", "department": "finance" } } } } } } }, "responses": { "200": { "description": "The resource has been successfully updated with new attributes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_id": { "type": "string" }, "uri": { "type": "string" }, "owner_did": { "type": "string" }, "controller_did": { "type": "string" }, "kind": { "type": "string" }, "schema_id": { "type": "string", "nullable": true }, "connector_id": { "type": "string" }, "metadata": { "type": "object" }, "provenance_ref": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request format or content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "The specified resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } }, "delete": { "summary": "Soft-delete a resource entry safely", "description": "In the intricate dance of data management, not all deletions are final. This endpoint offers a safeguard by soft-deleting a resource, marking it as inactive while keeping its historical footprint for audit trails. It's the digital equivalent of setting aside a book on a crowded shelf, knowing it can be revisited when needed.", "operationId": "deleteResource", "tags": [ "Resources", "Data Management" ], "x-code-hash": "0b5cd83682eb58e5", "x-generated-at": "2026-04-02T20:10:51.609Z", "responses": { "200": { "description": "The resource has been successfully soft-deleted, ensuring it remains invisible in standard queries but preserved for historical accuracy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "The unique identifier of the resource" }, "deleted": { "type": "boolean", "description": "Indicates if the resource was successfully marked as deleted" }, "deleted_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the resource was soft-deleted" } } }, "examples": { "successful_deletion": { "summary": "Successful Deletion", "description": "A resource identified by '12345' is successfully soft-deleted.", "value": { "resource_id": "12345", "deleted": true, "deleted_at": "2023-11-01T12:34:56Z" } } } } } }, "404": { "description": "The resource could not be found, perhaps due to an incorrect ID or it being already deleted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "An attempt to delete a non-existent resource.", "value": { "type": "/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The resource with ID '12345' was not found." } } } } } }, "500": { "description": "An unexpected server error occurred while attempting to delete the resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A failure on the server prevents the deletion of a resource.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An internal error occurred while attempting to delete the resource with ID '12345'. Please try again later." } } } } } } } } }, "/v1/schemas/:id/example": { "get": { "summary": "Retrieve an example schema payload", "description": "Dive into the world of schemas by fetching a sample payload that showcases its structure and usage. This endpoint is your gateway to creating realistic mock data, enhancing SDK documentation, and enriching your development playground with practical examples.", "operationId": "getSchemaExample_1", "tags": [ "Schemas", "Examples" ], "x-code-hash": "630746c64da9fef7", "x-generated-at": "2026-03-24T21:40:42.615Z", "responses": { "200": { "description": "Successfully retrieved the schema example payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "kind": { "type": "string" }, "version": { "type": "string" }, "example": { "type": "object" } }, "required": [ "schema_id", "kind", "version", "example" ] }, "examples": { "sample_email_message_schema": { "summary": "Sample Email Message Schema", "description": "An example payload for the core.email.message.v1 schema, perfect for testing email processing in your application.", "value": { "schema_id": "core.email.message.v1", "kind": "message", "version": "1.0", "example": { "from": "alice@example.com", "to": "bob@example.com", "subject": "Meeting Reminder", "body": "Don't forget about our meeting at 3 PM." } } } } } } }, "400": { "description": "Invalid schema ID provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_id_example": { "summary": "Invalid ID Example", "value": { "type": "https://example.com/probs/invalid-id", "title": "Invalid Schema ID", "status": 400, "detail": "The provided schema ID 'invalid_id' is not valid. Please check the ID and try again." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing Credentials", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "You must provide valid credentials to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied_example": { "summary": "Access Denied Example", "value": { "type": "https://example.com/probs/insufficient-permissions", "title": "Access Denied", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "The requested schema was not found or has no defined examples.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schema_not_found_example": { "summary": "Schema Not Found Example", "value": { "type": "https://example.com/probs/schema-not-found", "title": "Schema Not Found", "status": 404, "detail": "The schema with ID 'core.email.message.v1' was not found, or no examples are defined." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_error_example": { "summary": "Internal Error Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/schemas/:id": { "get": { "summary": "Retrieve schema by unique identifier", "description": "Unlock the potential of structured data by accessing schemas through their unique identifiers. This endpoint is your gateway to understanding data models, enabling seamless integration and data orchestration across the HUMAN platform.", "operationId": "getSchema_1", "tags": [ "Schemas" ], "x-code-hash": "30cf362931bd5274", "x-generated-at": "2026-03-24T21:40:53.396Z", "responses": { "200": { "description": "Successfully retrieved the schema details.", "content": { "application/json": {} } }, "404": { "description": "Schema not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/passport/attestations/credential": { "post": { "summary": "Create a new credential attestation", "description": "Forge a verifiable link between an organization and a subject through cryptographic identity. This endpoint empowers organizations to attest to credentials, securely embedding trust into decentralized interactions. By weaving human intent with machine precision, it strengthens the backbone of the HUMAN network.", "operationId": "createCredentialAttestation", "tags": [ "Passport", "Identity" ], "x-code-hash": "bd93f196c3e804d4", "x-generated-at": "2026-04-11T01:59:39.215Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_did": { "type": "string", "description": "Decentralized Identifier (DID) of the subject receiving the credential." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Additional attributes to include in the attestation payload." } }, "required": [ "subject_did" ] }, "examples": { "credential_attestation_for_alice": { "summary": "Credential Attestation for Alice", "description": "Attesting a credential for Alice under the organization 'acme'.", "value": { "subject_did": "did:example:alice", "attributes": { "role": "engineer", "department": "R&D" } } } } } } }, "responses": { "201": { "description": "Credential attestation successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "attestation_id": { "type": "string", "description": "Unique identifier for the created attestation." }, "attestation_kind": { "type": "string", "enum": [ "credential" ], "description": "Type of attestation created." }, "subject_did": { "type": "string", "description": "DID of the subject for whom the credential was attested." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the attestation was created." } } }, "examples": { "default": { "summary": "Example", "value": { "attestation_id": "cp_att_cred_12345", "attestation_kind": "credential", "subject_did": "did:example:alice", "created_at": "2023-10-22T14:48:00Z" } } } } } }, "400": { "description": "Bad request due to invalid or missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body contained invalid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required to perform this action. Ensure your credentials are correct and try again." } } } } } }, "403": { "description": "Forbidden access due to lack of permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permissions to create attestations. Verify your role and permissions within the organization." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/passport/attestations/license": { "post": { "summary": "Create license attestation for a Passport", "description": "This endpoint allows organizations to attest a license to a subject's Passport, strengthening trust in identity verification within the HUMAN ecosystem. By enabling license attestations, organizations can securely affirm the skills and credentials of individuals, enhancing the reliability of the Capability Graph.", "operationId": "createLicenseAttestation", "tags": [ "Passport", "Attestation" ], "x-code-hash": "91bc4991c5ef60e1", "x-generated-at": "2026-04-11T01:59:53.884Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_did": { "type": "string", "description": "The decentralized identifier (DID) of the subject to whom the license is being attested", "example": "did:human:123456789abcdefghi" }, "license_details": { "type": "object", "description": "Additional metadata describing the license", "properties": { "license_type": { "type": "string", "description": "Type of the license being attested", "example": "driver's license" }, "issuer": { "type": "string", "description": "The issuing authority or organization", "example": "Department of Motor Vehicles" }, "validity_period": { "type": "object", "description": "Start and end dates defining the validity period of the license", "properties": { "start_date": { "type": "string", "format": "date", "description": "Start date of the license validity", "example": "2023-01-01" }, "end_date": { "type": "string", "format": "date", "description": "End date of the license validity", "example": "2028-12-31" } }, "required": [ "start_date", "end_date" ] } }, "required": [ "license_type", "issuer", "validity_period" ] } }, "required": [ "subject_did", "license_details" ] }, "examples": { "driver's_license_attestation": { "summary": "Driver's License Attestation", "description": "Attesting a driver's license for a subject.", "value": { "subject_did": "did:human:123456789abcdefghi", "license_details": { "license_type": "driver's license", "issuer": "Department of Motor Vehicles", "validity_period": { "start_date": "2023-01-01", "end_date": "2028-12-31" } } } } } } } }, "responses": { "201": { "description": "License attestation successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "attestation_id": { "type": "string", "description": "Unique identifier for the created attestation", "example": "cp_att_lic_1234567890" }, "attestation_kind": { "type": "string", "description": "Kind of attestation created", "example": "license" }, "subject_did": { "type": "string", "description": "DID of the subject for whom the attestation was created", "example": "did:human:123456789abcdefghi" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the attestation was created", "example": "2023-11-23T12:34:56Z" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad request due to invalid JSON or missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/validation", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication", "title": "Delegation required", "status": 401, "detail": "The request requires organizational delegation. Please ensure proper credentials are provided." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/permission", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error encountered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/proofs": { "get": { "summary": "Retrieve Passport Jurisdiction Proofs", "description": "Unravel the cryptographic tapestry of identity by accessing jurisdiction-specific proofs associated with a Passport DID. This endpoint empowers organizations to verify identity assertions across borders, ensuring trust and compliance in human-AI orchestration.", "operationId": "getPassportProofs", "tags": [ "Passport", "Identity" ], "x-code-hash": "abe4c195c684998a", "x-generated-at": "2026-04-11T02:00:11.285Z", "responses": { "200": { "description": "Successfully retrieved jurisdiction proofs for the specified Passport DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jurisdiction": { "type": "string", "description": "The jurisdiction under which the proofs are categorized." }, "passport_did": { "type": "string", "description": "The Decentralized Identifier (DID) of the passport whose proofs are retrieved." }, "proofs": { "type": "array", "items": { "type": "object", "properties": { "proof_id": { "type": "string", "description": "The unique identifier for the proof." }, "proof_type": { "type": [ "string", "null" ], "description": "The type of proof, if specified." }, "payload": { "type": "object", "description": "The payload of the proof, potentially including specific claims." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the proof was created." } }, "required": [ "proof_id", "payload", "created_at" ] } } }, "required": [ "jurisdiction", "passport_did", "proofs" ] }, "examples": { "proofs_for_acme_corp": { "summary": "Proofs for ACME Corp", "description": "This example shows proofs retrieved for ACME Corp under the jurisdiction of 'US'.", "value": { "jurisdiction": "US", "passport_did": "did:human:123456789abcdefghi", "proofs": [ { "proof_id": "proof-001", "proof_type": "residency", "payload": { "claim": "resides_in_US" }, "created_at": "2023-10-01T12:00:00Z" }, { "proof_id": "proof-002", "proof_type": null, "payload": { "claim": "employment_verified" }, "created_at": "2023-10-02T15:30:00Z" } ] } } } } } }, "400": { "description": "The request was invalid due to missing or incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_query_parameters": { "summary": "Missing Query Parameters", "description": "Example response when 'jurisdiction' and 'passport_did' are missing.", "value": { "type": "/problems/invalid-request", "title": "Invalid request parameters", "status": 400, "detail": "One or more query parameters are missing or invalid.", "errors": [ { "field": "jurisdiction", "code": "REQUIRED_QUERY_PARAM", "message": "jurisdiction query parameter is required", "expected": "non-empty string (e.g. ISO country code)", "received": "missing" }, { "field": "passport_did", "code": "REQUIRED_QUERY_PARAM", "message": "passport_did (or subject_did) query parameter is required", "expected": "non-empty string", "received": "missing" } ] } } } } } }, "401": { "description": "Authentication failure due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "This example shows an error response when delegation is required but not provided.", "value": { "type": "/problems/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation required. Please authenticate with proper delegation credentials." } } } } } }, "403": { "description": "The request is forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "This example illustrates a forbidden response due to lack of permissions.", "value": { "type": "/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Ensure your account has the necessary permissions." } } } } } }, "404": { "description": "No proofs found for the specified DID and jurisdiction.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "proofs_not_found": { "summary": "Proofs Not Found", "description": "Example response when no proofs match the query.", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "No proofs found for the specified Passport DID and jurisdiction." } } } } } }, "500": { "description": "A server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An example of what happens when the server encounters an unexpected condition.", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/passport/context/travel": { "post": { "summary": "Record Passport Travel Context", "description": "Embark on a journey of seamless orchestration between humans and AI. This endpoint securely logs the travel context of a Passport within an organization, ensuring that each step is accounted for with precision and trust.", "operationId": "recordPassportTravelContext", "tags": [ "Passport", "Context" ], "x-code-hash": "b6b669eb54ad7d78", "x-generated-at": "2026-04-11T02:00:23.162Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "The decentralized identifier for the Passport" }, "context": { "type": "object", "description": "Additional context data related to the travel", "properties": { "destination": { "type": "string", "description": "The travel destination" }, "purpose": { "type": "string", "description": "Purpose of the travel" } }, "required": [ "destination", "purpose" ] } }, "required": [ "passport_did" ] }, "examples": { "record_travel_to_acme_hq": { "summary": "Record Travel to Acme HQ", "description": "Record context for a Passport traveling to Acme Corporation's headquarters.", "value": { "passport_did": "did:example:123456789abcdefghi", "context": { "destination": "Acme HQ", "purpose": "Annual Strategy Meeting" } } } } } } }, "responses": { "201": { "description": "The travel context was successfully recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "context_id": { "type": "string", "description": "Unique identifier for the recorded context" }, "passport_did": { "type": "string", "description": "The Passport DID associated with the context" }, "recorded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the context was recorded" } } }, "examples": { "default": { "summary": "Example", "value": { "context_id": "cp_travel_001", "passport_did": "did:example:123456789abcdefghi", "recorded_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/missing-field", "title": "Missing required field", "status": 400, "detail": "passport_did is required", "errors": [ { "field": "passport_did", "code": "REQUIRED_FIELD_MISSING", "message": "passport_did is required" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/unauthorized", "title": "Delegation required", "status": 401, "detail": "Delegation required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/forbidden", "title": "Access Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "500": { "description": "Internal server error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passport/context/merchant-whitelist": { "post": { "summary": "Whitelist merchants for passport interactions", "description": "Enlist merchants to interact with a passport holder, ensuring trusted exchanges within the HUMAN ecosystem. This process empowers organizations to manage merchant relationships securely and efficiently, leveraging cryptographic identities.", "operationId": "addMerchantToWhitelist", "tags": [ "Passport", "Merchant" ], "x-code-hash": "9b94f4328dee3405", "x-generated-at": "2026-04-11T02:00:32.910Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "Decentralized Identifier for the passport holder" }, "merchant_id": { "type": "string", "description": "Unique identifier for the merchant" } }, "required": [ "passport_did", "merchant_id" ] }, "examples": { "whitelisting_example": { "summary": "Whitelisting Example", "description": "An example of whitelisting a merchant for a passport holder", "value": { "passport_did": "did:human:123456789abcdefghi", "merchant_id": "merchant_987654321" } } } } } }, "responses": { "201": { "description": "Merchant successfully whitelisted for the passport holder", "content": { "application/json": { "schema": { "type": "object", "properties": { "whitelist_entry_id": { "type": "string", "description": "Unique identifier for the whitelist entry" }, "passport_did": { "type": "string", "description": "Decentralized Identifier for the passport holder" }, "merchant_id": { "type": "string", "description": "Unique identifier for the merchant" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the whitelist entry was last updated" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication required to access this resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please authenticate to access this resource." } } } } } }, "500": { "description": "A server error occurred, please try again later", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/server-error", "title": "Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/vault/:entityDid/export": { "get": { "summary": "Export encrypted documents from vault", "description": "Unveil the cryptic treasures stored within your vault by exporting encrypted documents tied to an entity's cryptographic identity. This endpoint empowers organizations, like 'acme', to effortlessly migrate their secured data while maintaining the sanctity of their information.", "operationId": "exportVaultDocuments", "tags": [ "Vault", "DataMigration" ], "x-code-hash": "73fbe36c74131fe3", "x-generated-at": "2026-04-09T21:18:03.483Z", "responses": { "200": { "description": "Successfully exported documents, returned as a structured list of encrypted entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "required": [ "doc_id", "namespace", "collection", "ciphertext", "iv" ], "properties": { "doc_id": { "type": "string" }, "namespace": { "type": "string" }, "collection": { "type": "string" }, "ciphertext": { "type": "string", "description": "Base64 encoded ciphertext of the document" }, "iv": { "type": "string", "description": "Base64 encoded initialization vector" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "examples": { "successful_export_example": { "summary": "Successful export example", "description": "Example of successfully exporting documents for an entity.", "value": { "documents": [ { "doc_id": "doc123", "namespace": "acme-invoices", "collection": "2023", "ciphertext": "c3VwZXJzZWNyZXRkYXRh", "iv": "aW5pdHZlY3Rvcg==", "metadata": { "created_by": "agent007", "tags": [ "finance", "confidential" ] } } ] } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_did_example": { "summary": "Malformed DID example", "description": "Illustrates an error when the entity DID format is incorrect.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Bad Request", "status": 400, "detail": "The entity DID provided is malformed. Please ensure it follows the correct format." } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_example": { "summary": "Missing authentication example", "description": "Shows what happens when no Passport token is provided.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid. Please provide a valid Passport token." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied_example": { "summary": "Access denied example", "description": "Demonstrates a scenario where access is denied due to lack of permissions.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this entity's vault. Verify your access rights with your system administrator." } } } } } }, "404": { "description": "The specified entity's vault could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "entity_not_found_example": { "summary": "Entity not found example", "description": "Details the response when an entity DID does not exist.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The entity DID referenced does not exist. Please verify the DID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server error example", "description": "Illustrates a generic server error response.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/vault/:entityDid/migrate-in": { "post": { "summary": "Migrate encrypted documents into vault", "description": "Unlock the power of secure document storage by migrating encrypted data into the HUMAN vault. This process ensures that your data remains protected and easily accessible, maintaining integrity through our distributed ledger.", "operationId": "migrateInToVault", "tags": [ "Vault", "Migration" ], "x-code-hash": "b6aebd92221c2b88", "x-generated-at": "2026-04-09T21:18:22.116Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "doc_id": { "type": "string", "format": "uuid" }, "namespace": { "type": "string" }, "collection": { "type": "string" }, "ciphertext": { "type": "string", "description": "Base64-encoded encrypted document content" }, "iv": { "type": "string", "description": "Base64-encoded 12-byte initialization vector" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "doc_id", "namespace", "collection", "ciphertext", "iv" ] } } }, "required": [ "documents" ] }, "examples": { "migrate_encrypted_invoices": { "summary": "Migrate encrypted invoices", "description": "Migrating a batch of encrypted invoices for the 'acme' organization", "value": { "documents": [ { "doc_id": "123e4567-e89b-12d3-a456-426614174000", "namespace": "acme-invoices", "collection": "2023", "ciphertext": "U2FsdGVkX1...", "iv": "YWJjZGVmZ2hpamtsbW5vcA==", "metadata": { "uploadedBy": "finance-agent", "timestamp": "2023-10-01T12:34:56Z" } } ] } } } } } }, "responses": { "201": { "description": "Documents successfully migrated into the vault", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "inserted": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "status", "inserted", "total" ] }, "examples": { "successful_migration": { "summary": "Successful migration", "value": { "status": "completed", "inserted": 1, "total": 1 } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_documents_array": { "summary": "Missing documents array", "value": { "type": "https://api.haio.run/errors/missing-documents", "title": "Bad Request", "status": 400, "detail": "documents array is required and must not be empty", "errors": [ { "field": "documents", "code": "REQUIRED_FIELD_MISSING", "message": "documents array is required and must not be empty" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_token": { "summary": "Missing authentication token", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication token is missing or invalid" } } } } } }, "403": { "description": "Forbidden access due to lack of permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission denied", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to migrate documents for this entity" } } } } } }, "404": { "description": "Entity not found, possibly due to an incorrect DID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "entity_not_found": { "summary": "Entity not found", "value": { "type": "https://api.haio.run/errors/entity-not-found", "title": "Not Found", "status": 404, "detail": "The specified entity DID does not exist" } } } } } }, "500": { "description": "Server error while processing the migration", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_insertion_error": { "summary": "Database insertion error", "value": { "type": "https://api.haio.run/errors/vault-migrate-in-failed", "title": "Vault migrate-in failed", "status": 500, "detail": "An error occurred while inserting documents into the vault" } } } } } } } } }, "/v1/vault/:entityDid/migrate": { "post": { "summary": "Migrate Documents Between Vaults", "description": "Embark on a journey to securely migrate your documents from one vault to another, ensuring data integrity and provenance tracking. This endpoint empowers organizations to seamlessly transition their data to a new storage destination, enhancing operational flexibility and resilience.", "operationId": "postVaultEntityDidMigrate", "tags": [ "Vault", "Migration" ], "x-code-hash": "99a7f0902369a194", "x-generated-at": "2026-04-09T21:18:39.495Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_connector_id": { "type": "string", "description": "Identifier of the target connector, e.g., 'human-cloud-vault'." }, "target_endpoint": { "type": "string", "description": "Base URL of the target vault API, e.g., 'https://api.example.com/v1/vault'." }, "target_token": { "type": "string", "description": "Authorization token for the target vault. Optional if provided in the Authorization header." }, "dry_run": { "type": "boolean", "description": "When true, simulates migration without actual data transfer." } }, "required": [ "target_connector_id", "target_endpoint" ] }, "examples": { "migrate_to_acme_vault": { "summary": "Migrate to Acme Vault", "description": "Migrate documents to Acme Corp's vault with a dry run.", "value": { "target_connector_id": "acme-vault", "target_endpoint": "https://vault.acme.com/api/v1/vault", "target_token": "securetoken123", "dry_run": true } } } } } }, "responses": { "200": { "description": "Documents successfully migrated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "completed" }, "migrated": { "type": "integer", "example": 42 }, "message": { "type": "string", "example": "Documents migrated successfully." } } }, "examples": { "default": { "summary": "Example", "value": { "status": "completed", "migrated": 42, "message": "Documents migrated successfully." } } } } } }, "400": { "description": "Invalid request due to missing or incorrect data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "target_connector_id is required (e.g. human-cloud-vault).", "errors": [ { "field": "target_connector_id", "code": "REQUIRED_FIELD_MISSING", "message": "target_connector_id is required (e.g. human-cloud-vault)." } ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "target_token or Authorization header required for target vault auth." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to migrate data for this entity." } } } } } }, "404": { "description": "Entity or connector not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Connector 'acme-vault' not found in ConnectorRegistry." } } } } } }, "500": { "description": "Internal server error during migration", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Unexpected error occurred during migration." } } } } } } } } }, "/v1/vault/access-grants": { "post": { "summary": "Create or Update Vault Access Grant", "description": "Orchestrate secure access to organizational vaults by creating or updating access grants. This endpoint ensures that only authenticated users can grant themselves access, reinforcing security by tying cryptographic identity to vault permissions.", "operationId": "createOrUpdateVaultAccessGrant", "tags": [ "Access Management", "Security" ], "x-code-hash": "9679085a3c59b803", "x-generated-at": "2026-04-09T21:18:58.309Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vault_entity_did": { "type": "string", "description": "Decentralized identifier of the vault entity (organization)" }, "member_did": { "type": "string", "description": "Decentralized identifier of the member requesting access" }, "encrypted_mvk": { "type": "string", "description": "Base64-encoded encrypted master vault key" }, "iv": { "type": "string", "description": "Base64-encoded initialization vector (12 bytes)" } }, "required": [ "vault_entity_did", "member_did", "encrypted_mvk", "iv" ] }, "examples": { "self-grant_access": { "summary": "Self-Grant Access", "description": "A member of Acme Corp granting themselves access to the vault", "value": { "vault_entity_did": "did:example:acme-corp", "member_did": "did:example:john-doe", "encrypted_mvk": "U2FsdGVkX1+abc123456=", "iv": "QUJDREVGRw==" } } } } } }, "responses": { "201": { "description": "Access grant successfully created or updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Indicates successful creation or update of the access grant" } } }, "examples": { "default": { "summary": "Example", "value": { "ok": true } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/required-fields-missing", "title": "Missing Required Fields", "status": 400, "detail": "vault_entity_did, member_did, encrypted_mvk, iv are required", "errors": [ { "field": "body", "code": "REQUIRED_FIELD_MISSING", "message": "vault_entity_did, member_did, encrypted_mvk, iv are required" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Forbidden action due to permissions mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-member", "title": "Forbidden", "status": 403, "detail": "You must be a member of the org to create an access grant for its vault" } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/vault/access-grants/:orgDid": { "get": { "summary": "Retrieve Organization Vault Access Grant", "description": "Fetches the encrypted master vault key (MVK) for a specific organization. This endpoint empowers human agents to securely access their organization's data vault by retrieving a cryptographically secure key, ensuring both access and privacy.", "operationId": "getVaultAccessGrant", "tags": [ "Vault", "AccessControl" ], "x-code-hash": "61d415ad19a5393e", "x-generated-at": "2026-04-09T21:19:16.646Z", "responses": { "200": { "description": "Successfully retrieved the encrypted master vault key and its initialization vector.", "content": { "application/json": { "schema": { "type": "object", "properties": { "encrypted_mvk": { "type": "string", "description": "Base64-encoded ciphertext of the master vault key." }, "iv": { "type": "string", "description": "Base64-encoded initialization vector for the encrypted MVK." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the access grant was created." } }, "required": [ "encrypted_mvk", "iv", "created_at" ] }, "examples": { "successful_retrieval_of_access_grant": { "summary": "Successful retrieval of access grant", "description": "An agent retrieves their organization's encrypted master vault key for secure operations.", "value": { "encrypted_mvk": "Q2hhcmxlc1RpbWVzVGhlQmVzdE9mVGltZXM=", "iv": "c2VjdXJlSW5pdFZlY3Rvcg==", "created_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_organization_did": { "summary": "Invalid organization DID", "description": "The provided organization DID is not valid.", "value": { "type": "https://example.com/probs/invalid-param", "title": "Invalid Parameter", "status": 400, "detail": "The organization DID provided is not in a valid format. Please ensure the DID follows the correct structure.", "errors": [ "Invalid DID format for orgDid" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "description": "The user attempted to access a resource without providing a delegation token.", "value": { "type": "https://example.com/probs/missing-delegation", "title": "Delegation Required", "status": 401, "detail": "Delegation is required to access the vault. Please include a valid delegation token in your request." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_actor": { "summary": "Unauthorized actor", "description": "The actor does not have permission to access the specified organization's vault.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "The actor is not authorized to access this organization's vault. Please check your permissions and try again." } } } } } }, "404": { "description": "Not Found when the vault access grant does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_grant_not_found": { "summary": "Access grant not found", "description": "The specified vault access grant could not be found for the organization and actor.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "No vault access grant found for the provided organization and actor DID. Verify the DIDs and try again." } } } } } }, "500": { "description": "Internal Server Error when an unexpected condition was encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "An unexpected error occurred on the server while processing the request.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/vault/:entityDid/:namespace/:collection": { "post": { "summary": "Store Encrypted Document Securely", "description": "Embark on a journey of secure document storage with our vault endpoint. This API endpoint enables you to safely store encrypted documents, ensuring that sensitive data is guarded with precision. By using a cryptographic identity, it maintains integrity and traceability, making it indispensable for organizations like 'acme' that require robust data protection.", "operationId": "storeEncryptedDocument", "tags": [ "Vault", "Security" ], "x-code-hash": "e4cc892611e4a5c0", "x-generated-at": "2026-04-10T00:56:10.022Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ciphertext": { "type": "string", "description": "The encrypted document content, encoded in base64." }, "iv": { "type": "string", "description": "The initialization vector for the encryption, encoded in base64 and must decode to 12 bytes." }, "metadata": { "type": "object", "description": "Optional metadata; each value is arbitrary JSON (`Record`) stored as JSONB — not limited to strings.", "additionalProperties": true } }, "required": [ "ciphertext", "iv" ] }, "examples": { "encrypt_invoice": { "summary": "Encrypt Invoice", "description": "An example of storing an encrypted invoice document.", "value": { "ciphertext": "c3VwZXJzZWNyZXRjb250ZW50", "iv": "dGVzdGluaXQxMjM=", "metadata": { "documentType": "invoice", "organization": "acme", "date": "2023-10-05" } } } } } } }, "responses": { "201": { "description": "Document stored successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc_id": { "type": "string", "description": "The unique identifier for the stored document." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the document was stored." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request - The request body was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized - Authentication failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden - Insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found - Entity or collection does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "summary": "Retrieve vault document metadata", "description": "Explore the labyrinth of your digital vault by retrieving only the metadata of documents within a specified collection. This endpoint empowers you to efficiently navigate and manage your document collections without exposing sensitive details.", "operationId": "getVaultDocumentMetadata", "tags": [ "Vault", "Documents", "Metadata" ], "x-code-hash": "37d587f8f446825d", "x-generated-at": "2026-04-10T00:56:22.696Z", "responses": { "200": { "description": "Successfully retrieved document metadata for the specified vault collection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "metadata_json": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "standard_metadata_retrieval": { "summary": "Standard metadata retrieval", "description": "An example response showing metadata for documents in a vault collection.", "value": { "data": [ { "id": "doc123", "metadata_json": { "title": "Invoice" }, "created_at": "2023-10-05T12:34:56Z", "updated_at": "2023-10-06T13:45:07Z" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Invalid request due to malformed input or parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid cursor example", "description": "An error response when the cursor is invalid.", "value": { "type": "https://humanprotocol.io/problem/invalid-cursor", "title": "Invalid Pagination Cursor", "status": 400, "detail": "The provided pagination cursor is invalid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "valid cursor token", "received": "abc123" } ] } } } } } }, "401": { "description": "Authentication required or failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized access example", "description": "An error response for unauthorized access.", "value": { "type": "https://humanprotocol.io/problem/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access is denied due to invalid credentials. Please provide valid authentication details." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden access example", "description": "An error response when access is forbidden.", "value": { "type": "https://humanprotocol.io/problem/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please check your access rights." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not found example", "description": "An error response when the requested vault or document collection does not exist.", "value": { "type": "https://humanprotocol.io/problem/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested collection or entity does not exist. Please verify the entityDid, namespace, and collection." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server error example", "description": "A generic error response for server issues.", "value": { "type": "https://humanprotocol.io/problem/internal-error", "title": "Internal Server Error", "status": 500, "detail": "Something went wrong on our end. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/vault/:entityDid/:namespace/:collection/:docId": { "get": { "summary": "Retrieve an encrypted document from vault", "description": "This endpoint dives into the depths of the HUMAN vault to retrieve an encrypted document, ensuring secure data retrieval for your organization. It exists to seamlessly bridge the gap between secure storage and access, allowing authorized users to fetch their critical documents without compromising on security.", "operationId": "getVaultDocument", "tags": [ "Vault", "Documents" ], "x-code-hash": "db732ed98ddcab52", "x-generated-at": "2026-04-09T21:19:59.396Z", "responses": { "200": { "description": "The encrypted document was retrieved successfully, including its metadata and creation timestamps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ciphertext": { "type": "string", "description": "The base64-encoded ciphertext of the document." }, "iv": { "type": "string", "description": "The base64-encoded initialization vector used for encryption." }, "metadata": { "type": "object", "description": "Additional metadata about the document.", "additionalProperties": true }, "wrapped_keys": { "type": "array", "items": { "type": "object" }, "description": "Array of wrapped keys used for decryption." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the document was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the document was last updated." } } }, "examples": { "existing_document_retrieval": { "summary": "Existing Document Retrieval", "description": "Retrieving an encrypted document for invoice processing in the Acme organization.", "value": { "ciphertext": "c29tZSBlbmNvZGVkIGNpcGhlcnRleHQ=", "iv": "ZGVtb25zdHJhdGlvbml2", "metadata": { "document_type": "invoice", "processing_status": "pending" }, "wrapped_keys": [], "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-15T12:00:00Z" } } } } } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_document_id_format": { "summary": "Invalid Document ID Format", "description": "The document ID provided does not conform to UUID format.", "value": { "type": "/errors/invalid-request", "title": "Invalid Request Format", "status": 400, "detail": "The document ID must be in UUID format. Please verify your input." } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request was made without providing valid authentication credentials.", "value": { "type": "/errors/unauthorized", "title": "Authentication Required", "status": 401, "detail": "Missing or invalid credentials. Please authenticate and try again." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user does not have permissions to access the requested document.", "value": { "type": "/errors/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have the necessary permissions to access this document." } } } } } }, "404": { "description": "The document specified by the request does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "document_not_found": { "summary": "Document Not Found", "description": "The document ID does not correspond to any stored document.", "value": { "type": "/errors/not-found", "title": "Document Not Found", "status": 404, "detail": "No document found with the specified ID. Please check the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred during document retrieval.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } }, "delete": { "summary": "Remove a document from the vault", "description": "In the HUMAN ecosystem, deleting a document is akin to erasing a chapter from a ledger. This endpoint allows users to surgically remove artifacts from their vault, ensuring that only the most relevant data persists, thus maintaining a pristine and efficient data environment.", "operationId": "deleteVaultDocument", "tags": [ "Data Management", "Vault" ], "x-code-hash": "6ea04b5199ede61b", "x-generated-at": "2026-04-09T21:20:51.781Z", "responses": { "204": { "description": "The document was successfully deleted. No content is returned on success as the document is permanently removed.", "content": { "application/json": { "examples": { "successful_deletion": { "summary": "Successful deletion", "description": "Illustrates a successful delete operation where the document is removed from the vault.", "value": null } } } } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_uuid": { "summary": "Invalid UUID", "description": "The document ID provided is not a valid UUID.", "value": { "type": "https://example.com/probs/invalid-uuid", "title": "Invalid Document ID", "status": 400, "detail": "The document ID 'abc123' is not a valid UUID.", "errors": [ "Ensure the document ID is a valid UUID." ] } } } } } }, "401": { "description": "Authentication credentials were not provided or are invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "User tried accessing with invalid credentials.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "The user does not have permission to delete the document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_operation": { "summary": "Forbidden operation", "description": "User lacks permission to delete the document.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to delete this document. Contact your administrator for access." } } } } } }, "404": { "description": "The document was not found in the vault.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "document_not_found": { "summary": "Document not found", "description": "The specified document ID does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Document Not Found", "status": 404, "detail": "The document with ID 'f47ac10b-58cc-4372-a567-0e02b2c3d479' was not found in the vault." } } } } } }, "500": { "description": "A server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "The server encountered an unexpected condition.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while attempting to delete the document. Please try again later." } } } } } } } } }, "/v1/vault/:entityDid/:namespace/:collection/:docId/share": { "patch": { "summary": "Share Access to Vault Document", "description": "Empower collaboration by securely sharing access to a vault document with another entity. This endpoint ensures that data sharing is both secure and traceable, leveraging the HUMAN platform's cryptographic identity and provenance tracking.", "operationId": "shareVaultDocumentAccess", "tags": [ "Vault", "Sharing" ], "x-code-hash": "2d428296a87b08d0", "x-generated-at": "2026-04-09T21:20:38.668Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_did": { "type": "string", "description": "Decentralized Identifier of the recipient entity." }, "wrapped_dek": { "type": "string", "description": "Base64-encoded wrapped Data Encryption Key for secure document access." }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional expiration date and time for the shared access." } }, "required": [ "recipient_did", "wrapped_dek" ] }, "examples": { "share_document_access": { "summary": "Share Document Access", "description": "Sharing document access with a recipient using a wrapped encryption key.", "value": { "recipient_did": "did:human:123abc", "wrapped_dek": "U2FsdGVkX1+E5V5bW7b5==", "expires_at": "2024-12-31T23:59:59Z" } } } } } }, "responses": { "200": { "description": "Successfully shared access to the vault document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "doc_id": { "type": "string" } } }, "examples": { "successful_share": { "summary": "Successful Share", "value": { "ok": true, "doc_id": "doc1234" } } } } } }, "400": { "description": "Invalid input data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_required_fields": { "summary": "Missing Required Fields", "value": { "type": "https://docs.human.api/problems/invalid-input", "title": "Invalid Request Body", "status": 400, "detail": "recipient_did and wrapped_dek are required", "errors": [ { "field": "body", "code": "REQUIRED_FIELD_MISSING", "message": "recipient_did and wrapped_dek are required" } ] } } } } } }, "401": { "description": "Unauthorized access attempt", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_authentication": { "summary": "Invalid Authentication", "value": { "type": "https://docs.human.api/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://docs.human.api/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to share this document." } } } } } }, "404": { "description": "Document not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "document_not_found": { "summary": "Document Not Found", "value": { "type": "https://docs.human.api/problems/not-found", "title": "Not Found", "status": 404, "detail": "The specified vault document was not found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "value": { "type": "https://docs.human.api/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "summary": "Revoke Document Sharing with Recipient", "description": "In the tapestry of digital collaboration, sharing is key, but sometimes ties need to be severed. This endpoint allows you to revoke access to a document for a specific recipient, ensuring only the right eyes see your data. It's a safeguard for when sharing needs to be undone without a trace.", "operationId": "deleteVaultDocumentShare", "tags": [ "Vault" ], "x-code-hash": "877623a5439678c6", "x-generated-at": "2026-04-12T16:52:55.124Z", "responses": { "200": { "description": "The document share was successfully revoked for the specified recipient.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "doc_id": { "type": "string", "format": "uuid" } }, "required": [ "ok", "doc_id" ] }, "examples": { "successful_revocation_example": { "summary": "Successful Revocation Example", "description": "Revoking document share for recipient with a valid request.", "value": { "ok": true, "doc_id": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "400": { "description": "The request was malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_query_parameter": { "summary": "Missing Query Parameter", "description": "The request failed because the 'recipient_did' query parameter was missing.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The recipient_did query parameter is required.", "errors": [ { "field": "recipient_did", "code": "REQUIRED_QUERY_PARAM_MISSING", "message": "recipient_did query parameter is required", "expected": "non-empty string (URL-encoded DID)", "received": "" } ] } } } } } }, "401": { "description": "The user is not authenticated.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "The request failed due to missing authentication credentials.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication credentials were not provided. Please include a valid token." } } } } } }, "403": { "description": "The user does not have permission to revoke this share.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "The user attempted to revoke a share without the necessary permissions.", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to revoke this share. Ensure you have 'vault:write' access." } } } } } }, "404": { "description": "The specified document was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "document_not_found": { "summary": "Document Not Found", "description": "The document specified by docId does not exist.", "value": { "type": "https://example.com/probs/document-not-found", "title": "Document Not Found", "status": 404, "detail": "The document with ID 123e4567-e89b-12d3-a456-426614174000 could not be found." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try your request again later." } } } } } } } } }, "/v1/events/ingest": { "post": { "summary": "Ingest Event Data with Verification", "description": "Harness the power of Human-AI orchestration by securely ingesting event data into the HUMAN platform. This endpoint ensures data integrity through signature verification and timestamps, safeguarding against replay attacks and unauthorized access.", "operationId": "ingestEvent", "tags": [ "Event Management", "Data Ingestion" ], "x-code-hash": "4fb78eebc60a008d", "x-generated-at": "2026-04-01T22:43:50.119Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "The type of event, formatted in dot-notation lowercase (e.g., billing.invoice.paid)" }, "source_connector_id": { "type": "string", "description": "Identifier of the source connector sending the event" }, "raw_payload": { "type": "object", "description": "The raw data payload of the event" }, "normalized_payload": { "type": "object", "description": "The normalized version of the event data, if applicable" }, "source_did": { "type": "string", "description": "Decentralized identifier of the source" }, "delegation_chain": { "type": "array", "items": { "type": "string" }, "description": "Chain of delegations for authorization" }, "subject": { "type": "string", "description": "The subject or entity to which the event pertains" }, "event_timestamp": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer" } ], "description": "The timestamp of the event in ISO 8601 or Unix seconds" }, "verification_status": { "type": "string", "description": "The verification status as asserted by the connector" } }, "required": [ "event_type", "source_connector_id", "raw_payload" ] }, "examples": { "invoice_payment_event": { "summary": "Invoice Payment Event", "description": "An event representing a paid invoice from the 'acme' organization", "value": { "event_type": "billing.invoice.paid", "source_connector_id": "acme_invoice_system", "raw_payload": { "invoice_id": "INV-12345", "amount": 1500, "currency": "USD" }, "event_timestamp": "2023-10-10T14:48:00Z" } } } } } }, "responses": { "201": { "description": "The event has been successfully ingested and stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string" }, "content_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example", "value": { "event_id": "123e4567-e89b-12d3-a456-426614174000", "content_hash": "abc123xyz789", "created_at": "2023-10-10T14:48:00Z" } } } } } }, "400": { "description": "Bad Request due to invalid JSON or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humandao.org/errors/validation", "title": "Invalid Request", "status": 400, "detail": "Request body must be valid JSON and include required fields.", "errors": [ { "field": "event_type", "code": "INVALID_EVENT_TYPE", "message": "event_type must be dot-notation lowercase (e.g., billing.invoice.paid)", "received": "123PAY" } ] } } } } } }, "401": { "description": "Unauthorized access due to failed signature verification.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humandao.org/errors/webhook-signature-invalid", "title": "Webhook Signature Verification Failed", "status": 401, "detail": "The webhook signature does not match the registered signing secret, or the timestamp has expired." } } } } } }, "422": { "description": "Event Timestamp Expired, indicating a potential replay attack.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humandao.org/errors/event-replay", "title": "Event Timestamp Expired", "status": 422, "detail": "Event is 700s old, exceeding the 600s window. Possible replay attack." } } } } } }, "500": { "description": "Internal Server Error due to unexpected server issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humandao.org/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "Failed to store event due to server error." } } } } } } } } }, "/v1/events/emit": { "post": { "summary": "Emit and log an event in the system", "description": "This endpoint allows the orchestration of human and AI interactions by emitting events that are securely logged and tracked. It ensures the integrity and provenance of actions within the HUMAN protocol by leveraging cryptographic proofs and distributed ledger technology. This guarantees transparency and trust in the interactions processed by the platform.", "operationId": "emitEvent", "tags": [ "Events", "Logging" ], "x-code-hash": "8ce51dfef7fc38e6", "x-generated-at": "2026-03-24T21:46:00.686Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "The type of event being emitted. This is a required field." }, "payload": { "type": "object", "description": "Arbitrary JSON object containing details relevant to the event." }, "subject": { "type": "string", "description": "The subject related to this event, often a DID or other identifier." }, "emitter_agent_did": { "type": "string", "description": "The DID of the agent emitting the event; if provided, the event will be signed." } }, "required": [ "event_type" ] }, "examples": { "invoice_processed_event": { "summary": "Invoice Processed Event", "description": "An event indicating an invoice has been processed by an agent within the 'acme' organization.", "value": { "event_type": "invoice.processed", "payload": { "invoice_id": "INV-123456", "amount": "1500.00", "currency": "USD" }, "subject": "did:example:123456789", "emitter_agent_did": "did:example:agent:acme" } } } } } }, "responses": { "201": { "description": "Event has been successfully emitted and logged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string", "description": "A unique identifier for the emitted event." }, "content_hash": { "type": "string", "description": "A hash representing the content of the event for integrity verification." }, "signed": { "type": "boolean", "description": "Indicates if the event was signed by an agent." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the event was created." } } }, "examples": { "default": { "summary": "Example", "value": { "event_id": "evt-5f6a3b4d2e7c", "content_hash": "abc123def456", "signed": true, "created_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Bad Request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/invalid-input", "title": "Invalid JSON Input", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "received": "unparseable" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Org DID required in delegation." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Insufficient permissions to emit event." } } } } } }, "404": { "description": "Not Found - the requested resource could not be located.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal Server Error due to a problem on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to store event due to server error." } } } } } } } } }, "/v1/events/stream": { "get": { "summary": "Stream Provenance Events via SSE", "description": "Dive into the heartbeat of your organization with a real-time stream of provenance events. This endpoint exists to ensure transparency and traceability, allowing you to monitor the flow of data and actions within your systems as they happen. Embrace the power of live data and make informed decisions with every beat.", "operationId": "getEventsStream", "tags": [ "Events", "Provenance" ], "x-code-hash": "04e0d4b6abac1097", "x-generated-at": "2026-03-24T21:46:19.647Z", "responses": { "200": { "description": "Returns a stream of provenance events in real-time, enabling the subscriber to stay updated with the latest activities and data changes.", "content": { "application/json": { "schema": { "type": "string", "format": "text/event-stream" }, "examples": { "live_stream_of_events": { "summary": "Live Stream of Events", "description": "A continuous stream of events for an organization monitoring data provenance.", "value": "event: event\ndata: {\"event_id\": \"evt-1234\", \"event_type\": \"data_update\", \"created_at\": \"2023-10-01T12:00:00Z\", \"org_did\": \"did:example:acme-org\"}\n\n" } } } } }, "400": { "description": "The request could not be understood by the server due to malformed syntax or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing Org DID", "description": "Example of a failed request due to missing organization DID in the authorization header.", "value": { "type": "https://human-protocol.org/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "Org DID required for streaming events.", "errors": [ { "field": "authorization", "code": "ORG_DID_REQUIRED", "message": "Org DID required", "received": "no delegation" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Example of a failed request due to missing or invalid authentication credentials.", "value": { "type": "https://human-protocol.org/probs/auth-error", "title": "Authentication Error", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "The request was a valid request, but the server is refusing to respond to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Example of a failed request due to lack of necessary permissions.", "value": { "type": "https://human-protocol.org/probs/permission-error", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found but may be available in the future.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Example of a failed request due to the requested endpoint being unavailable.", "value": { "type": "https://human-protocol.org/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested event stream endpoint does not exist." } } } } } }, "500": { "description": "A generic error message, given when an unexpected condition was encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Example of a failed request due to a server-side issue.", "value": { "type": "https://human-protocol.org/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/events/:id": { "get": { "summary": "Retrieve detailed event information", "description": "This endpoint unlocks the story behind an event by fetching its comprehensive details using its unique identifier. It's designed to ensure that organizations can trace back any event within their operations, maintaining a seamless record of activities with accountability and transparency.", "operationId": "getEventById", "tags": [ "Events", "Provenance" ], "x-code-hash": "9279c7f278cb8e9b", "x-generated-at": "2026-03-24T21:46:37.845Z", "responses": { "200": { "description": "Successfully retrieves the event details, providing insight into its occurrence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "description": "The unique identifier for the event." }, "orgDid": { "type": "string", "description": "Decentralized identifier of the organization." }, "timestamp": { "type": "string", "format": "date-time", "description": "The moment when the event was recorded." }, "details": { "type": "string", "description": "Narrative description of the event." } }, "required": [ "eventId", "orgDid", "timestamp", "details" ] }, "examples": { "event_retrieval_for_invoice_processing": { "summary": "Event retrieval for invoice processing", "description": "An event detailing the processing of an invoice by Acme Corporation.", "value": { "eventId": "evt-12345", "orgDid": "did:example:acme123", "timestamp": "2023-10-05T14:48:00.000Z", "details": "Invoice INV-001 processed successfully." } } } } } }, "400": { "description": "Invalid request parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_event_id": { "summary": "Invalid Event ID", "description": "A scenario where the provided event ID is malformed.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The event ID 'xyz' is not valid." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization": { "summary": "Missing Authorization", "description": "Attempt to access without providing authorization token.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization token is missing or invalid." } } } } } }, "403": { "description": "Access to the requested event is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Access attempt by unauthorized entity.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this event." } } } } } }, "404": { "description": "The specified event could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "event_not_found": { "summary": "Event Not Found", "description": "A situation where the event ID does not correspond to any existing records.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Event evt-98765 not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "A generic server-side failure during event retrieval.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/webhooks/subscriptions": { "post": { "summary": "Subscribe to Webhook Events for Your Organization", "description": "Imagine receiving only the events that matter most to your organization, seamlessly and securely. This endpoint allows you to subscribe to webhook events, ensuring your systems are always in sync with the latest updates from the HUMAN platform. It's designed for organizations looking to automate and streamline their workflows with precision.", "operationId": "createWebhookSubscription", "tags": [ "Webhooks", "Subscriptions" ], "x-code-hash": "6e15b4208d687945", "x-generated-at": "2026-03-31T03:39:32.573Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_pattern": { "type": "string", "description": "The pattern of events to subscribe to, using dot-notation.", "example": "billing.invoice.*" }, "target_url": { "type": "string", "description": "The destination URL where events will be delivered.", "format": "uri", "example": "https://webhooks.acme.com/events" }, "signing_secret": { "type": "string", "description": "Optional secret for signing webhook requests.", "example": "s3cr3t" }, "source_filter": { "type": "string", "description": "Optional filter for the event source.", "example": "source-123" }, "observability_profile": { "type": "string", "description": "Profile ID for observability settings.", "example": "obs-456" }, "metadata": { "type": "object", "description": "Additional metadata for the subscription.", "example": { "team": "finance", "project": "Quarterly Reports" } }, "audience": { "type": "string", "enum": [ "tenant_safe", "platform_internal" ], "description": "Defines who the subscription is intended for.", "example": "tenant_safe" } }, "required": [ "event_pattern", "target_url" ] }, "examples": { "acme_corp_subscription": { "summary": "Acme Corp Subscription", "description": "Acme Corp subscribing to all billing invoice events.", "value": { "event_pattern": "billing.invoice.*", "target_url": "https://webhooks.acme.com/events", "signing_secret": "supersecret", "metadata": { "team": "finance", "project": "Quarterly Reports" }, "audience": "tenant_safe" } } } } } }, "responses": { "201": { "description": "Webhook subscription successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "Unique identifier for the subscription.", "example": "sub-12345" }, "event_pattern": { "type": "string", "description": "The pattern of events subscribed to.", "example": "billing.invoice.*" }, "target_url": { "type": "string", "description": "The destination URL for events.", "example": "https://webhooks.acme.com/events" }, "signing_secret_provided": { "type": "boolean", "description": "Indicates if a signing secret was provided." }, "metadata": { "type": "object", "description": "Metadata associated with the subscription.", "example": { "team": "finance", "project": "Quarterly Reports" } } } }, "examples": { "successful_subscription": { "summary": "Successful Subscription", "description": "Response when Acme Corp successfully subscribes to webhook events.", "value": { "subscription_id": "sub-12345", "event_pattern": "billing.invoice.*", "target_url": "https://webhooks.acme.com/events", "signing_secret_provided": true, "metadata": { "team": "finance", "project": "Quarterly Reports" } } } } } } }, "400": { "description": "Validation errors occurred due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_url_example": { "summary": "Invalid URL Example", "description": "Occurs when the 'target_url' is not a valid URL.", "value": { "type": "https://docs.human.com/errors/validation", "title": "Invalid Request", "status": 400, "detail": "The 'target_url' field must be a valid URL.", "errors": [ { "field": "target_url", "code": "INVALID_URL", "message": "The 'target_url' must be a valid URL.", "received": "ftp://invalid-url.com" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization": { "summary": "Missing Authorization", "description": "Occurs when the Authorization header is missing.", "value": { "type": "https://docs.human.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization header missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to lacking necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Occurs when trying to create platform internal subscriptions without proper permissions.", "value": { "type": "https://docs.human.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Platform internal subscriptions require cloud:admin:global permission." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Occurs when the referenced resource does not exist.", "value": { "type": "https://docs.human.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified resource does not exist." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "Occurs when an unexpected error happens during request processing.", "value": { "type": "https://docs.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } }, "get": { "summary": "Retrieve active webhook subscriptions", "description": "This endpoint lets you explore the landscape of webhook subscriptions tied to your organization. By calling it, you can discover which events you're tracking in real-time, ensuring your applications remain in sync with the heartbeat of your business.", "operationId": "getWebhookSubscriptions", "tags": [ "Webhooks", "Subscriptions" ], "x-code-hash": "2092b3da949eacc2", "x-generated-at": "2026-03-31T03:39:54.261Z", "responses": { "200": { "description": "Successfully retrieved the list of active webhook subscriptions for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription" }, "orgDid": { "type": "string", "description": "Decentralized Identifier (DID) of the organization" }, "subscriptionType": { "type": "string", "description": "Type of the subscription" }, "active": { "type": "boolean", "description": "Status of the subscription" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the subscription was created" } }, "required": [ "id", "orgDid", "subscriptionType", "active", "createdAt" ] } }, "hasMore": { "type": "boolean", "description": "Indicates if there are more records to fetch" }, "limit": { "type": "integer", "description": "Maximum number of records returned" }, "cursor": { "type": "string", "description": "Cursor for the next set of records" } } }, "examples": { "successful_response_with_active_subscriptions": { "summary": "Successful response with active subscriptions", "description": "A response showing active webhook subscriptions for a specific organization.", "value": { "data": [ { "id": "sub_1234", "orgDid": "did:human:acme", "subscriptionType": "invoice.processed", "active": true, "createdAt": "2023-10-15T10:30:00Z" }, { "id": "sub_5678", "orgDid": "did:human:acme", "subscriptionType": "payment.received", "active": true, "createdAt": "2023-10-14T09:00:00Z" } ], "hasMore": false, "limit": 2, "cursor": "opaqueCursor123" } } } } } }, "400": { "description": "Bad request due to invalid input parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_error": { "summary": "Invalid cursor error", "description": "Occurs when the provided pagination cursor is not valid.", "value": { "type": "https://humanprotocol.org/errors/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The pagination cursor is invalid. Please use a cursor from a previous response.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authorization", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authorization_required": { "summary": "Authorization required", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization header is missing or invalid. Please provide a valid Org DID." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "The user does not have permission to access the requested resource.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to view webhook subscriptions. Please contact your administrator." } } } } } }, "404": { "description": "The requested resource was not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "No subscriptions found for the given criteria.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "No webhook subscriptions found for the specified organization." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "An error occurred on the server side.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/webhooks/subscriptions/:id": { "get": { "summary": "Retrieve webhook subscription details", "description": "Unlock the secrets of your organization's data flow by retrieving the details of a webhook subscription. This endpoint illuminates the path for authorized users to inspect the subscriptions tied to their cryptographic identity, ensuring data harmony between systems.", "operationId": "getWebhookSubscriptionById", "tags": [ "Webhooks", "Subscriptions" ], "x-code-hash": "53d1ee55fc8045d6", "x-generated-at": "2026-03-31T03:40:34.359Z", "responses": { "200": { "description": "A successful retrieval of the webhook subscription details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "The unique identifier of the subscription." }, "orgDid": { "type": "string", "description": "The decentralized identifier for the organization." }, "audience": { "type": "string", "description": "The audience this subscription is intended for." }, "endpoint": { "type": "string", "description": "The URL endpoint where the webhook is sent." } } }, "examples": { "successful_retrieval_example": { "summary": "Successful retrieval example", "description": "Fetching details of a webhook subscription for Acme Corporation.", "value": { "subscriptionId": "sub-12345", "orgDid": "did:human:acme", "audience": "platform_internal", "endpoint": "https://acme.com/hooks/invoice-updates" } } } } } }, "400": { "description": "Bad request due to malformed syntax or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_example": { "summary": "Malformed request example", "description": "Attempting to retrieve a subscription with an invalid ID format.", "value": { "type": "https://human.org/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The subscription ID format is incorrect. Please ensure the ID is a valid string." } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized access example", "description": "Accessing subscription details without valid authentication.", "value": { "type": "https://human.org/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Missing or invalid credentials. Please provide a valid Passport to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied_example": { "summary": "Permission denied example", "description": "Attempting to view a subscription without adequate permissions.", "value": { "type": "https://human.org/probs/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "This subscription is not visible with the current credentials. Ensure you have the 'cloud:admin:global' role." } } } } } }, "404": { "description": "Subscription not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not found example", "description": "Searching for a non-existent subscription ID.", "value": { "type": "https://human.org/probs/subscription-not-found", "title": "Subscription Not Found", "status": 404, "detail": "Subscription sub-99999 not found. Verify the subscription ID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server error example", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://human.org/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } }, "delete": { "summary": "Deactivate a webhook subscription", "description": "Effortlessly manage webhook subscriptions by deactivating them without losing valuable delivery history. This endpoint allows organizations to gracefully retire subscriptions, ensuring continuity and integrity of past interactions.", "operationId": "deleteWebhookSubscription", "tags": [ "Webhooks", "Subscriptions" ], "x-code-hash": "0b4f98d8b0316bf2", "x-generated-at": "2026-03-31T03:40:46.629Z", "responses": { "200": { "description": "The subscription was successfully deactivated, preserving the delivery history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "The unique identifier of the deactivated subscription." }, "active": { "type": "boolean", "description": "Indicates that the subscription is no longer active." }, "deactivated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the subscription was deactivated." } }, "required": [ "subscription_id", "active", "deactivated_at" ] }, "examples": { "successful_deactivation": { "summary": "Successful Deactivation", "description": "An example of successfully deactivating a subscription for an organization.", "value": { "subscription_id": "sub-12345", "active": false, "deactivated_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Request cannot be processed due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_input": { "summary": "Invalid Input", "value": { "type": "https://docs.acme.com/errors/invalid-input", "title": "Invalid input", "status": 400, "detail": "The subscription ID provided is not valid.", "errors": [ "Ensure the subscription ID is correctly formatted." ] } } } } } }, "401": { "description": "Authentication failed due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://docs.acme.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You do not have the necessary credentials to access this resource." } } } } } }, "403": { "description": "Permission denied to modify the subscription.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_modification": { "summary": "Forbidden Modification", "value": { "type": "https://docs.acme.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "This subscription cannot be modified with the current credentials.", "errors": [ "Ensure you have 'cloud:admin:global' capability." ] } } } } } }, "404": { "description": "The specified subscription could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "subscription_not_found": { "summary": "Subscription Not Found", "value": { "type": "https://docs.acme.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "Subscription sub-12345 not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://docs.acme.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/connectors/:connectorId/webhook-secret": { "put": { "summary": "Securely update connector webhook secret", "description": "In the ever-evolving world of digital interactions, ensuring secure communication is paramount. This endpoint allows organizations to update the signing secret for their connectors, reinforcing the security of webhook communications. It exists to ensure that data integrity and authenticity are maintained through cryptographic measures, allowing organizations to confidently interact with HUMAN's powerful orchestration capabilities.", "operationId": "updateConnectorWebhookSecret", "tags": [ "Connectors", "Security" ], "x-code-hash": "000e5d11df86af71", "x-generated-at": "2026-03-24T21:48:21.586Z", "responses": { "201": { "description": "The webhook secret was successfully updated, reinforcing security for future communications.", "content": { "application/json": {} } }, "400": { "description": "Bad request due to invalid input. Ensure all required fields are correct and the JSON is well-formed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication credentials. Ensure a valid delegation is provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden operation due to lack of necessary permissions. Ensure that the organization has the right capabilities to update secrets.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified connector was not found. Verify the connector ID and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error due to an unexpected condition. Try again later or contact support if the issue persists.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "summary": "Retrieve connector's webhook secret metadata", "description": "Unlock the orchestration potential of AI-human collaboration by fetching essential webhook secret metadata for a connector. This endpoint ensures secure and reliable communication between your services, safeguarding data integrity and authenticity.", "operationId": "getWebhookSecretMetadata", "tags": [ "Connectors", "Security" ], "x-code-hash": "7ee848effb6592c0", "x-generated-at": "2026-03-24T21:48:37.430Z", "responses": { "200": { "description": "Successfully retrieved webhook secret metadata for the specified connector.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connector_id": { "type": "string", "description": "The unique identifier of the connector." }, "org_did": { "type": "string", "description": "Decentralized Identifier (DID) of the organization." }, "active": { "type": "boolean", "description": "Indicates if the webhook secret is currently active." }, "max_age_seconds": { "type": "integer", "description": "The maximum age in seconds for the webhook secret." }, "header_name": { "type": "string", "description": "The HTTP header name used for passing the secret." }, "timestamp_header": { "type": "string", "description": "The HTTP header used for timestamp validation." }, "signing_secret": { "type": "string", "description": "The webhook signing secret, redacted for security reasons." }, "registered_at": { "type": "string", "format": "date-time", "description": "The date and time when the secret was registered." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the secret was last updated." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Org DID required", "errors": [ { "field": "authorization", "code": "ORG_DID_REQUIRED", "message": "Org DID required", "received": "no delegation" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found for the given connector ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No active ingest secret for connector invoice-processor" } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "summary": "Deactivate a Connector's Webhook Secret", "description": "In a world where data flows seamlessly, connectors play a crucial role in linking systems. This endpoint allows organizations to deactivate the webhook secret for a specific connector, enhancing security by disabling outdated or compromised integrations. By doing so, it ensures that the data shared through these connectors remains secure and controlled.", "operationId": "deactivateConnectorWebhookSecret", "tags": [ "Connectors", "Security" ], "x-code-hash": "96ccc295bdd0246d", "x-generated-at": "2026-03-24T21:48:51.671Z", "responses": { "200": { "description": "Successfully deactivated the webhook secret for the specified connector", "content": { "application/json": { "schema": { "type": "object", "properties": { "connector_id": { "type": "string" }, "active": { "type": "boolean" }, "deactivated_at": { "type": "string", "format": "date-time" } } }, "examples": { "webhook_secret_deactivation_success": { "summary": "Webhook Secret Deactivation Success", "description": "Successfully deactivating the webhook secret for connector ID 1234", "value": { "connector_id": "1234", "active": false, "deactivated_at": "2023-12-01T12:34:56Z" } } } } } }, "400": { "description": "Invalid request due to missing or malformed data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing Org DID", "description": "Attempting to deactivate without providing an organization DID", "value": { "type": "https://example.com/probs/validation", "title": "Validation Error", "status": 400, "detail": "Org DID required", "errors": [ { "field": "authorization", "code": "ORG_DID_REQUIRED", "message": "Org DID required", "received": "no delegation" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Access attempt with invalid credentials", "value": { "type": "https://example.com/probs/auth", "title": "Unauthorized", "status": 401, "detail": "Invalid or missing credentials. Ensure your access token is valid and retry." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Attempting to deactivate a webhook secret without appropriate permissions", "value": { "type": "https://example.com/probs/permissions", "title": "Forbidden", "status": 403, "detail": "You do not have permission to deactivate this webhook secret. Contact your administrator for access." } } } } } }, "404": { "description": "Connector not found or no active secret exists", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_not_found": { "summary": "Connector Not Found", "description": "Attempting to deactivate a webhook secret for a non-existent connector", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No active ingest secret for connector 1234. Check the connector ID and try again." } } } } } }, "500": { "description": "Unexpected server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An internal error occurred while processing the request", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/prompts/:key": { "get": { "summary": "Retrieve the active version of a prompt", "description": "In the dynamic world of prompts, accessing the latest version is crucial for keeping your applications in sync. This endpoint allows you to retrieve the active version of a specific prompt, ensuring that you are always working with the most current information. It supports both short keys and full URIs, making it versatile for various use cases.", "operationId": "getActivePromptVersion", "tags": [ "Prompts", "Versioning" ], "x-code-hash": "b706bd4eb563a704", "x-generated-at": "2026-03-24T21:49:30.880Z", "responses": { "200": { "description": "Successfully retrieves the active version of the specified prompt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "The active version identifier of the prompt." }, "content": { "type": "string", "description": "The content of the active prompt version." } } }, "examples": { "active_prompt_version_retrieval": { "summary": "Active prompt version retrieval", "description": "Retrieves the active version details for a prompt with a short key.", "value": { "version": "v2.3.1", "content": "Welcome to the new era of AI-driven orchestration." } } } } } }, "400": { "description": "Bad request due to malformed key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_key_example": { "summary": "Invalid Key Example", "description": "This example shows a response when the key provided is not properly formatted.", "value": { "type": "https://api.humanprotocol.org/problems/invalid-key", "title": "Invalid Key Format", "status": 400, "detail": "The provided key 'abcd123' is not in a recognizable format. Please ensure it is URL-encoded if necessary." } } } } } }, "401": { "description": "Unauthorized request due to missing delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "Shows the response when a delegation is not provided.", "value": { "type": "https://api.humanprotocol.org/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required to access this resource. Please provide a valid delegation token." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Response when the user does not have the necessary permissions.", "value": { "type": "https://api.humanprotocol.org/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "Your delegation does not include prompt:read:example-key. Contact your org admin to request this scope." } } } } } }, "404": { "description": "Prompt not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "prompt_not_found": { "summary": "Prompt Not Found", "description": "Response when the prompt key does not match any active prompt.", "value": { "type": "https://api.humanprotocol.org/problems/not-found", "title": "Not Found", "status": 404, "detail": "The prompt with key 'example-key' could not be found. Verify the key and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "Response for a generic server-side issue.", "value": { "type": "https://api.humanprotocol.org/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Incident ID: inc_1678901234567" } } } } } } } } }, "/v1/prompts/:key/versions": { "get": { "summary": "Retrieve versions of a specific prompt", "description": "Explore the evolutionary journey of your prompts by listing all their versions. This endpoint empowers organizations to track changes, ensuring clarity and accountability in modifications over time. Whether for audit purposes or creative exploration, understanding the version history is pivotal.", "operationId": "getPromptVersions", "tags": [ "Prompts", "Version Management" ], "x-code-hash": "2687de5748d99286", "x-generated-at": "2026-03-24T21:49:54.094Z", "responses": { "200": { "description": "A paginated list of prompt versions, providing insights into their historical changes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object" } }, "required": [ "version", "created_at" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "totalCount": { "type": "integer" } }, "required": [ "data", "limit", "cursorField", "totalCount" ] }, "examples": { "version_list_for_prompt": { "summary": "Version List for Prompt", "description": "A detailed look at all versions of the 'invoice-processing' prompt.", "value": { "data": [ { "version": "1.0", "created_at": "2023-07-21T15:03:01Z", "metadata": { "description": "Initial version for basic invoice processing." } }, { "version": "1.1", "created_at": "2023-08-05T10:22:15Z", "metadata": { "description": "Added support for multi-language invoices." } } ], "limit": 10, "cursorField": "version", "totalCount": 2 } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "description": "Occurs when a non-integer is provided for the limit parameter.", "value": { "type": "https://api.human/probs/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "The 'limit' parameter must be a positive integer." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "A request was made without the necessary delegation credentials.", "value": { "type": "https://api.human/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user lacks the necessary read permissions for the prompt.", "value": { "type": "https://api.human/probs/insufficient-scope", "title": "Insufficient Scope", "status": 403, "detail": "Your delegation does not include prompt:read:invoice-processing.", "errors": [ "prompt:read:invoice-processing" ] } } } } } }, "404": { "description": "Prompt not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "prompt_key_not_found": { "summary": "Prompt Key Not Found", "description": "The specified prompt key does not exist in the organization.", "value": { "type": "https://api.human/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "Prompt with key 'invoice-processing' not found." } } } } } }, "500": { "description": "Internal server error occurred while processing the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An example of an internal error when the server fails unexpectedly.", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/prompts/:key/versions/:version": { "get": { "summary": "Retrieve a specific prompt version", "description": "Uncover the rich history of your creative assets by retrieving a specific version of a prompt. This endpoint exists to empower organizations to track their content evolution, ensuring that every iteration is preserved and accessible for future reference.", "operationId": "getPromptVersion_1", "tags": [ "Prompts", "Versioning" ], "x-code-hash": "2836ec046fae4f36", "x-generated-at": "2026-03-24T21:50:16.981Z", "responses": { "200": { "description": "The requested version of the prompt was successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "The version identifier of the prompt." }, "content": { "type": "string", "description": "The content associated with the prompt version." }, "createdAt": { "type": "string", "format": "date-time", "description": "The timestamp when this version was created." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The version parameter is not a valid format. Ensure it follows semantic versioning." } } } } } }, "401": { "description": "Authentication error due to missing delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access prompt version. Please authenticate and try again." } } } } } }, "403": { "description": "Permission error due to insufficient scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/errors/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "Your delegation does not include prompt:read:invoice-processing. Please request additional permissions." } } } } } }, "404": { "description": "Not found error when the specified prompt or version does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The specified prompt version 'invoice-processing@1.0.0' does not exist. Check the key and version, or ensure it has been created." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. If the problem persists, contact support with incident ID inc_1698765432109." } } } } } } } } }, "/v1/prompts/:key/publish": { "post": { "summary": "Publish a new version of a prompt", "description": "Publishing prompts is at the heart of dynamic content orchestration within HUMAN. This endpoint allows you to release updates, ensuring your AI tasks are fueled with the latest and greatest instructions. It's not just about updates; it's about enhancing the AI-human collaboration with precision and clarity.", "operationId": "publishPromptVersion", "tags": [ "Prompts", "Publishing" ], "x-code-hash": "fe2b1343f62426d6", "x-generated-at": "2026-03-24T21:50:36.009Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "Semantic version of the prompt, e.g., '1.0.0'." }, "content": { "type": "string", "description": "The core text or body of the prompt." }, "meta": { "type": "object", "description": "Metadata about the prompt, such as namespace and ID." }, "input_schema": { "type": "object", "description": "Optional schema detailing expected input structure." } }, "required": [ "version", "content", "meta" ] }, "examples": { "initial_version_publish": { "summary": "Initial Version Publish", "description": "Publishing the first version of a new prompt for the 'acme' organization.", "value": { "version": "1.0.0", "content": "Welcome to the Acme AI platform!", "meta": { "namespace": "marketing", "id": "welcome-prompt" }, "input_schema": { "type": "object", "properties": { "user_name": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "The prompt version was successfully published.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promptUri": { "type": "string", "description": "The URI of the published prompt." }, "version": { "type": "string", "description": "The version of the published prompt." }, "publishedBy": { "type": "string", "description": "The Passport ID of the publisher." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "JSON object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication failed due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation required. Ensure your request includes a valid delegation token." } } } } } }, "403": { "description": "Permission denied due to insufficient prompt publishing scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/authorization-error", "title": "Authorization Error", "status": 403, "detail": "Your delegation does not include prompt:publish:welcome-prompt. Request this scope from your org admin." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while attempting to publish the prompt. Incident ID: inc_1697059200000" } } } } } } } } }, "/v1/prompts/:key/rollback": { "post": { "summary": "Revert prompt to a previous version", "description": "In the fast-paced world of AI-driven tasks, mistakes happen. This endpoint allows you to gracefully roll back a prompt to a previous version, ensuring that your workflows remain consistent and reliable. By using this feature, you can swiftly mitigate issues caused by unintended changes.", "operationId": "rollbackPromptVersion", "tags": [ "Prompt Management", "Version Control" ], "x-code-hash": "86aa8c8c0f889e6f", "x-generated-at": "2026-03-24T21:50:55.062Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_version": { "type": "string", "description": "The semantic version identifier of the target version." } }, "required": [ "target_version" ] }, "examples": { "rollback_to_previous_stable_version": { "summary": "Rollback to Previous Stable Version", "description": "This example demonstrates rolling back a prompt to version 1.3.2.", "value": { "target_version": "1.3.2" } } } } } }, "responses": { "200": { "description": "The prompt was successfully rolled back to the specified version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_uri": { "type": "string", "description": "The URI of the prompt that was rolled back." }, "active_version": { "type": "string", "description": "The version to which the prompt has been rolled back." }, "rolled_back_at": { "type": "string", "format": "date-time", "description": "The timestamp of when the rollback occurred." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Access to this resource is forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "The specified prompt or version could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/prompts/:key/deprecate/:version": { "post": { "summary": "Deprecate a specific prompt version", "description": "This endpoint allows you to mark a specific version of a prompt as deprecated. It plays a crucial role in maintaining the integrity of your prompts' lifecycle, ensuring that outdated or incorrect versions are no longer in active use. By deprecating a version, you safeguard the quality and consistency of tasks processed by your organization.", "operationId": "deprecatePromptVersion_1", "tags": [ "Prompts", "Version Management" ], "x-code-hash": "3dff9beca1263602", "x-generated-at": "2026-03-24T21:51:13.338Z", "responses": { "200": { "description": "The prompt version was successfully deprecated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_uri": { "type": "string", "description": "The URI of the deprecated prompt." }, "version": { "type": "string", "description": "The version of the prompt that was deprecated." }, "status": { "type": "string", "enum": [ "deprecated" ], "description": "The status of the prompt version." }, "deprecated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the version was deprecated." } }, "required": [ "prompt_uri", "version", "status", "deprecated_at" ] }, "examples": { "successful_deprecation": { "summary": "Successful Deprecation", "description": "A prompt version is successfully deprecated.", "value": { "prompt_uri": "prompt://acme/invoice-processing", "version": "v1.2.3", "status": "deprecated", "deprecated_at": "2023-11-02T14:30:00Z" } } } } } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request": { "summary": "Malformed Request", "description": "The request parameters are incorrect.", "value": { "type": "https://example.com/probs/malformed-request", "title": "Malformed Request", "status": 400, "detail": "The 'version' parameter is missing or invalid.", "errors": [ "version parameter is required" ] } } } } } }, "401": { "description": "Authentication is required to deprecate a prompt version.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "No valid delegation was found.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please provide valid authentication." } } } } } }, "403": { "description": "The client lacks the required permission to deprecate the prompt version.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "The delegation lacks the necessary scope.", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "Your delegation does not include prompt:deprecate:acme. Please ensure your delegation includes the required scope." } } } } } }, "404": { "description": "The specified prompt key was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "prompt_not_found": { "summary": "Prompt Not Found", "description": "The prompt key does not exist in the system.", "value": { "type": "https://example.com/probs/prompt-not-found", "title": "Prompt Not Found", "status": 404, "detail": "The prompt with key 'acme' was not found. Please verify the key and try again." } } } } } }, "500": { "description": "An internal error occurred while deprecating the prompt version.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred during processing.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to deprecate the prompt version. Please contact support with incident ID: inc_123456789." } } } } } } } } }, "/v1/prompts/:key/performance": { "get": { "summary": "Retrieve Prompt Performance Snapshot", "description": "Dive into the details of how your prompts are performing with our telemetry data. This endpoint allows you to understand the efficiency, cost, and success of prompt executions, empowering you to optimize for better outcomes.", "operationId": "getPromptPerformanceSnapshot", "tags": [ "Performance", "Telemetry" ], "x-code-hash": "8cab88e7916f804c", "x-generated-at": "2026-03-24T21:51:45.618Z", "responses": { "200": { "description": "Returns a detailed performance snapshot for a specific prompt key over the last seven days.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_key": { "type": "string" }, "window": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "stats": { "type": "object", "properties": { "total_calls": { "type": "integer" }, "avg_tokens": { "type": "integer" }, "avg_cost_usd": { "type": "number" }, "avg_duration_ms": { "type": "integer" }, "positive_signals": { "type": "integer" }, "negative_signals": { "type": "integer" }, "rephrases": { "type": "integer" }, "corrections": { "type": "integer" } } }, "model_breakdown": { "type": "array", "items": { "type": "object", "properties": { "model_id": { "type": "string" }, "provider": { "type": "string" }, "call_count": { "type": "integer" }, "avg_latency_ms": { "type": "integer" }, "avg_cost_usd": { "type": "number" }, "avg_tokens": { "type": "integer" }, "success_rate": { "type": "number" } } } }, "recommended_model": { "type": [ "string", "null" ] } } }, "examples": { "acme_corp_prompt_analysis": { "summary": "Acme Corp Prompt Analysis", "description": "A performance snapshot for Acme Corp's invoice processing prompt over the last week.", "value": { "prompt_key": "acme_invoice_processor", "window": { "start": "2023-10-01T00:00:00Z", "end": "2023-10-08T00:00:00Z" }, "stats": { "total_calls": 1500, "avg_tokens": 350, "avg_cost_usd": 0.015, "avg_duration_ms": 120, "positive_signals": 1200, "negative_signals": 100, "rephrases": 50, "corrections": 10 }, "model_breakdown": [ { "model_id": "GPT-3", "provider": "OpenAI", "call_count": 900, "avg_latency_ms": 110, "avg_cost_usd": 0.01, "avg_tokens": 300, "success_rate": 0.95 }, { "model_id": "BERT", "provider": "HuggingFace", "call_count": 600, "avg_latency_ms": 140, "avg_cost_usd": 0.02, "avg_tokens": 400, "success_rate": 0.9 } ], "recommended_model": "GPT-3" } } } } } }, "400": { "description": "Bad request due to malformed input or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_prompt_key_format": { "summary": "Invalid Prompt Key Format", "value": { "type": "https://humanapi.com/problems/invalid-input", "title": "Invalid Parameter", "status": 400, "detail": "The prompt key 'acme%20invoice%20processor' is improperly formatted.", "errors": [ "Ensure the prompt key is URL encoded correctly." ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://humanapi.com/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access prompt performance data." } } } } } }, "403": { "description": "Authorization error due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://humanapi.com/problems/insufficient-permissions", "title": "Forbidden", "status": 403, "detail": "Your delegation does not include prompt:read:acme_invoice_processor.", "errors": [ "Ensure your Passport includes the necessary prompt:read:{key} permissions." ] } } } } } }, "404": { "description": "The specified prompt key does not exist or no data is available.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "prompt_key_not_found": { "summary": "Prompt Key Not Found", "value": { "type": "https://humanapi.com/problems/not-found", "title": "Not Found", "status": 404, "detail": "No performance data available for prompt key 'unknown_prompt'." } } } } } }, "500": { "description": "Server error due to database issues or unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanapi.com/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please contact support with incident ID: inc_1697072400000." } } } } } } } } }, "/v1/prompts/:key/affinity": { "get": { "summary": "Retrieve prompt model affinity insights", "description": "Dive into the nuanced world of AI model performance with this endpoint, providing insights into which models excel with a specific prompt. By analyzing historical data, it helps you orchestrate the perfect harmony between human and AI, optimizing task efficiency.", "operationId": "getPromptAffinity_1", "tags": [ "PromptAnalysis", "ModelPerformance" ], "x-code-hash": "ec17d9842fad9456", "x-generated-at": "2026-03-24T21:52:00.697Z", "responses": { "200": { "description": "Successfully retrieved model affinities for the provided prompt key. Discover which models are your best allies in achieving optimal outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "prompt_key": { "type": "string" }, "model_id": { "type": "string" }, "provider": { "type": "string" }, "sample_size": { "type": "integer" }, "stats": { "type": "object", "properties": { "avg_latency_ms": { "type": "integer" }, "avg_cost_usd": { "type": "number" }, "avg_tokens": { "type": "integer" }, "success_rate": { "type": "number" } } }, "affinity_score": { "type": "number" } } } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "data": [ { "prompt_key": "invoice-processing", "model_id": "model_42", "provider": "acmeAI", "sample_size": 150, "stats": { "avg_latency_ms": 120, "avg_cost_usd": 0.0045, "avg_tokens": 350, "success_rate": 0.95 }, "affinity_score": 0.9025 } ], "limit": 10, "cursorField": "model_id" } } } } } }, "400": { "description": "Bad request due to malformed input or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/bad-request", "title": "Bad Request", "status": 400, "detail": "The request parameters were malformed. Ensure valid prompt key and parameters." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please authenticate to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Your delegation does not include prompt:read:invoice-processing.", "errors": [ "prompt:read:invoice-processing" ] } } } } } }, "404": { "description": "Not found error when the prompt key does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified prompt key does not exist. Verify the prompt key and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID inc_1697045300000." } } } } } } } } }, "/v1/interaction/duplex/sessions": { "post": { "summary": "Initiate a Duplex Session for Interaction", "description": "Begin an interactive session where human and AI collaborate seamlessly. This endpoint is the gateway to orchestrating dynamic conversations, ensuring that tasks are handled with precision and AI safety. Dive into a world where your AI can act as a passive observer, a collaborative coach, or take the reins as an active participant.", "operationId": "startDuplexSession", "tags": [ "Session Management", "Duplex Communication" ], "x-code-hash": "6f69d13cf2f094a7", "x-generated-at": "2026-03-24T21:52:22.912Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "passive", "coach", "active" ], "description": "The operational mode of the session." }, "agent_id": { "type": "string", "description": "Unique identifier for the agent initiating the session." }, "provider": { "type": "string", "description": "Specifies the service provider for the session." }, "persona_id": { "type": "string", "description": "Identifier for the persona to be used." }, "privacy_profile_id": { "type": "string", "description": "Identifier for the privacy profile to be used." }, "org_id": { "type": "string", "description": "Identifier for the organization under which the session is being initiated." } }, "required": [ "mode" ] }, "examples": { "start_passive_session": { "summary": "Start Passive Session", "description": "Initiates a session with the AI in passive mode.", "value": { "mode": "passive", "agent_id": "agent_007", "provider": "acme_voice_service", "persona_id": "support_bot", "privacy_profile_id": "confidential", "org_id": "acme_corp" } } } } } }, "responses": { "201": { "description": "Duplex session successfully started, returning session details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique identifier for the created session." }, "mode": { "type": "string", "description": "Operational mode of the session." }, "provider": { "type": "string", "description": "Service provider used for the session." }, "status": { "type": "string", "description": "Current status of the session." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was created." } } }, "examples": { "default": { "summary": "Example", "value": { "session_id": "sess_12345", "mode": "passive", "provider": "acme_voice_service", "status": "active", "created_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Request Body", "status": 400, "detail": "Request body is required and must include a valid mode.", "errors": [ { "field": "mode", "code": "INVALID_ENUM_VALUE", "message": "mode must be one of: passive, coach, active", "expected": "passive | coach | active", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource." } } } } } }, "403": { "description": "Access to the resource is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to start a session with the specified parameters." } } } } } }, "404": { "description": "The specified resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The organization or agent specified does not exist." } } } } } }, "500": { "description": "Internal server error due to system issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while starting the duplex session. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve active duplex session list", "description": "This endpoint unveils the heartbeat of the HUMAN platform by listing all active duplex sessions. Imagine a bustling command center where human and AI agents collaborate seamlessly—this endpoint ensures you have a real-time view of those dynamic interactions.", "operationId": "listActiveDuplexSessions", "tags": [ "Interaction", "Duplex" ], "x-code-hash": "0748166d78687595", "x-generated-at": "2026-03-24T21:54:24.441Z", "responses": { "200": { "description": "A list of active duplex sessions, each detailing the collaborative pathways between human and AI agents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string" }, "passport_id": { "type": "string" }, "org_id": { "type": [ "string", "null" ] }, "agent_id": { "type": "string" }, "mode": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "session_id", "passport_id", "agent_id", "mode", "provider", "status", "created_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "active_sessions_for_acme_corp": { "summary": "Active sessions for Acme Corp", "description": "A glimpse into Acme Corp's active sessions where human and AI agents are collaboratively processing invoices.", "value": { "data": [ { "session_id": "sess_01F8MECHYX82Y9JQ3T3J7Y8W5Z", "passport_id": "pass_01F8MECHEJZK9A1X7ZTZ9F0P43", "org_id": "org_acme", "agent_id": "agent_01F8MECHX9WY7VZ9QJ9K9P8B6B", "mode": "interactive", "provider": "provider_xyz", "status": "active", "created_at": "2023-10-01T12:34:56Z" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Bad Request - The request could not be understood or was missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters are incorrect. Check the API documentation for the correct query parameters." } } } } } }, "401": { "description": "Unauthorized - Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "No valid API key provided. Please ensure your request includes a valid Authorization header." } } } } } }, "403": { "description": "Forbidden - The server understood the request, but refuses to authorize it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these sessions. Please check your permissions or contact your administrator." } } } } } }, "404": { "description": "Not Found - The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "No active sessions found for the specified query. Please refine your search criteria." } } } } } }, "500": { "description": "Internal Server Error - An error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try your request again later or contact support if the issue persists." } } } } } } } } }, "/v1/interaction/duplex/sessions/:id": { "delete": { "summary": "Stop an active duplex session", "description": "In the dynamic world of real-time interactions, there comes a moment when a conversation must gracefully conclude. This endpoint empowers you to end an active duplex session, ensuring resources are efficiently reallocated and tasks can progress seamlessly. It's not just about stopping; it's about orchestrating a smooth transition.", "operationId": "stopDuplexSession", "tags": [ "Interaction", "Duplex Sessions" ], "x-code-hash": "bded4c915dba95e4", "x-generated-at": "2026-03-24T21:52:42.732Z", "responses": { "200": { "description": "The duplex session was successfully stopped, allowing the system to reclaim resources and prepare for future interactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The unique identifier of the duplex session." }, "status": { "type": "string", "description": "The current status of the session, post-termination." } }, "required": [ "session_id", "status" ] }, "examples": { "successful_session_termination": { "summary": "Successful session termination", "description": "A successful response indicating the duplex session has been stopped.", "value": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "status": "stopped" } } } } } }, "400": { "description": "The request was malformed. Perhaps the session ID was not provided correctly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_example": { "summary": "Malformed request example", "description": "An example of a malformed request due to an incorrect session ID.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Bad Request", "status": 400, "detail": "The session ID is invalid or missing." } } } } } }, "401": { "description": "Authentication failed. This could occur if the passport credentials are incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_failure_example": { "summary": "Authentication failure example", "description": "An example of a failed authentication due to missing or invalid credentials.", "value": { "type": "https://humanprotocol.org/errors/authentication-failed", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Access is forbidden, usually due to insufficient permissions tied to the user's capability graph.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_error_example": { "summary": "Permission error example", "description": "An example where the user lacks the necessary privileges to stop a session.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to stop this session." } } } } } }, "404": { "description": "The specified duplex session could not be found, possibly because it has already been terminated or the ID was incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "session_not_found_example": { "summary": "Session not found example", "description": "An example of what happens when a session ID does not match any active session.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Duplex session not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server. This is often a transient issue, and the operation may succeed if retried.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server error example", "description": "An example of a server-side failure that prevents the session from being stopped.", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to stop duplex session due to an unexpected error." } } } } } } } } }, "/v1/interaction/duplex/sessions/:id/speak": { "post": { "summary": "Initiate agent speech in a session", "description": "In the dynamic dance of human and AI collaboration, this endpoint empowers agents to vocalize within an ongoing duplex session. It's the bridge where AI articulation meets human context, enabling seamless task progression and richer interactions.", "operationId": "initiateAgentSpeech", "tags": [ "Interaction", "DuplexSession" ], "x-code-hash": "8d4a8b0da286eeef", "x-generated-at": "2026-03-24T21:53:00.165Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content the agent should vocalize." }, "style": { "type": "string", "enum": [ "default", "whisper", "emphasis" ], "description": "The vocal style in which the text should be spoken." }, "interrupt_current": { "type": "boolean", "description": "Determines if the current speech should be interrupted for this new speech." } }, "required": [ "text" ] }, "examples": { "acme_invoice_processing": { "summary": "Acme Invoice Processing", "description": "An agent in the Acme organization processes invoices and provides feedback via speech in an ongoing session.", "value": { "text": "Processing invoice #12345 for client XYZ.", "style": "default", "interrupt_current": true } } } } } }, "responses": { "200": { "description": "The agent's speech was successfully initiated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The unique identifier for the duplex session." }, "sent": { "type": "boolean", "description": "Indicates if the speech command was successfully sent." } } }, "examples": { "default": { "summary": "Example", "value": { "session_id": "session-42", "sent": true } } } } } }, "400": { "description": "Invalid input was provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.ai/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "One or more fields failed validation.", "errors": [ { "field": "text", "code": "REQUIRED_FIELD_MISSING", "message": "text is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication credentials were missing or incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.ai/problems/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "The user does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.ai/problems/permission-error", "title": "Permission Error", "status": 403, "detail": "You do not have the required permissions to initiate speech in this session." } } } } } }, "404": { "description": "The specified duplex session was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.ai/problems/not-found", "title": "Not Found", "status": 404, "detail": "The duplex session with ID 'session-42' could not be found. Please verify the session ID and try again." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.ai/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "There was an error processing your request. Please try again later or contact support." } } } } } } } } }, "/v1/interaction/duplex/sessions/:id/backchannel": { "post": { "summary": "Initiate backchannel in duplex session", "description": "Open a direct communication channel with the AI agent during an active duplex session. This endpoint allows human operators to signal their current interaction mode, enhancing the coordination and effectiveness of the AI's response.", "operationId": "postBackchannelDuplexSession", "tags": [ "Communication", "DuplexSession" ], "x-code-hash": "be29a428937f7e2f", "x-generated-at": "2026-03-24T21:53:15.438Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "style": { "type": "string", "enum": [ "ack", "thinking" ], "description": "The style of interaction: 'ack' for acknowledgment or 'thinking' for processing state." } }, "required": [ "style" ] }, "examples": { "acknowledge_interaction": { "summary": "Acknowledge Interaction", "description": "Signals the AI to acknowledge receipt of information.", "value": { "style": "ack" } } } } } }, "responses": { "200": { "description": "The backchannel was successfully established and the interaction style was sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "sent": { "type": "boolean" } } }, "examples": { "default": { "summary": "Example", "value": { "session_id": "123456", "sent": true } } } } } }, "400": { "description": "Invalid request due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.com/errors/400", "title": "Bad Request", "status": 400, "detail": "The 'style' field must be a valid enum value.", "errors": [ "Invalid value for 'style'. Expected 'ack' or 'thinking'." ] } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.com/errors/401", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this endpoint." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.com/errors/403", "title": "Forbidden", "status": 403, "detail": "You do not have permission to send a backchannel in this session." } } } } } }, "404": { "description": "The specified duplex session could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.com/errors/404", "title": "Not Found", "status": 404, "detail": "The duplex session with ID '123456' was not found." } } } } } }, "500": { "description": "Internal server error while attempting to send the backchannel.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.com/errors/500", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the backchannel request." } } } } } } } } }, "/v1/interaction/duplex/sessions/:id/pause": { "post": { "summary": "Pause a live duplex session", "description": "In the bustling world of human-AI interaction, sometimes you need a breather. This endpoint lets you pause an ongoing duplex session, providing control and flexibility in managing real-time exchanges. Whether you're handling a complex negotiation or need a moment to regroup, this functionality ensures you can pause without missing a beat.", "operationId": "pauseDuplexSession", "tags": [ "Interaction", "Session Management" ], "x-code-hash": "3d1e536e0dd692fe", "x-generated-at": "2026-03-24T21:53:32.972Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique identifier for the duplex session to pause." } }, "required": [ "session_id" ] }, "examples": { "pause_active_session": { "summary": "Pause Active Session", "description": "Pausing a session with ID '123e4567-e89b-12d3-a456-426614174000'.", "value": { "session_id": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "responses": { "200": { "description": "The session was successfully paused.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "status": { "type": "string", "enum": [ "paused" ] } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was malformed. Ensure the session ID is correctly formatted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/malformed-request", "title": "Malformed Request", "status": 400, "detail": "The session ID provided is not valid. Please check and try again." } } } } } }, "401": { "description": "Unauthorized access. Authentication is required to pause a session.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access is denied due to invalid credentials. Please authenticate and try again." } } } } } }, "403": { "description": "Forbidden. You do not have permission to pause this session.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the required permissions to pause this session. Contact your administrator." } } } } } }, "404": { "description": "The specified duplex session was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The duplex session with ID '123e4567-e89b-12d3-a456-426614174000' was not found. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error while attempting to pause the session.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while pausing the session. Please try again later or contact support." } } } } } } } } }, "/v1/interaction/duplex/sessions/:id/resume": { "post": { "summary": "Resume an existing duplex session", "description": "In the dynamic world of human-AI collaboration, the ability to pause and resume interactions is essential. This endpoint breathes life back into a paused duplex session, allowing humans and AI to seamlessly continue their orchestration journey. By reactivating a session, we ensure that no valuable interaction goes unfinished.", "operationId": "resumeDuplexSession", "tags": [ "Session Management", "Duplex Communication" ], "x-code-hash": "72ac8417b9b57e3c", "x-generated-at": "2026-03-24T21:53:48.978Z", "responses": { "200": { "description": "Successfully resumed the duplex session, transitioning it back to an active state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "status": { "type": "string", "enum": [ "started" ] } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanplatform.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request syntax was malformed." } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanplatform.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "The server understood the request, but refuses to authorize it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanplatform.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to resume this session." } } } } } }, "404": { "description": "The requested session was not found. This might mean the session ID is incorrect or the session has been deleted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanplatform.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The session with ID 'session123' was not found." } } } } } }, "500": { "description": "The server encountered an unexpected condition which prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanplatform.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to resume duplex session due to an internal error." } } } } } } } } }, "/v1/interaction/duplex/sessions/:id/events": { "get": { "summary": "Stream Duplex Session Events via SSE", "description": "Experience the continuous flow of events from a duplex session, leveraging Server-Sent Events (SSE) to keep you updated in real-time. This endpoint ensures you are at the forefront of session activity, providing insights and state changes as they happen.", "operationId": "getDuplexSessionEvents", "tags": [ "Sessions", "Events" ], "x-code-hash": "b19c37701fb6a647", "x-generated-at": "2026-03-24T21:54:05.141Z", "responses": { "200": { "description": "Successfully streaming events from the duplex session.", "content": { "application/json": { "schema": { "type": "string", "description": "SSE formatted string with each event serialized as JSON." }, "examples": { "active_session_stream": { "summary": "Active Session Stream", "description": "Streaming active events from a live session.", "value": "data: {\"type\":\"interaction\",\"detail\":\"user joined\",\"sessionId\":\"session123\",\"timestamp\":\"2023-10-12T07:20:50.52Z\"}\n\n" }, "session_stopped_event": { "summary": "Session Stopped Event", "description": "Event indicating the session has stopped.", "value": "data: {\"type\":\"session.state\",\"state\":\"stopped\",\"sessionId\":\"session123\",\"timestamp\":\"2023-10-12T07:25:30.52Z\"}\n\n" } } } } }, "400": { "description": "Invalid request due to malformed input or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.io/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request parameter 'id' is missing or malformed." } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing Passport credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.io/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions with provided Passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.io/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Your Passport does not grant access to this session." } } } } } }, "404": { "description": "The requested session was not found, possibly due to an incorrect session ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.io/errors/not-found", "title": "Not Found", "status": 404, "detail": "Duplex session not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.io/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/workforce/opportunities": { "get": { "summary": "Discover Open Opportunities Effortlessly", "description": "Unlock a world of possibilities with our marketplace-style discovery endpoint. This tool connects organizations with open opportunities tailored to specific locations and capabilities, ensuring the right skills meet the right needs in real-time.", "operationId": "getWorkforceOpportunities", "tags": [ "Workforce", "Opportunities" ], "x-code-hash": "ec7ceb3f1e266565", "x-generated-at": "2026-03-24T21:54:41.049Z", "responses": { "200": { "description": "Successfully retrieves a list of open opportunities for the specified location and capability.", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string" }, "capability": { "type": "string" }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "opportunity_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "payload": { "type": "object" }, "posted_at": { "type": "string", "format": "date-time" } } } } } }, "examples": { "successful_opportunity_listing": { "summary": "Successful Opportunity Listing", "value": { "location": "USA", "capability": "capability://data-entry", "opportunities": [ { "opportunity_id": "op123", "title": "Data Entry Specialist", "status": "open", "payload": { "description": "Enter data for Acme Corp." }, "posted_at": "2023-10-01T12:34:56Z" } ] } } } } } }, "400": { "description": "Invalid request due to missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_query_parameters": { "summary": "Missing Query Parameters", "value": { "type": "https://humanprotocol.org/errors/required-query-param", "title": "Required Query Parameters Missing", "status": 400, "detail": "The 'location' and 'capability' query parameters are required.", "errors": [ { "field": "query", "code": "REQUIRED_QUERY_PARAM", "message": "location and capability query parameters are required", "expected": "location={country}&capability={skill slug}", "received": "location=missing&capability=missing" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://humanprotocol.org/errors/authentication-error", "title": "Delegation Required", "status": 401, "detail": "Delegation is required to access this resource. Ensure you have included a valid delegation header." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://humanprotocol.org/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access these opportunities. Please check your user roles and permissions." } } } } } }, "404": { "description": "No opportunities found matching the criteria.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "opportunities_not_found": { "summary": "Opportunities Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Opportunities Not Found", "status": 404, "detail": "No open opportunities found for the specified location and capability. Try different criteria." } } } } } }, "500": { "description": "Internal server error due to unforeseen issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/orgs/:orgDid/muscles": { "get": { "summary": "Retrieve organization's installed muscles", "description": "In the heart of the HUMAN platform, organizations harness the power of 'muscles'—modular skills to augment human capabilities. This endpoint allows you to explore the muscles currently installed for a specific organization, enabling you to manage and optimize skill resources. Delve into the dynamic world of skill orchestration, where AI and human skills converge.", "operationId": "getInstalledMuscles", "tags": [ "Organizations", "Muscles" ], "x-code-hash": "60df298412cd7ec3", "x-generated-at": "2026-03-27T15:35:50.565Z", "responses": { "200": { "description": "A successful response containing the list of installed muscles for the organization, paginated by the date of installation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "org_did": { "type": "string" }, "muscle_id": { "type": "string" }, "version_installed": { "type": "string" }, "asset_id": { "type": "string" }, "config": { "type": "object" }, "installed_at": { "type": "string", "format": "date-time" }, "installed_by_did": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "uninstalled" ] } } } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } } }, "examples": { "acme_corp's_muscle_list": { "summary": "Acme Corp's Muscle List", "description": "An overview of muscles installed in Acme Corp, showcasing active skill modules.", "value": { "data": [ { "id": "muscle-123", "org_did": "did:example:acme", "muscle_id": "muscle-text-analysis", "version_installed": "1.0.3", "asset_id": "asset-987", "config": { "language": "en" }, "installed_at": "2023-10-10T14:48:00Z", "installed_by_did": "did:example:agent123", "status": "active" } ], "limit": 10, "cursorField": "installed_at", "hasMore": false } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor": { "summary": "Invalid Cursor", "description": "An error indicating that the provided cursor for pagination is malformed.", "value": { "type": "https://humanprotocol.org/error/invalid-parameter", "title": "Invalid Cursor", "status": 400, "detail": "The pagination cursor provided is invalid. Please ensure the cursor token is correctly formatted.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "valid cursor token", "received": "malformed-cursor" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "description": "An error scenario where the request is missing the required delegation token.", "value": { "type": "https://humanprotocol.org/error/authentication", "title": "Authentication Required", "status": 401, "detail": "Delegation token required to access this endpoint. Ensure your request includes a valid authorization header." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Access is denied because the user does not have the necessary permissions.", "value": { "type": "https://humanprotocol.org/error/forbidden", "title": "Access Forbidden", "status": 403, "detail": "You do not have permission to view this organization's muscles. Contact your administrator for access." } } } } } }, "404": { "description": "The specified organization could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "An error scenario where the specified organization DID does not exist.", "value": { "type": "https://humanprotocol.org/error/not-found", "title": "Organization Not Found", "status": 404, "detail": "The organization with DID 'did:example:acme' could not be found. Verify the DID is correct." } } } } } }, "500": { "description": "Internal server error due to processing failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected server error occurred while fetching muscles.", "value": { "type": "https://humanprotocol.org/error/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while fetching the muscles. Please try again later. If the problem persists, contact support." } } } } } } } }, "post": { "summary": "Install a new muscle for an organization", "description": "In the ever-evolving orchestration of human and AI, installing a 'muscle' represents empowering your organization with new capabilities. This endpoint ensures your organization is equipped with the right tools, validating asset and version, and securing the necessary connectors for a seamless integration.", "operationId": "installOrgMuscle", "tags": [ "Organizations", "Muscles" ], "x-code-hash": "8883f0c99fff6598", "x-generated-at": "2026-03-30T18:02:01.840Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "muscle_id": { "type": "string", "description": "Unique identifier in publisher.name format." }, "version": { "type": "string", "description": "Semantic version of the muscle being installed." }, "asset_id": { "type": "string", "description": "Optional ID of the marketplace asset if specifying an asset." }, "config": { "type": "object", "description": "Configuration settings for the muscle." } }, "required": [ "muscle_id", "version" ] }, "examples": { "install_spreadsheet_processor": { "summary": "Install Spreadsheet Processor", "description": "Installing the spreadsheet processing muscle for data analytics.", "value": { "muscle_id": "human.spreadsheets", "version": "1.0.0", "asset_id": "asset-1234", "config": { "auto_update": true } } } } } } }, "responses": { "201": { "description": "Muscle successfully installed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string" }, "muscle_id": { "type": "string" }, "version_installed": { "type": "string" }, "asset_id": { "type": "string" }, "config": { "type": "object" }, "installed_by_did": { "type": "string" }, "status": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:human:org:acme", "muscle_id": "human.spreadsheets", "version_installed": "1.0.0", "asset_id": "asset-1234", "config": { "auto_update": true }, "installed_by_did": "did:human:agent:installer", "status": "active" } } } } } }, "400": { "description": "Validation errors occurred due to incorrect input format or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-input", "title": "Invalid Input", "status": 400, "detail": "muscle_id must follow publisher.name format.", "errors": [ { "field": "muscle_id", "code": "INVALID_FORMAT", "message": "muscle_id must follow publisher.name format (e.g. 'human.spreadsheets')", "expected": "dot-notation lowercase string", "received": "HumanSpreadsheets" } ] } } } } } }, "401": { "description": "Authentication failed due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/authentication-failed", "title": "Authentication Failed", "status": 401, "detail": "Delegation token required. Please provide a valid token." } } } } } }, "404": { "description": "Requested marketplace asset not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Asset Not Found", "status": 404, "detail": "Marketplace asset 'asset-1234' not found. Verify the asset_id and try again." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to install muscle. Please contact support if this issue persists." } } } } } } } } }, "/v1/orgs/:orgDid/muscles/:muscleId": { "delete": { "summary": "Soft-delete an organization's muscle", "description": "This endpoint allows organizations to gracefully retire skills, known as 'muscles', by marking them as 'uninstalled'. This mechanism ensures a clean audit trail while preserving historical data, enabling organizations to maintain transparency and compliance.", "operationId": "softDeleteOrgMuscle", "tags": [ "Organization", "Muscle Management" ], "x-code-hash": "1a7915099d522a40", "x-generated-at": "2026-03-27T15:36:25.639Z", "responses": { "200": { "description": "The muscle was successfully uninstalled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "uninstalled" }, "muscle_id": { "type": "string", "example": "muscle-abc123" } } }, "examples": { "successful_uninstall": { "summary": "Successful uninstall", "description": "An example where the muscle is successfully uninstalled.", "value": { "status": "uninstalled", "muscle_id": "muscle-abc123" } } } } } }, "400": { "description": "Bad request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-input", "title": "Invalid Request", "status": 400, "detail": "The muscle ID format is incorrect.", "errors": [ "muscleId should match pattern 'muscle-\\w{6}'" ] } } } } } }, "401": { "description": "Unauthorized access due to missing delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation token required." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to uninstall this muscle." } } } } } }, "404": { "description": "The specified muscle could not be found or is already uninstalled.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Muscle 'muscle-abc123' is not installed in org 'org-789xyz'." } } } } } }, "500": { "description": "Internal server error occurred while trying to uninstall the muscle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to uninstall muscle due to server error." } } } } } } } } }, "/v1/orgs/:orgDid/muscles/:muscleId/upgrade": { "patch": { "summary": "Upgrade an installed muscle version", "description": "In the dynamic world of AI-powered organizations, keeping your capabilities sharp is paramount. This endpoint allows you to upgrade an installed 'muscle'—a specific skill module in your organization—to a newer version. It's like giving your organization's AI a new set of tools to tackle tasks more efficiently, ensuring you're always at the cutting edge of technology.", "operationId": "upgradeMuscleVersion", "tags": [ "Muscles", "Upgrades" ], "x-code-hash": "e0bce6816bfaf50b", "x-generated-at": "2026-03-27T15:36:44.044Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "The semantic version number to which the muscle should be upgraded." }, "force": { "type": "boolean", "description": "Whether to force the upgrade even if the version is lower." } }, "required": [ "version" ] }, "examples": { "upgrade_to_a_newer_version": { "summary": "Upgrade to a newer version", "description": "This example shows a typical request to upgrade a muscle to version 2.1.0.", "value": { "version": "2.1.0", "force": false } } } } } }, "responses": { "200": { "description": "The muscle was successfully upgraded to the specified version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "org_did": { "type": "string" }, "muscle_id": { "type": "string" }, "version_installed": { "type": "string" }, "asset_id": { "type": "string" }, "config": { "type": "object" }, "installed_at": { "type": "string", "format": "date-time" }, "installed_by_did": { "type": "string" }, "status": { "type": "string" } } }, "examples": { "successful_upgrade": { "summary": "Successful Upgrade", "description": "An example response showing a successfully upgraded muscle.", "value": { "id": "muscle-12345", "org_did": "did:human:acme-org", "muscle_id": "muscle-alpha", "version_installed": "2.1.0", "asset_id": "asset-67890", "config": {}, "installed_at": "2023-10-25T14:48:00.000Z", "installed_by_did": "did:human:agent-jane", "status": "active" } } } } } }, "400": { "description": "The request is invalid due to missing or malformed version.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_version": { "summary": "Missing Version", "description": "The request failed because the version field was missing.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "version is required", "errors": [ { "field": "version", "code": "REQUIRED_FIELD_MISSING", "message": "version is required", "expected": "semver string (e.g. \"1.1.0\")", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication is required to perform this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "description": "The request failed due to a missing delegation token.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation token required" } } } } } }, "403": { "description": "The requester does not have permission to upgrade the muscle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_upgrade": { "summary": "Forbidden Upgrade", "description": "The request failed because the user lacks permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to upgrade this muscle." } } } } } }, "404": { "description": "The specified muscle or version was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "muscle_not_found": { "summary": "Muscle Not Found", "description": "The request failed because the muscle is not installed in the organization.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Muscle \"muscle-alpha\" is not installed in org \"did:human:acme-org\"" } }, "version_not_found": { "summary": "Version Not Found", "description": "The request failed because the specified version does not exist in the marketplace.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Version \"2.1.0\" of muscle \"muscle-alpha\" not found in marketplace" } } } } } }, "500": { "description": "An unexpected error occurred while attempting to upgrade the muscle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to upgrade muscle" } } } } } } } } }, "/v1/orgs/:orgDid/connectors/:connectorId/upgrade": { "patch": { "summary": "Upgrade a connector to a new version", "description": "In the ever-evolving landscape of digital tools, keeping your connectors up-to-date is paramount for leveraging new features and maintaining security. This endpoint allows organizations to seamlessly upgrade their connectors to newer versions, ensuring they are always operating with the latest capabilities.", "operationId": "upgradeConnectorVersion", "tags": [ "Connectors", "Upgrades" ], "x-code-hash": "7d03f139f0ed0ce1", "x-generated-at": "2026-03-27T15:37:06.333Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "The semantic version number to upgrade the connector to, e.g., '1.1.0'." }, "force": { "type": "boolean", "description": "Flag to force the upgrade even if it is a downgrade." } }, "required": [ "version" ] }, "examples": { "upgrade_to_version_2.0.0": { "summary": "Upgrade to version 2.0.0", "description": "Example showing how to upgrade a connector to version 2.0.0", "value": { "version": "2.0.0", "force": false } } } } } }, "responses": { "200": { "description": "Connector successfully upgraded to the specified version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "installation_id": { "type": "string", "description": "The unique identifier of the connector installation." }, "connector_id": { "type": "string", "description": "The unique identifier of the connector." }, "version_installed": { "type": "string", "description": "The version of the connector that was installed." } } }, "examples": { "successful_upgrade": { "summary": "Successful Upgrade", "value": { "installation_id": "inst-12345", "connector_id": "conn-67890", "version_installed": "2.0.0" } } } } } }, "400": { "description": "The request was invalid, such as missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_version": { "summary": "Missing Version", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "version is required", "errors": [ { "field": "version", "code": "REQUIRED_FIELD_MISSING", "message": "version is required", "expected": "semver string (e.g. '1.1.0')", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "value": { "type": "https://humanprotocol.org/errors/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation token required" } } } } } }, "403": { "description": "Permission denied for the requested operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to upgrade this connector." } } } } } }, "404": { "description": "Connector or version not found for the given identifiers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_not_found": { "summary": "Connector Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Connector \"conn-67890\" is not installed in org \"org-12345\"" } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to upgrade connector" } } } } } } } } }, "/v1/onboarding/persona": { "post": { "summary": "Select and install a persona", "description": "Empower your organization by selecting a persona that aligns with your goals, ensuring the necessary agents are installed seamlessly. This endpoint orchestrates essential configurations, making your workspace ready for action.", "operationId": "selectOnboardingPersona", "tags": [ "Onboarding", "Persona" ], "x-code-hash": "1054d2340f8a26bd", "x-generated-at": "2026-04-02T20:38:48.475Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personaId": { "type": "string", "description": "Unique identifier for the desired persona." }, "org_did": { "type": "string", "description": "Decentralized identifier for the organization, required if not in token." } }, "required": [ "personaId" ] }, "examples": { "select_persona_for_acme_corp": { "summary": "Select Persona for Acme Corp", "description": "Selecting a persona with organization context provided.", "value": { "personaId": "persona-123", "org_did": "did:org:acme-inc" } } } } } }, "responses": { "202": { "description": "Persona successfully selected and agents installed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "personaId": { "type": "string", "description": "The selected persona ID." }, "displayName": { "type": "string", "description": "Human-readable name of the persona." }, "agentCount": { "type": "integer", "description": "Number of agents installed." }, "status": { "type": "string", "enum": [ "installed" ], "description": "Status of the installation process." }, "installations": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string", "description": "ID of the installed asset." }, "installation_id": { "type": "string", "description": "Unique identifier for the installation." }, "agent_did": { "type": "string", "description": "DID of the installed agent." } }, "required": [ "asset_id", "installation_id", "agent_did" ] } }, "message": { "type": "string", "description": "Descriptive message about the installation outcome." } }, "required": [ "personaId", "displayName", "agentCount", "status", "installations", "message" ] }, "examples": { "successful_persona_selection": { "summary": "Successful Persona Selection", "description": "Persona selected and agents installed for Acme Corp.", "value": { "personaId": "persona-123", "displayName": "Acme Persona", "agentCount": 3, "status": "installed", "installations": [ { "asset_id": "agent-001", "installation_id": "install-789", "agent_did": "did:agent:001" }, { "asset_id": "agent-002", "installation_id": "install-790", "agent_did": "did:agent:002" } ], "message": "Acme Persona: installed 3 required agents for your workspace." } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_persona_id": { "summary": "Missing Persona ID", "description": "The request did not include a persona ID.", "value": { "type": "https://haio.run/errors/required-field-missing", "title": "Invalid Request", "status": 400, "detail": "personaId is required", "errors": [ { "field": "personaId", "code": "REQUIRED_FIELD_MISSING", "message": "personaId is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "User did not provide valid authentication.", "value": { "type": "https://haio.run/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required to select a persona" } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "User lacks permission to select this persona.", "value": { "type": "https://haio.run/errors/access-denied", "title": "Access Denied", "status": 403, "detail": "You do not have permission to select this persona" } } } } } }, "404": { "description": "The requested persona or asset was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "persona_not_found": { "summary": "Persona Not Found", "description": "The specified persona ID does not exist.", "value": { "type": "https://haio.run/errors/persona-not-found", "title": "Persona Not Found", "status": 404, "detail": "Persona with ID persona-unknown not found" } } } } } }, "500": { "description": "Internal server error due to unexpected issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_issuance_error": { "summary": "Delegation Issuance Error", "description": "Error occurred during delegation issuance.", "value": { "type": "https://haio.run/errors/delegation-issuance-failed", "title": "Delegation Issuance Failed", "status": 500, "detail": "Delegation issuance failed due to configuration error" } } } } } } } } }, "/v1/presence/report": { "post": { "summary": "Report device presence and status", "description": "Integrate seamlessly with HumanOS by reporting real-time device presence. This endpoint captures the essence of human-device interaction, enabling dynamic task routing and enhancing AI safety through accurate modality tracking.", "operationId": "reportPresence", "tags": [ "Presence", "Device" ], "x-code-hash": "e5fcb6e480cfdd6f", "x-generated-at": "2026-03-24T21:57:44.829Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string", "description": "Unique identifier for the device" }, "modality": { "type": "string", "description": "The interaction modality, such as text or voice", "default": "text", "enum": [ "text", "voice", "spatial", "compact" ] }, "accessories": { "type": "array", "items": { "type": "string" }, "description": "List of accessories used with the device" }, "bandwidth_tier": { "type": "string", "description": "Current bandwidth tier of the device" } }, "required": [ "device_id" ] }, "examples": { "text_modality_report": { "summary": "Text Modality Report", "description": "Reporting presence with a text modality", "value": { "device_id": "device123", "modality": "text", "accessories": [ "keyboard" ], "bandwidth_tier": "high" } } } } } }, "responses": { "200": { "description": "Presence reported successfully, facilitating efficient task routing in HumanOS.", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" }, "device_id": { "type": "string" }, "modality": { "type": "string" }, "routing_hint": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Validation errors due to incorrect request format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body contains invalid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Invalid JSON body" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Access forbidden due to lack of necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found; the specified endpoint does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested endpoint does not exist." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected server error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/orgs/:orgDid": { "get": { "summary": "Retrieve organization details by DID", "description": "Delve into the heart of HUMAN's orchestration by fetching the details of an organization using its Decentralized Identifier (DID). This endpoint empowers you to access essential data that defines an organization’s identity within the HUMAN network, ensuring seamless integration and interaction.", "operationId": "getOrgDetails", "tags": [ "Organization", "Identity" ], "x-code-hash": "c95d8c11713ed68e", "x-generated-at": "2026-03-24T21:58:02.811Z", "responses": { "200": { "description": "Successfully retrieved organization details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgDid": { "type": "string", "description": "The Decentralized Identifier of the organization." }, "name": { "type": "string", "description": "The name of the organization." }, "createdAt": { "type": "string", "format": "date-time", "description": "The timestamp when the organization was created." } } }, "examples": { "successful_retrieval_example": { "summary": "Successful retrieval example", "value": { "orgDid": "did:human:123456789abcdefghi", "name": "Acme Corporation", "createdAt": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Invalid request due to malformed DID or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'orgDid' parameter is malformed or missing.", "errors": [ "'orgDid' must be a valid DID." ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested organization was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Organization with DID 'did:human:123456789abcdefghi' not found." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "put": { "summary": "Update organizational details securely", "description": "Refine the identity and configuration of your organization within the HUMAN ecosystem. This endpoint empowers administrators to update key organizational attributes, ensuring alignment with evolving goals and compliance requirements. By leveraging this capability, you can effortlessly manage organizational dynamics through cryptographic identity and secure task orchestration.", "operationId": "updateOrgDetails", "tags": [ "Organization Management", "Control Plane" ], "x-code-hash": "780b3fa36efc3460", "x-generated-at": "2026-03-30T18:02:33.771Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The human-readable name of the organization." }, "slug": { "type": "string", "description": "A unique identifier for the organization." }, "logo_url": { "type": "string", "description": "URL to the organization's logo." }, "deployment_mode": { "type": "string", "description": "Current mode of deployment, e.g., 'development' or 'production'." }, "data_residency_tier": { "type": "string", "description": "Tier defining data residency restrictions." }, "data_residency_region": { "type": "string", "description": "Region where data is stored." }, "autonomy_profile": { "type": "string", "description": "Profile defining organizational autonomy level." }, "policies": { "type": "object", "description": "Organizational policies in JSON format." }, "settings": { "type": "object", "description": "Specific settings for organizational configuration." } } }, "examples": { "update_organization_name_and_mode": { "summary": "Update organization name and mode", "description": "This example demonstrates a request to update the organization's name and switch its deployment mode to 'production'.", "value": { "name": "Acme Corp", "deployment_mode": "production" } } } } } }, "responses": { "200": { "description": "The organization details were successfully updated. The response includes the updated organization object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgDid": { "type": "string", "description": "The decentralized identifier for the organization." }, "name": { "type": "string", "description": "Updated name of the organization." }, "slug": { "type": "string", "description": "Updated slug of the organization." }, "logo_url": { "type": "string", "description": "Updated URL of the organization's logo." }, "deployment_mode": { "type": "string", "description": "Updated deployment mode of the organization." }, "data_residency_tier": { "type": "string", "description": "Updated data residency tier." }, "data_residency_region": { "type": "string", "description": "Updated data residency region." }, "autonomy_profile": { "type": "string", "description": "Updated autonomy profile." }, "policies": { "type": "object", "description": "Updated policies in JSON format." }, "settings": { "type": "object", "description": "Updated settings for organizational configuration." } } }, "examples": { "successful_update_response": { "summary": "Successful update response", "description": "The organization Acme Corp's details have been successfully updated.", "value": { "orgDid": "did:human:acme", "name": "Acme Corp", "slug": "acme-corp", "logo_url": "https://example.com/logo.png", "deployment_mode": "production", "data_residency_tier": "premium", "data_residency_region": "us-east-1", "autonomy_profile": "advanced", "policies": { "policy1": "value1" }, "settings": { "setting1": "value1" } } } } } } }, "400": { "description": "The request was invalid. No fields were provided for update.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_fields_provided": { "summary": "No fields provided", "value": { "type": "https://haio.run/errors/no-update", "title": "No fields to update", "status": 400, "detail": "Provide at least one updatable field." } } } } } }, "401": { "description": "Unauthorized access to the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_token": { "summary": "Missing authentication token", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A valid authentication token is required to access this resource." } } } } } }, "403": { "description": "Forbidden: The authenticated user does not have permission to perform this update.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this organization." } } } } } }, "404": { "description": "The organization with the specified DID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization not found", "value": { "type": "https://haio.run/errors/not-found", "title": "Organization Not Found", "status": 404, "detail": "The specified organization was not found in the control plane." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "generic_server_error": { "summary": "Generic server error", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/orgs/:orgDid/policies": { "post": { "summary": "Create or Update Organization Policy", "description": "Orchestrate your organization's operations with precision by defining or updating policies. This endpoint enables organizations to enforce rules that govern their conduct within the HUMAN network, ensuring alignment with strategic goals and regulatory requirements.", "operationId": "createOrUpdateOrgPolicy", "tags": [ "Organization", "Policy Management" ], "x-code-hash": "e916b9410007ebc3", "x-generated-at": "2026-03-30T18:02:51.384Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_type": { "type": "string", "enum": [ "marketplace", "agent_autonomy_domain", "audit_retention", "data_residency", "transparency_redaction" ], "description": "The type of policy to apply." }, "policy_rules": { "type": "object", "description": "The rules defining the policy. Specific structure depends on the policy_type." } }, "required": [ "policy_type", "policy_rules" ] }, "examples": { "marketplace_policy": { "summary": "Marketplace Policy", "description": "An example of creating a marketplace policy.", "value": { "policy_type": "marketplace", "policy_rules": { "enforce_strict_transactions": true } } } } } } }, "responses": { "201": { "description": "Policy successfully created or updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the policy." }, "org_did": { "type": "string", "description": "The DID of the organization." }, "policy_type": { "type": "string" }, "policy_rules": { "type": "object" }, "updated_by": { "type": "string", "description": "The passport ID of the person who updated the policy." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request - Invalid input provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid Request", "status": 400, "detail": "policy_type must be one of: marketplace, agent_autonomy_domain, audit_retention, data_residency, transparency_redaction", "errors": [ { "field": "policy_type", "code": "INVALID_ENUM_VALUE", "message": "policy_type must be valid" } ] } } } } } }, "401": { "description": "Unauthorized - Authentication failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "You must authenticate to perform this action." } } } } } }, "403": { "description": "Forbidden - You do not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "Your role does not permit this action. Contact your admin for access." } } } } } }, "404": { "description": "Not Found - Organization or resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "Org 'did:example:acme' not found or you are not a member." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve organization policies list", "description": "Dive into the strategic framework of an organization by retrieving its policies. This endpoint allows you to access the structured set of rules and guidelines that govern an organization identified by its DID. It's a window into understanding how the organization orchestrates its operations.", "operationId": "getOrgPolicies", "tags": [ "Organization", "Policies" ], "x-code-hash": "2dac3bdd56893b5c", "x-generated-at": "2026-03-24T21:59:01.169Z", "responses": { "200": { "description": "Successfully retrieved the list of policies for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "policy_type": { "type": "string" }, "policy_details": { "type": "object" } } } } } }, "examples": { "default": { "summary": "Example", "value": { "data": [ { "policy_type": "data-retention", "policy_details": { "retention_period": "6 months", "review_frequency": "annual" } }, { "policy_type": "access-control", "policy_details": { "roles": [ "admin", "editor", "viewer" ], "permissions": [ "read", "write", "execute" ] } } ] } } } } } }, "400": { "description": "Invalid organization DID provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided organization DID is not valid. Please ensure it is correctly formatted." } } } } } }, "401": { "description": "Authentication token is missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access token is required to authenticate this request. Please provide a valid token." } } } } } }, "403": { "description": "Access to organization's policies is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access the policies of this organization. Please contact your administrator." } } } } } }, "404": { "description": "Organization with specified DID not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The organization with the specified DID could not be found. Please verify the DID and try again." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/orgs/:orgDid/compute-policy": { "put": { "summary": "Configure Organization Compute Policy", "description": "Empower your organization by setting a compute policy that aligns with your operational needs, either opting for self-hosted resources or leveraging HUMAN's infrastructure. This decision impacts cost management and resource allocation, ensuring flexibility and control over computational expenses.", "operationId": "setOrgComputePolicy", "tags": [ "Organization", "Compute" ], "x-code-hash": "69cca029b6e3b13d", "x-generated-at": "2026-03-24T21:59:18.892Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "compute_mode": { "type": "string", "enum": [ "BYOK", "HUMAN_HOSTED" ] }, "compute_policy": { "type": "object", "properties": { "spend_limits": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 } }, "max_cost_per_1k_tokens_usd": { "type": "number", "minimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false }, "examples": { "human_hosted_example": { "summary": "HUMAN Hosted Example", "description": "An organization opting for HUMAN-hosted compute with specified spend limits.", "value": { "compute_mode": "HUMAN_HOSTED", "compute_policy": { "spend_limits": { "ai_processing": 1000 }, "max_cost_per_1k_tokens_usd": 0.05 } } } } } } }, "responses": { "200": { "description": "The compute policy was successfully updated, reflecting the new settings for the organization's computational resources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgDid": { "type": "string" }, "settings": { "type": "object", "properties": { "compute_mode": { "type": "string" }, "compute_policy": { "type": "object" } } } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request is invalid due to incorrect values or format in the compute mode or policy.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid compute_mode", "status": 400, "detail": "compute_mode must be BYOK or HUMAN_HOSTED" } } } } } }, "401": { "description": "Authentication is required and was not provided or is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "A valid Passport is required to access this resource." } } } } } }, "403": { "description": "Access is forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to modify this organization's compute policy." } } } } } }, "404": { "description": "The specified organization does not exist or the user is not a member.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Organization Not Found", "status": 404, "detail": "Org 'did:example:123456789' not found or you are not a member." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/orgs/:orgDid/autonomy": { "put": { "summary": "Configure Organization Autonomy Profile", "description": "Elevate your organization's decision-making capabilities by setting an autonomy profile that aligns with your operational strategy. This endpoint allows you to define how autonomously your systems should operate, striking a balance between human oversight and AI efficiency. Choose from 'Paranoid', 'Balanced', or 'Aggressive' profiles to best suit your organization's needs.", "operationId": "setOrgAutonomyProfile", "tags": [ "Organization Management", "Configuration" ], "x-code-hash": "90eaaab9cd8387cf", "x-generated-at": "2026-03-24T21:59:37.113Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autonomy_profile": { "type": "string", "enum": [ "paranoid", "balanced", "aggressive" ], "description": "Specifies the level of autonomy granted to the organization." } }, "required": [ "autonomy_profile" ] }, "examples": { "balanced_autonomy_profile": { "summary": "Balanced autonomy profile", "description": "Setting the autonomy profile to 'Balanced' for an organization.", "value": { "autonomy_profile": "balanced" } } } } } }, "responses": { "200": { "description": "The autonomy profile was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The decentralized identifier of the organization." }, "autonomy_profile": { "type": "string", "description": "The newly set autonomy profile." }, "settings": { "type": "object", "description": "Additional settings associated with the organization." } } }, "examples": { "successful_update": { "summary": "Successful Update", "description": "Organization's autonomy profile updated to 'Balanced'.", "value": { "org_did": "did:example:123456", "autonomy_profile": "balanced", "settings": { "autonomy_configured": true } } } } } } }, "400": { "description": "Invalid autonomy profile provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid autonomy_profile", "status": 400, "detail": "Must be one of: paranoid, balanced, aggressive" } } } } } }, "401": { "description": "Unauthorized access to the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authorization credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden operation for the current user.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to modify this organization's autonomy profile." } } } } } }, "404": { "description": "Organization not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Organization Not Found", "status": 404, "detail": "Org 'did:example:123456' not found." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while updating the autonomy profile. Please try again later." } } } } } } } } }, "/v1/control-plane/devices": { "get": { "summary": "Retrieve paginated list of devices", "description": "Explore the vast network of devices under your organization's purview. This endpoint allows you to seamlessly paginate through enrolled devices, ensuring you stay on top of your technological landscape. Whether tracking IoT devices or managing enterprise hardware, maintain a clear view of your assets.", "operationId": "getDevices", "tags": [ "Devices", "Control Plane" ], "x-code-hash": "d66a816444cf8885", "x-generated-at": "2026-03-24T21:59:55.734Z", "responses": { "200": { "description": "Successfully retrieved a list of devices with pagination support.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "type": "string" }, "orgDid": { "type": "string" }, "enrolledAt": { "type": "string", "format": "date-time" } } } }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "nextCursor": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "description": "A list of devices for the organization ACME Corp.", "value": { "data": [ { "deviceId": "device-123", "orgDid": "did:org:acme", "enrolledAt": "2023-10-01T12:00:00Z" }, { "deviceId": "device-456", "orgDid": "did:org:acme", "enrolledAt": "2023-09-25T15:30:00Z" } ], "hasMore": false, "limit": 2, "nextCursor": "opaqueCursor123" } } } } } }, "400": { "description": "Invalid request parameters, such as an incorrect pagination cursor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Example of an invalid cursor error", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "Invalid pagination cursor provided.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor from previous response", "received": "badCursor123" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Missing Passport credentials", "value": { "type": "https://example.com/probs/authentication-required", "title": "Unauthorized", "status": 401, "detail": "Passport credentials are required to access this resource." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions to view devices in the specified organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Insufficient permissions", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view devices for this organization." } } } } } }, "404": { "description": "The requested organization or devices could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Organization not found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization with the specified DID does not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Internal server error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "summary": "Register new device in control plane", "description": "Orchestrate the enrollment of a new device within your organization using HUMAN's control plane. Connect devices with the HUMAN network, track their capabilities, and ensure secure task routing with the power of AI. This endpoint is crucial for maintaining seamless operations across distributed systems.", "operationId": "registerDevice", "tags": [ "Device Management", "Control Plane" ], "x-code-hash": "70669ce641baeca6", "x-generated-at": "2026-03-24T22:00:19.727Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier for the organization" }, "device_did": { "type": "string", "description": "Decentralized identifier for the device" }, "label": { "type": "string", "description": "Human-readable label for identifying the device" }, "fingerprint": { "type": "string", "description": "Unique fingerprint for device identification" }, "device_type": { "type": "string", "description": "Type of device, e.g., 'edge', 'cloud'" }, "capabilities": { "type": "object", "description": "Capabilities this device offers as a JSON object" }, "metadata": { "type": "object", "description": "Additional metadata about the device" } }, "required": [ "org_did", "label" ] }, "examples": { "basic_device_enrollment": { "summary": "Basic Device Enrollment", "description": "Enroll a device with essential information", "value": { "org_did": "did:example:123456789abcdefghi", "device_did": "did:example:abcdefghij123456789", "label": "Edge Device #42", "fingerprint": "abc123fingerprint", "device_type": "edge", "capabilities": { "compute": true, "storage": true }, "metadata": { "location": "Data Center A" } } } } } } }, "responses": { "201": { "description": "Device successfully enrolled in the control plane", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the enrolled device" }, "org_did": { "type": "string" }, "device_did": { "type": "string" }, "label": { "type": "string" }, "fingerprint": { "type": "string" }, "device_type": { "type": "string" }, "capabilities": { "type": "object" }, "metadata": { "type": "object" }, "enrolled_by": { "type": "string", "description": "Passport ID of the enroller" } } }, "examples": { "default": { "summary": "Example", "value": { "id": "device-12345", "org_did": "did:example:123456789abcdefghi", "device_did": "did:example:abcdefghij123456789", "label": "Edge Device #42", "fingerprint": "abc123fingerprint", "device_type": "edge", "capabilities": { "compute": true, "storage": true }, "metadata": { "location": "Data Center A" }, "enrolled_by": "passport-xyz123" } } } } } }, "400": { "description": "Bad request due to missing required fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing required fields", "status": 400, "detail": "org_did and label are required." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to enroll this device." } } } } } }, "404": { "description": "Not found error when resources are missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/devices/topology": { "get": { "summary": "Retrieve organizational device topology", "description": "Dive into the intricate web of devices and their interconnections within an organization. This endpoint unveils the topology graph, a vivid map that helps administrators visualize and manage their digital ecosystem efficiently.", "operationId": "getDevicesTopology", "tags": [ "Control Plane", "Topology" ], "x-code-hash": "453197e3142708dc", "x-generated-at": "2026-03-24T22:00:42.231Z", "responses": { "200": { "description": "A successful response providing the nodes and edges representing the organization's device topology.", "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "type": "string" }, "deviceName": { "type": "string" }, "enrolledAt": { "type": "string", "format": "date-time" } }, "required": [ "deviceId", "deviceName", "enrolledAt" ] } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "fromDevice": { "type": "string" }, "toDevice": { "type": "string" } }, "required": [ "fromDevice", "toDevice" ] } } } }, "examples": { "acme_org_device_topology": { "summary": "Acme Org Device Topology", "description": "Visual representation of Acme's interconnected devices.", "value": { "nodes": [ { "deviceId": "dev-001", "deviceName": "Acme Router", "enrolledAt": "2023-10-01T14:48:00Z" }, { "deviceId": "dev-002", "deviceName": "Acme Switch", "enrolledAt": "2023-09-15T08:30:00Z" } ], "edges": [ { "fromDevice": "dev-001", "toDevice": "dev-002" } ] } } } } } }, "400": { "description": "Bad request due to missing or invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid": { "summary": "Missing orgDid", "description": "The request is missing the required 'orgDid' query parameter.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing orgDid", "status": 400, "detail": "org_did query parameter is required." } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Attempt to access without valid credentials.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden due to lack of necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "User lacks permission to access the requested resource.", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "The organization or device was not found.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested organization or device could not be found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "General server error during processing.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/devices/edges": { "post": { "summary": "Create and manage device connections", "description": "Unleash the potential of interconnected devices by forging new pathways between them. This endpoint allows organizations to establish logical edges between devices, weaving a network where data flows seamlessly and securely. By connecting devices, organizations can optimize operations and enhance collaboration.", "operationId": "createDeviceEdge", "tags": [ "Device Management", "Network Configuration" ], "x-code-hash": "54e04ad5fbf90313", "x-generated-at": "2026-03-24T22:01:20.124Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier for the organization" }, "source_device_id": { "type": "string", "description": "Identifier of the source device" }, "target_device_id": { "type": "string", "description": "Identifier of the target device" }, "edge_type": { "type": "string", "description": "Type of edge connecting devices", "default": "data" }, "metadata": { "type": "object", "description": "Additional information about the edge" } }, "required": [ "org_did", "source_device_id", "target_device_id" ] }, "examples": { "connecting_devices_in_acme_corporation": { "summary": "Connecting Devices in Acme Corporation", "description": "This example establishes a data connection between two devices within the Acme organization.", "value": { "org_did": "did:haio:acme", "source_device_id": "device-123", "target_device_id": "device-456", "edge_type": "data", "metadata": { "description": "Edge for real-time data sync" } } } } } } }, "responses": { "201": { "description": "Device connection successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the edge" }, "org_did": { "type": "string", "description": "Decentralized Identifier for the organization" }, "source_device_id": { "type": "string", "description": "Identifier of the source device" }, "target_device_id": { "type": "string", "description": "Identifier of the target device" }, "edge_type": { "type": "string", "description": "Type of edge" }, "metadata": { "type": "object", "description": "Additional information about the edge" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request due to missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing required fields", "status": 400, "detail": "org_did, source_device_id, and target_device_id are required." } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect. Ensure your Passport is valid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create device edges in this organization. Check your Capability Graph." } } } } } }, "404": { "description": "Resource not found for given identifiers", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/notfound", "title": "Resource Not Found", "status": 404, "detail": "The specified devices or organization could not be found. Verify identifiers." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/devices/:deviceId/health": { "patch": { "summary": "Update health status of a device", "description": "In the intricate dance of human and AI collaboration, devices play a pivotal role. This endpoint allows devices to signal their current health status, ensuring timely intervention and seamless operations. By keeping the HUMAN ecosystem informed, we maintain the harmony essential for efficient orchestration.", "operationId": "updateDeviceHealthStatus", "tags": [ "Device Management", "Health Monitoring" ], "x-code-hash": "671171469f5ff878", "x-generated-at": "2026-03-24T22:01:41.234Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "health_status": { "type": "string", "enum": [ "healthy", "degraded", "error", "unknown", "offline" ], "description": "The current health status of the device." } }, "required": [ "health_status" ] }, "examples": { "healthy_device_update": { "summary": "Healthy Device Update", "description": "A device signaling it's in a healthy state.", "value": { "health_status": "healthy" } } } } } }, "responses": { "200": { "description": "The device health status was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the device." }, "health_status": { "type": "string", "description": "The newly updated health status." }, "last_seen_at": { "type": "string", "format": "date-time", "description": "Timestamp of the latest health update." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid health status provided by the device.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid health_status", "status": 400, "detail": "Must be one of: healthy, degraded, error, unknown, offline" } } } } } }, "401": { "description": "Unauthorized access. Authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Invalid or missing authentication credentials. Ensure you are logged in and try again." } } } } } }, "403": { "description": "Forbidden. The device does not have permission to update its health status.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this device's health status. Contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "Device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Device Not Found", "status": 404, "detail": "Device 'device-123' not found. Verify the device ID and try again." } } } } } }, "500": { "description": "Internal server error. Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/events": { "get": { "summary": "Retrieve audit events for an organization", "description": "Navigate through the intricate web of decision-making within your organization with this endpoint, offering a flat timeline of governed decision events. Designed for transparency and accountability, it empowers users to audit actions and decisions made under the auspices of human-AI collaboration.", "operationId": "getControlPlaneAuditEvents", "tags": [ "Audit", "Governance" ], "x-code-hash": "9894767050fe686b", "x-generated-at": "2026-04-14T23:26:02.206Z", "responses": { "200": { "description": "A list of governed decision events in reverse chronological order, supporting pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Unique identifier for the event" }, "orgDid": { "type": "string", "description": "Decentralized identifier for the organization" }, "actorId": { "type": "string", "description": "Passport ID of the actor" }, "decisionType": { "type": "string", "description": "Type of decision made" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the event" } }, "required": [ "eventId", "orgDid", "actorId", "decisionType", "timestamp" ] } }, "limit": { "type": "integer", "description": "Maximum number of events in the response" }, "hasMore": { "type": "boolean", "description": "Indicates if more events are available beyond this page" }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page" } }, "required": [ "data", "limit", "hasMore" ] }, "examples": { "acme_corp_decision_events": { "summary": "Acme Corp Decision Events", "description": "Audit log of Acme Corp showing recent decision events", "value": { "data": [ { "eventId": "evt_12345", "orgDid": "did:human:acme123", "actorId": "passport:john_doe", "decisionType": "APPROVE_INVOICE", "timestamp": "2023-10-10T15:00:00Z" } ], "limit": 50, "hasMore": false, "nextCursor": null } } } } } }, "400": { "description": "Invalid query parameters - ensure cursor and date formats are correct.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_error": { "summary": "Invalid Cursor Error", "description": "Occurs when the provided pagination cursor is malformed or expired.", "value": { "type": "https://example.com/problem/invalid-query-parameters", "title": "Invalid Query Parameters", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor from previous response", "received": "invalid_cursor_string" } ] } } } } } }, "401": { "description": "Unauthorized access - missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "description": "Occurs when a user tries to access the endpoint without valid authentication.", "value": { "type": "https://example.com/problem/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden - the user does not have permission to access these events.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Occurs when a user without the necessary permissions tries to access the events.", "value": { "type": "https://example.com/problem/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these events." } } } } } }, "404": { "description": "Not found - resource not available for the specified organization DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "Occurs when no events are found for the specified organization DID.", "value": { "type": "https://example.com/problem/not-found", "title": "Not Found", "status": 404, "detail": "No governed decision events found for the specified organization DID." } } } } } }, "500": { "description": "Internal server error - something went wrong on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Occurs when there is an unexpected issue on the server.", "value": { "type": "https://example.com/problem/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/graph/:executionId": { "get": { "summary": "Retrieve execution provenance graph", "description": "Dive into the intricate web of task execution with our provenance graph. By querying this endpoint, you uncover the nodes and edges that outline the path your execution traversed. This transparency is not just for oversight but also for insights, enabling you to optimize workflows and trace the lineage of your data processes.", "operationId": "getAuditGraphByExecutionId", "tags": [ "Audit", "Provenance" ], "x-code-hash": "f6df2a00d02b0435", "x-generated-at": "2026-04-14T23:26:24.194Z", "responses": { "200": { "description": "Successfully retrieves the provenance graph of a specific execution, providing a detailed map of nodes and edges that represent the execution's journey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string", "description": "Unique identifier of the execution" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the node" }, "label": { "type": "string", "description": "Descriptive label of the node" } } } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Source node identifier" }, "target": { "type": "string", "description": "Target node identifier" } } } } } }, "examples": { "acme_org's_invoice_processing": { "summary": "Acme Org's Invoice Processing", "description": "Shows the provenance graph for an invoice processing execution at Acme Org.", "value": { "execution_id": "123e4567-e89b-12d3-a456-426614174000", "nodes": [ { "id": "node-1", "label": "Start Task" }, { "id": "node-2", "label": "Validate Invoice" }, { "id": "node-3", "label": "Approve Payment" } ], "edges": [ { "source": "node-1", "target": "node-2" }, { "source": "node-2", "target": "node-3" } ] } } } } } }, "400": { "description": "Execution ID is missing from the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_execution_id": { "summary": "Missing Execution ID", "description": "Occurs when executionId is not provided.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing executionId", "status": 400, "detail": "executionId is required." } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Occurs when the user is not authenticated.", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Occurs when the user lacks necessary permissions.", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Execution not found for the given execution ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "execution_not_found": { "summary": "Execution Not Found", "description": "Occurs when the specified execution ID does not exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Execution not found", "status": 404, "detail": "The specified execution could not be found." } } } } } }, "500": { "description": "Internal server error during graph retrieval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Occurs when an unexpected error happens during processing.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/summaries": { "get": { "summary": "Retrieve AI-generated audit summaries", "description": "Dive into the AI's lens on your organization with this endpoint. It delivers curated summaries generated by our Audit Summarizer Agent, helping you understand the intricate details of your organizational activities. This service empowers users by providing insights that can guide strategic decision-making.", "operationId": "getAuditSummaries", "tags": [ "Audit", "Summaries" ], "x-code-hash": "28e2e44cf06fb66f", "x-generated-at": "2026-04-14T23:26:53.795Z", "responses": { "200": { "description": "Successfully retrieved a list of audit summaries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "summaryId": { "type": "string" }, "orgDid": { "type": "string" }, "persona": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "content": { "type": "string" } }, "required": [ "summaryId", "orgDid", "persona", "generatedAt", "content" ] } } } }, "examples": { "successful_retrieval": { "summary": "Successful retrieval", "description": "An example response where the organization 'acme' reviews its recent audit summaries.", "value": { "data": [ { "summaryId": "summary-123", "orgDid": "did:human:acme", "persona": "compliance-agent", "generatedAt": "2023-10-10T12:00:00Z", "content": "A detailed analysis of compliance events over the past week." } ] } } } } } }, "400": { "description": "Invalid query parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "description": "The client set an invalid limit parameter exceeding the maximum allowed.", "value": { "type": "https://example.com/problems/invalid-query", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'limit' parameter must not exceed 50. Please adjust your request." } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The user attempted to access the endpoint without valid authentication credentials.", "value": { "type": "https://example.com/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication credentials were not provided or are invalid. Please log in and try again." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "The user's credentials do not grant access to audit summaries for the specified organization.", "value": { "type": "https://example.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to view these audit summaries. Please check your access rights." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "summaries_not_found": { "summary": "Summaries Not Found", "description": "No audit summaries were found for the specified criteria.", "value": { "type": "https://example.com/problems/not-found", "title": "Not Found", "status": 404, "detail": "No audit summaries match the provided criteria. Please refine your search parameters." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A general server error occurred while processing the request.", "value": { "type": "https://example.com/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/control-plane/audit/retention": { "get": { "summary": "Retrieve retention policies for organization", "description": "Discover the retention periods your organization has set for its data tiers. By understanding these configurations, you can better align your data management strategies with organizational policies and compliance requirements.", "operationId": "cpAuditGetRetention", "tags": [ "Audit", "Retention" ], "x-code-hash": "f3db86c07c9ebe68", "x-generated-at": "2026-04-14T23:27:17.678Z", "responses": { "200": { "description": "Successfully retrieved retention windows for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The decentralized identifier (DID) of the organization." }, "retention_days_hot": { "type": "integer", "description": "Number of days data is retained in the hot tier (PostgreSQL)." }, "retention_days_warm": { "type": "integer", "description": "Number of days data is retained in the warm tier, if set." }, "retention_days_cold": { "type": "integer", "description": "Number of days data is retained in the cold tier, if set." }, "tiers_implemented": { "type": "array", "items": { "type": "string" }, "description": "List of data storage tiers that are operational." } }, "required": [ "org_did", "retention_days_hot", "tiers_implemented" ] }, "examples": { "example_retention_policy": { "summary": "Example retention policy", "description": "An organization with hot tier retention only.", "value": { "org_did": "did:haio:acme", "retention_days_hot": 30, "retention_days_warm": null, "retention_days_cold": null, "tiers_implemented": [ "hot" ] } } } } } }, "400": { "description": "The request was invalid due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_parameter": { "summary": "Missing orgDid parameter", "description": "The request did not include the required orgDid parameter.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing orgDid", "status": 400, "detail": "org_did is required." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid credentials", "description": "The user attempted to access the endpoint without valid credentials.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "The user lacks the necessary permissions to view retention policies.", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested organization was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization not found", "description": "The orgDid provided does not correspond to any organization.", "value": { "type": "https://haio.run/errors/not-found", "title": "Organization Not Found", "status": 404, "detail": "The specified organization could not be found." } } } } } }, "500": { "description": "Server encountered an unexpected condition that prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "description": "A server-side error occurred while processing the request.", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/control-plane/audit/reports": { "get": { "summary": "Retrieve Pre-built Audit Report Catalog", "description": "Unveil the hidden narratives behind your operations with HUMAN's pre-built audit report catalog. This endpoint grants you a gateway to a curated collection of insightful reports, each designed to shed light on the orchestration of human and AI activities across your organization. Discover patterns, enhance transparency, and drive informed decisions.", "operationId": "getAuditReports", "tags": [ "Audit", "Reports" ], "x-code-hash": "354a64b1d011ac62", "x-generated-at": "2026-04-14T23:27:41.890Z", "responses": { "200": { "description": "Successfully retrieved the catalog of pre-built audit reports.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the report." }, "name": { "type": "string", "description": "The name of the report." }, "description": { "type": "string", "description": "A brief explanation of the report's coverage." }, "frequency": { "type": "string", "description": "How often the report is generated." } }, "required": [ "id", "name", "description", "frequency" ] } } }, "required": [ "data" ] }, "examples": { "sample_report_catalog": { "summary": "Sample Report Catalog", "description": "A glimpse into the diverse range of audit reports available.", "value": { "data": [ { "id": "delegation-usage", "name": "Delegation Usage", "description": "Who used which delegations, when, and for what actions.", "frequency": "weekly" }, { "id": "trust-introduced", "name": "New Trust Introduced", "description": "New delegation grants, agent registrations, and capability assignments.", "frequency": "monthly" }, { "id": "autonomy-vs-approval", "name": "Agent Autonomy vs Human Approvals", "description": "Ratio of auto-executed vs human-approved operations per agent.", "frequency": "weekly" }, { "id": "connector-usage", "name": "Connector Usage", "description": "Per-connector invocation counts, error rates, and latency.", "frequency": "daily" } ] } } } } } }, "400": { "description": "Bad Request due to invalid parameters or malformed request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid Parameters", "description": "Occurs when request parameters do not meet API requirements.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters were invalid." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_token": { "summary": "Missing Token", "description": "Occurs when no authentication token is provided.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Occurs when the user lacks necessary permissions to access the report catalog.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not Found error when the requested resource is unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "catalog_not_found": { "summary": "Catalog Not Found", "description": "Occurs when the audit reports cannot be located.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested report catalog was not found." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "Occurs when an unforeseen error disrupts the process.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/reports/:reportId": { "get": { "summary": "Retrieve detailed audit report data", "description": "Delve into the intricate details of your organization's decision-making footprint. This endpoint executes a selected pre-built audit report, providing insights on delegation, trust changes, autonomy ratios, and connector usage. Use this tool to ensure transparency and governance in your human-AI interactions.", "operationId": "getAuditReport", "tags": [ "Audit", "Reports", "Governance" ], "x-code-hash": "45610247984d9f0e", "x-generated-at": "2026-04-14T23:28:00.952Z", "responses": { "200": { "description": "The audit report was successfully generated and returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "report_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "period_days": { "type": "integer" }, "org_did": { "type": [ "string", "null" ] }, "row_count": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "actor_passport_id": { "type": "string" }, "decision_type": { "type": "string" }, "operation_count": { "type": "integer" }, "last_used_at": { "type": "string", "format": "date-time" }, "first_used_at": { "type": "string", "format": "date-time" } } } } } }, "examples": { "delegation_usage_example": { "summary": "Delegation Usage Example", "description": "Example of a delegation usage report for acme org.", "value": { "report_id": "delegation-usage", "generated_at": "2023-10-01T12:00:00Z", "period_days": 30, "org_did": "did:example:acme", "row_count": 150, "data": [ { "actor_passport_id": "did:example:actor123", "decision_type": "delegation.grant", "operation_count": 25, "last_used_at": "2023-09-30T23:59:59Z", "first_used_at": "2023-09-01T00:00:00Z" } ] } } } } } }, "400": { "description": "Bad Request due to invalid parameters. Ensure query parameters are correctly formatted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing Org DID", "description": "The orgDid parameter is required for certain reports.", "value": { "type": "https://haio.run/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'orgDid' query parameter is required for the delegation-usage report.", "errors": [ "Missing 'orgDid' parameter" ] } } } } } }, "401": { "description": "Unauthorized. Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden. You lack the necessary permissions to access this report.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user attempted to access a report without sufficient permissions.", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to view this report." } } } } } }, "404": { "description": "Report not found. The specified reportId does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "report_not_found": { "summary": "Report Not Found", "description": "The specified reportId does not match any pre-built report.", "value": { "type": "https://haio.run/errors/not-found", "title": "Report not found", "status": 404, "detail": "Report 'invalid-report' is not a valid pre-built report. GET /v1/control-plane/audit/reports for the catalog." } } } } } }, "500": { "description": "Internal Server Error. An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/audit/export": { "get": { "summary": "Export audit events in various formats", "description": "Dive into the rich history of your organization's decisions with the ability to export audit events in CSV or JSON format. This endpoint empowers compliance and oversight by offering a comprehensive view of critical actions taken within your organization. Understand the provenance of your decisions and ensure accountability at every step.", "operationId": "getAuditExport", "tags": [ "Audit", "Export" ], "x-code-hash": "42fd1f116d98dbc0", "x-generated-at": "2026-04-14T23:28:15.024Z", "responses": { "200": { "description": "Successfully retrieved audit events in the requested format.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "decision_type": { "type": "string" }, "actor_passport_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "decision_type", "actor_passport_id", "created_at" ] } }, "count": { "type": "integer" }, "exported_at": { "type": "string", "format": "date-time" } }, "required": [ "data", "count", "exported_at" ] } ] }, "examples": { "json_export_example": { "summary": "JSON Export Example", "description": "A JSON response containing a list of audit events.", "value": { "data": [ { "id": "event123", "decision_type": "approval", "actor_passport_id": "agent456", "created_at": "2023-09-10T14:48:00Z" } ], "count": 1, "exported_at": "2023-09-10T15:00:00Z" } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid": { "summary": "Missing orgDid", "description": "Example of a missing orgDid parameter causing a 400 error.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing orgDid", "status": 400, "detail": "org_did is required for export." } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Attempting to access the endpoint without valid credentials.", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Example of a user without the necessary permissions attempting to export audit events.", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to export audit events for this organization." } } } } } }, "404": { "description": "Not Found when the specified organization does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "Attempting to export audit events for a non-existent organization.", "value": { "type": "https://haio.run/errors/not-found", "title": "Organization Not Found", "status": 404, "detail": "The specified organization does not exist." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Example of a server error occurring during the export process.", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } } }, "/v1/control-plane/audit/billing-category-check": { "get": { "summary": "Audit missing billing categories", "description": "This endpoint performs a crucial audit on cloud metering events to ensure that all entries have a specified billing category. It's essential for maintaining accurate billing and reporting, helping organizations like 'Acme Corp' avoid financial discrepancies.", "operationId": "getBillingCategoryCheck", "tags": [ "Audit", "Billing" ], "x-code-hash": "a59250ad906d4cbd", "x-generated-at": "2026-04-14T23:28:29.358Z", "responses": { "200": { "description": "Successfully retrieved the count of untagged billing events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "untagged_count": { "type": "integer", "description": "Number of metering events missing a billing category in the past hour." }, "checked_at": { "type": "string", "format": "date-time", "description": "Timestamp when the check was performed." } } }, "examples": { "successful_audit_check": { "summary": "Successful Audit Check", "description": "Example response showing a scenario where some events are missing billing categories.", "value": { "untagged_count": 5, "checked_at": "2023-10-05T14:48:00Z" } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Bad Request", "status": 400, "detail": "The request could not be understood by the server due to malformed syntax." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden: The user does not have the necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Not Found: The requested resource could not be located.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal Server Error: An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/control-plane/agents/schedules": { "get": { "summary": "Retrieve Scheduled Agent Tasks", "description": "Unlock a world of precision with the HUMAN platform's schedule viewer. This endpoint reveals the heartbeat of your automated operations, providing a clear view of when each agent is set to act next. It exists to empower proactive management and seamless orchestration of tasks. Hone your command over the Command Plane with this insightful glance into your agents' futures.", "operationId": "getAgentSchedules", "tags": [ "Agent Management", "Scheduling" ], "x-code-hash": "9eee5ae2fb6c44a1", "x-generated-at": "2026-03-24T22:05:42.613Z", "responses": { "200": { "description": "A list of active agent schedules, including timing and status details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "agent_did": { "type": "string" }, "name": { "type": "string" }, "schedule_cron": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" }, "last_run_at": { "type": "string", "format": "date-time" }, "next_run": { "type": [ "string", "null" ] } }, "required": [ "agent_did", "name", "schedule_cron", "status", "trigger_type", "last_run_at" ] } } }, "required": [ "data" ] }, "examples": { "acme_corp's_automation_overview": { "summary": "Acme Corp's Automation Overview", "description": "A snapshot of Acme Corporation's agent schedules, offering a glimpse into their strategic task deployment.", "value": { "data": [ { "agent_did": "did:human:acme:agent123", "name": "Invoice Processor", "schedule_cron": "0 0 * * *", "status": "active", "trigger_type": "scheduled", "last_run_at": "2023-09-25T00:00:00Z", "next_run": null }, { "agent_did": "did:human:acme:agent456", "name": "Data Aggregator", "schedule_cron": "30 2 * * 1", "status": "paused", "trigger_type": "scheduled", "last_run_at": "2023-09-24T02:30:00Z", "next_run": null } ] } } } } } }, "400": { "description": "The request could not be processed due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_query_parameter": { "summary": "Invalid Query Parameter", "description": "An example of a poorly constructed request due to invalid parameters.", "value": { "type": "https://humanapi.com/problems/invalid-query", "title": "Invalid query parameter", "status": 400, "detail": "The query parameter 'foo' is not recognized. Please refer to the documentation for valid query parameters." } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "This response is returned when authentication credentials are missing or invalid.", "value": { "type": "https://humanapi.com/problems/authentication-failed", "title": "Authentication Failed", "status": 401, "detail": "Authentication is required to access this resource. Please provide valid credentials." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "An example where a user attempts to access a resource they do not have permissions for.", "value": { "type": "https://humanapi.com/problems/access-denied", "title": "Access Denied", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "An attempt to retrieve a non-existent agent schedule.", "value": { "type": "https://humanapi.com/problems/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested agent schedule could not be found. Please verify the agent identifier and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A generic error message when the server fails unexpectedly.", "value": { "type": "https://humanapi.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } } }, "/v1/control-plane/agents/:agentDid": { "get": { "summary": "Retrieve Agent by Decentralized ID", "description": "Discover the unique capabilities and skills of a specific agent, identified by their cryptographic Passport. This endpoint is your gateway to understanding the role and history of an agent within the HUMAN ecosystem, offering insights into their past tasks and skillset.", "operationId": "getAgentByDid", "tags": [ "Agents", "Control Plane" ], "x-code-hash": "8e146d47bbe90b8b", "x-generated-at": "2026-03-24T22:05:59.040Z", "responses": { "200": { "description": "Successfully retrieved the agent details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentDid": { "type": "string" }, "name": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "lastActive": { "type": "string", "format": "date-time" } } }, "examples": { "successful_retrieval_of_agent": { "summary": "Successful retrieval of agent", "description": "Details of an agent from ACME Corp known for processing complex invoices.", "value": { "agentDid": "did:human:123456789abcdefghi", "name": "Invoice Processor 3000", "capabilities": [ "capability://invoice.processing", "capability://data.analysis" ], "lastActive": "2023-10-15T14:48:00Z" } } } } } }, "400": { "description": "Request was invalid due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_agentdid": { "summary": "Missing agentDid", "value": { "type": "https://haio.run/errors/validation", "title": "Missing agentDid", "status": 400, "detail": "agentDid is required." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden access when the user lacks permission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this agent's details." } } } } } }, "404": { "description": "Agent not found by the provided DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent not found", "value": { "type": "https://haio.run/errors/not-found", "title": "Agent Not Found", "status": 404, "detail": "No agent found with the DID: did:human:123456789abcdefghi." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/agents/:agentDid/schedule/pause": { "post": { "summary": "Pause an Agent's Active Schedule", "description": "In the dynamic world of Human-AI collaboration, there are moments when pausing an agent's schedule becomes essential. This endpoint empowers you to momentarily halt the operations of an agent, ensuring flexibility and control over automated processes. Whether it's a strategic pause for maintenance or oversight, this endpoint is your tool for agile orchestration.", "operationId": "pauseAgentSchedule", "tags": [ "Agent Management", "Control Plane" ], "x-code-hash": "84b5989ffb79f846", "x-generated-at": "2026-03-24T22:06:13.223Z", "responses": { "200": { "description": "The agent's schedule is successfully paused.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentDid": { "type": "string", "description": "Decentralized Identifier of the paused agent" }, "status": { "type": "string", "description": "Current status of the agent" } }, "required": [ "agentDid", "status" ] }, "examples": { "successful_pausing_of_agent": { "summary": "Successful Pausing of Agent", "description": "The agent's schedule is paused successfully.", "value": { "agentDid": "did:example:acme-agent-123", "status": "paused" } } } } } }, "400": { "description": "Bad request due to missing or malformed agentDid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_agentdid": { "summary": "Missing agentDid", "description": "The request failed because the agentDid was not provided.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing agentDid", "status": 400, "detail": "agentDid is required." } } } } } }, "403": { "description": "Attempt to pause an always-on agent denied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "cannot_pause_always-on_agent": { "summary": "Cannot Pause Always-On Agent", "description": "Attempt to pause a Policy Guardian agent which is not allowed.", "value": { "type": "https://haio.run/errors/agent-always-on", "title": "Cannot Pause Policy Guardian", "status": 403, "detail": "The Policy Guardian agent is always-on per Canon Principle 10 (Human Override). It cannot be paused via autonomy controls." } } } } } }, "404": { "description": "The specified agent could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "description": "The agent specified by the DID does not exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Agent Not Found", "status": 404, "detail": "The agent with DID 'did:example:acme-agent-123' was not found." } } } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A server error occurred, unable to process the request.", "value": { "type": "https://haio.run/errors/internal-server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/agents/:agentDid/pause": { "post": { "summary": "Pause an agent's task execution", "description": "In the dynamic landscape of Human-AI orchestration, there are times when an agent's activities need to be paused for strategic realignment or resource management. This endpoint empowers administrators to pause an agent's task execution, ensuring that only relevant and prioritized tasks continue in the HUMAN ecosystem.", "operationId": "pauseAgentExecution", "tags": [ "Agent Management", "Task Control" ], "x-code-hash": "1b03dcacc1d5d9ab", "x-generated-at": "2026-03-24T22:06:32.601Z", "responses": { "200": { "description": "The agent's tasks have been successfully paused, returning the updated agent status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentDid": { "type": "string", "description": "The DID of the agent that was paused." }, "status": { "type": "string", "enum": [ "paused" ], "description": "The new status of the agent, signifying it is now paused." } } }, "examples": { "agent_paused_successfully": { "summary": "Agent Paused Successfully", "description": "An example where an agent with DID 'did:example:123456789' is paused successfully.", "value": { "agentDid": "did:example:123456789", "status": "paused" } } } } } }, "400": { "description": "Occurs when the agent DID is missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_agent_did": { "summary": "Missing Agent DID", "description": "The agent DID was not provided in the request path.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing agentDid", "status": 400, "detail": "agentDid is required." } } } } } }, "403": { "description": "The Policy Guardian agent cannot be paused due to its always-on status.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "cannot_pause_policy_guardian": { "summary": "Cannot Pause Policy Guardian", "description": "An attempt to pause a Policy Guardian agent, which is not allowed.", "value": { "type": "https://haio.run/errors/agent-always-on", "title": "Cannot Pause Policy Guardian", "status": 403, "detail": "The Policy Guardian agent is always-on per Canon Principle 10 (Human Override). It cannot be paused via autonomy controls." } } } } } }, "404": { "description": "The specified agent was not found, indicating a potential typo or non-existent agent DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "description": "The agent DID 'did:example:nonexistent' does not correspond to an existing agent.", "value": { "type": "https://haio.run/errors/not-found", "title": "Agent Not Found", "status": 404, "detail": "No agent found with DID 'did:example:nonexistent'. Please verify the DID and try again." } } } } } }, "500": { "description": "A server error occurred, preventing the agent from being paused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A generic server error occurred during the pause operation.", "value": { "type": "https://haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please retry the operation or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/agents/:agentDid/schedule": { "put": { "summary": "Update an Agent's Scheduled Tasks", "description": "Empower your AI agents by updating their task schedules with precision and ease. This endpoint allows you to set or clear a recurring task schedule using a familiar cron syntax, ensuring your agents operate at the right time, every time.", "operationId": "updateAgentSchedule", "tags": [ "Agent Management", "Scheduling" ], "x-code-hash": "c68bf8421033bc3f", "x-generated-at": "2026-03-24T22:06:51.548Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule_cron": { "type": [ "string", "null" ], "description": "A valid cron expression for task scheduling. Set to null to clear existing schedule." } }, "required": [ "schedule_cron" ] }, "examples": { "weekly_data_processing": { "summary": "Weekly Data Processing", "description": "Schedule the agent to run data processing every Monday at 3 AM.", "value": { "schedule_cron": "0 3 * * 1" } } } } } }, "responses": { "200": { "description": "The agent's schedule has been successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentDid": { "type": "string", "description": "Decentralized Identifier for the agent." }, "schedule_cron": { "type": [ "string", "null" ], "description": "The updated cron expression for the agent's schedule." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the schedule was updated." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid schedule_cron", "status": 400, "detail": "schedule_cron must be a valid 5 or 6-field cron expression.", "errors": [ "Expected 5 or 6 fields, found 3." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this agent's schedule." } } } } } }, "404": { "description": "The specified agent could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Agent Not Found", "status": 404, "detail": "No agent with DID did:human:agent123 was found. Please verify the agentDid." } } } } } }, "500": { "description": "Internal Server Error due to unforeseen circumstances.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } }, "delete": { "summary": "Remove agent's scheduled tasks", "description": "In the world of ever-adaptive AI, agents must evolve. This endpoint clears the scheduled tasks for a given agent, ensuring they are primed for new missions. By removing outdated schedules, it empowers organizations to dynamically reassign resources as their strategies shift.", "operationId": "deleteAgentSchedule", "tags": [ "Agent Management", "Scheduling" ], "x-code-hash": "19cb743fba0b0b78", "x-generated-at": "2026-03-24T22:07:06.417Z", "responses": { "200": { "description": "The agent's schedule was successfully removed, allowing for new task assignments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_did": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "successful_schedule_removal": { "summary": "Successful Schedule Removal", "value": { "agent_did": "did:human:123456789abcdefghi", "updated_at": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "The request was malformed or missing critical data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_agentdid": { "summary": "Missing agentDid", "value": { "type": "https://haio.run/errors/validation", "title": "Missing agentDid", "status": 400, "detail": "agentDid is required." } } } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "The client does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The specified agent was not found in the system.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The agent with DID did:human:nonexistent was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/agents/:agentDid/resume": { "post": { "summary": "Resume a paused agent's operations", "description": "In the dynamic world of Human-AI collaboration, there's often a need to pause and resume activities as priorities shift. This endpoint breathes life back into a paused agent, enabling it to resume its tasks as part of a larger orchestration. By providing the agent's unique digital identity, you can seamlessly reactivate its capabilities within the HUMAN ecosystem.", "operationId": "resumeAgent", "tags": [ "Agent Management", "Control Plane" ], "x-code-hash": "eab17fab97513d3c", "x-generated-at": "2026-03-24T22:07:24.010Z", "responses": { "200": { "description": "The agent has been successfully resumed, allowing it to perform assigned tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentDid": { "type": "string", "description": "The digital identity of the resumed agent." }, "status": { "type": "string", "description": "The current status of the agent." } }, "required": [ "agentDid", "status" ] }, "examples": { "default": { "summary": "Example", "value": { "agentDid": "did:example:1234567890", "status": "active" } } } } } }, "400": { "description": "Bad Request: Missing or invalid parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing agentDid", "status": 400, "detail": "agentDid is required." } } } } } }, "401": { "description": "Unauthorized: Authentication credentials were missing or incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Authentication required", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden: You do not have permission to resume this agent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/permission", "title": "Permission denied", "status": 403, "detail": "You do not have the necessary permissions to perform this action." } } } } } }, "404": { "description": "Not Found: The specified agent could not be found or is not paused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Agent not found", "status": 404, "detail": "The agent with the specified DID was not found or is not in a paused state." } } } } } }, "500": { "description": "Internal Server Error: An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/agents/:agentDid/autonomy": { "put": { "summary": "Override Agent Autonomy Settings", "description": "Empower your organization by customizing AI agent behaviors for specific tasks. This endpoint allows you to fine-tune the decision-making autonomy of an agent, ensuring it aligns with the unique operational needs of your organization.", "operationId": "updateAgentAutonomy", "tags": [ "Control Plane", "Agent Management" ], "x-code-hash": "ed4c3ac931b786eb", "x-generated-at": "2026-03-24T22:07:58.444Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autonomy_level": { "type": "string", "enum": [ "paranoid", "balanced", "aggressive" ], "description": "The level of autonomy assigned to the agent." }, "org_did": { "type": "string", "description": "The Decentralized Identifier (DID) of the organization setting the override." }, "reason": { "type": "string", "description": "Optional rationale for setting or changing the autonomy level." } }, "required": [ "autonomy_level", "org_did" ] }, "examples": { "balanced_autonomy_for_invoice_processing": { "summary": "Balanced Autonomy for Invoice Processing", "description": "Overrides the autonomy level of an agent handling invoice processing tasks to 'balanced' for the 'acme' organization.", "value": { "autonomy_level": "balanced", "org_did": "org:acme", "reason": "Ensuring proper oversight during financial audits." } } } } } }, "responses": { "200": { "description": "The agent's autonomy settings were successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "org_did": { "type": "string" }, "agent_did": { "type": "string" }, "autonomy_level": { "type": "string" }, "set_by": { "type": "string" }, "reason": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "autonomy_update_success": { "summary": "Autonomy Update Success", "value": { "id": "123e4567-e89b-12d3-a456-426614174000", "org_did": "org:acme", "agent_did": "agent:xyz123", "autonomy_level": "balanced", "set_by": "passport:alice", "reason": "Ensuring proper oversight during financial audits.", "updated_at": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing org_did", "value": { "type": "https://haio.run/errors/validation", "title": "Missing org_did", "status": 400, "detail": "org_did is required for per-agent autonomy overrides.", "errors": [ "org_did is required" ] } }, "invalid_autonomy_level": { "summary": "Invalid autonomy_level", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid autonomy_level", "status": 400, "detail": "Must be one of: paranoid, balanced, aggressive", "errors": [ "autonomy_level is not valid" ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing Credentials", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "User does not have permission to override agent autonomy." } } } } } }, "404": { "description": "The specified agent or organization was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The agent ID provided does not exist." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/agents/:agentDid/actions": { "get": { "summary": "Retrieve recent decision events for an agent", "description": "Uncover the trail of decisions governed by HUMAN's sophisticated orchestration, as this endpoint unveils recent decision events associated with a specific agent. Whether you're monitoring task progress or conducting audits, these events offer a window into the agent's operational history, ensuring transparency and accountability.", "operationId": "getAgentRecentDecisionEvents", "tags": [ "ControlPlane", "Agents" ], "x-code-hash": "6d719ed189deef56", "x-generated-at": "2026-03-24T22:08:16.121Z", "responses": { "200": { "description": "Successfully retrieved recent governed decision events for the specified agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "agent_id": { "type": "string" }, "decision": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "event_id", "agent_id", "decision", "created_at" ] } } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request due to missing or invalid agentDid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing agentDid", "status": 400, "detail": "agentDid is required." } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these decision events." } } } } } }, "404": { "description": "The specified agent was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Agent Not Found", "status": 404, "detail": "No agent found with the specified DID." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/diagnostics/history": { "get": { "summary": "Retrieve diagnostics history for an organization", "description": "Explore the historical diagnostics events of your organization within the HUMAN platform. This endpoint empowers you to audit and trace past events, ensuring transparency and accountability in your AI orchestration. Utilize pagination to navigate large datasets effortlessly.", "operationId": "getDiagnosticsHistory", "tags": [ "Diagnostics", "ControlPlane" ], "x-code-hash": "b8680200e6f9ceee", "x-generated-at": "2026-03-24T22:08:43.821Z", "responses": { "200": { "description": "Successfully retrieved the diagnostics history for the specified organization.", "content": { "application/json": {} } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found error when the specified organization does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/control-plane/incidents": { "get": { "summary": "Retrieve incidents from control plane", "description": "Navigate the complexities of your organization's incident history with precision. This endpoint offers a window into the incidents registered in the control plane, filtered by organizational identity, status, and severity. By analyzing these incidents, organizations can fine-tune their strategies, ensuring smoother operations and fortified defenses.", "operationId": "getControlPlaneIncidents", "tags": [ "IncidentManagement", "ControlPlane" ], "x-code-hash": "a23b4690b10643d3", "x-generated-at": "2026-03-24T22:09:09.708Z", "responses": { "200": { "description": "A paginated list of incidents retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "orgDid": { "type": "string" }, "status": { "type": "string" }, "severity": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "orgDid", "status", "severity", "createdAt" ] } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "data", "hasMore" ] }, "examples": { "successful_retrieval_of_incidents": { "summary": "Successful retrieval of incidents", "description": "An organization reviews their latest incidents to adjust their response strategies.", "value": { "data": [ { "id": "incident-123", "orgDid": "did:example:acme", "status": "open", "severity": "high", "createdAt": "2023-10-04T11:23:45Z" } ], "hasMore": false, "nextCursor": null } } } } } }, "400": { "description": "Bad request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_error": { "summary": "Invalid cursor error", "description": "The request failed due to an incorrectly formatted cursor.", "value": { "type": "https://human.api/error/invalid-request", "title": "Bad Request", "status": 400, "detail": "The provided cursor is invalid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor.", "expected": "opaque cursor from previous response", "received": "fooBar" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing credentials", "description": "Request failed due to absence of valid Passport.", "value": { "type": "https://human.api/error/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Passport credentials are required to access this endpoint." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "Access denied due to lack of sufficient permissions.", "value": { "type": "https://human.api/error/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these incidents." } } } } } }, "404": { "description": "Requested resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "The specified incidents do not exist or have been removed.", "value": { "type": "https://human.api/error/not-found", "title": "Not Found", "status": 404, "detail": "The requested incidents could not be found." } } } } } }, "500": { "description": "Internal server error due to unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "The server encountered an anomaly it couldn't handle.", "value": { "type": "https://human.api/error/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "summary": "Create and escalate incident for review", "description": "In the ever-evolving landscape of digital operations, the ability to swiftly identify and manage incidents is crucial. This endpoint empowers organizations to register new incidents, offering an opportunity for automatic escalation to human review if the incident's severity demands it. With a focus on both speed and accuracy, this API ensures that no critical event goes unnoticed, providing peace of mind and operational resilience.", "operationId": "createIncident", "tags": [ "Incident Management", "Control Plane" ], "x-code-hash": "980d6a431972d6eb", "x-generated-at": "2026-03-31T03:42:07.517Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier (DID) of the organization" }, "title": { "type": "string", "description": "A brief title summarizing the incident" }, "scan_id": { "type": "string", "nullable": true, "description": "Identifier for the scan that detected the incident" }, "source_event_id": { "type": "string", "nullable": true, "description": "ID of the originating event triggering this incident" }, "incident_type": { "type": "string", "default": "anomaly", "description": "Type classification of the incident" }, "severity": { "type": "string", "default": "medium", "enum": [ "low", "medium", "high", "critical" ], "description": "Severity level of the incident" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the incident" }, "blast_radius": { "type": "object", "description": "Estimated impact scope of the incident", "additionalProperties": true }, "proposed_actions": { "type": "array", "items": { "type": "string" }, "description": "List of actions proposed to mitigate the incident" }, "raw_data": { "type": "object", "description": "Raw data associated with the incident", "additionalProperties": true }, "created_by_agent": { "type": "string", "nullable": true, "description": "Agent ID responsible for creating the incident" }, "request_escalation": { "type": "boolean", "default": false, "description": "Indicator whether manual escalation to human review is requested" }, "skip_auto_escalation": { "type": "boolean", "default": false, "description": "Flag to skip automatic escalation based on severity" } }, "required": [ "org_did", "title" ] }, "examples": { "basic_incident_registration": { "summary": "Basic Incident Registration", "description": "Registers an incident with minimal required fields", "value": { "org_did": "did:example:acme", "title": "Unexpected spike in CPU usage", "severity": "high", "request_escalation": true } } } } } }, "responses": { "201": { "description": "Incident successfully registered and possibly escalated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the newly created incident" }, "org_did": { "type": "string", "description": "Organization's DID" }, "incident_type": { "type": "string", "description": "Type of the incident" }, "severity": { "type": "string", "description": "Severity level of the incident" }, "title": { "type": "string", "description": "Title of the incident" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the incident" }, "status": { "type": "string", "description": "Current status of the incident" } } }, "examples": { "default": { "summary": "Example", "description": "The CPU usage spiked unexpectedly, potentially causing performance degradation." } } } } }, "400": { "description": "Bad Request due to missing required fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing required fields", "status": 400, "detail": "org_did and title are required." } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create incidents for this organization." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified resource was not found." } } } } } }, "500": { "description": "Internal server error while processing the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/control-plane/incidents/:incidentId": { "get": { "summary": "Retrieve detailed incident information", "description": "Dive into the heart of incident management with this endpoint, which fetches not only the incident's core details but also a tapestry of linked approvals and external issues. By providing comprehensive insights into each incident, it empowers organizations to understand and resolve issues with precision and efficiency.", "operationId": "getIncidentDetails", "tags": [ "Incidents", "Control Plane" ], "x-code-hash": "4a1c815eb97e26ca", "x-generated-at": "2026-03-31T03:42:27.287Z", "responses": { "200": { "description": "Successfully retrieved incident details including associated approvals and external issues.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the incident." }, "title": { "type": "string", "description": "Brief description of the incident." }, "status": { "type": "string", "description": "Current status of the incident." }, "linked_approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Approval request identifier." }, "status": { "type": "string", "description": "Status of the approval request." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the approval was created." }, "workforce_task_id": { "type": "string", "description": "Task ID related to the workforce." }, "risk_level": { "type": "string", "description": "Risk level associated with the approval." }, "action_description": { "type": "string", "description": "Description of actions taken or required." }, "escalation_console_path": { "type": "string", "description": "Path to the escalation console." }, "workforce_inbox_path": { "type": "string", "description": "Path to the workforce inbox." } } } }, "linked_external_issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "External issue identifier." }, "provider": { "type": "string", "description": "Provider of the external issue." }, "external_key": { "type": "string", "description": "Unique key for the external issue." }, "issue_url": { "type": "string", "format": "uri", "description": "URL to the external issue." }, "fingerprint": { "type": "string", "description": "Unique fingerprint of the external issue." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the external issue was created." } } } }, "workbench_links": { "type": "object", "properties": { "workforce_inbox": { "type": "string", "description": "Link to the workforce inbox." }, "escalation_paths": { "type": "array", "items": { "type": "object", "properties": { "approval_id": { "type": "string", "description": "Approval ID for the escalation." }, "path": { "type": "string", "description": "Console path for the escalation." }, "workforce_task_id": { "type": "string", "description": "Task ID for the workforce." } } } } } } } }, "examples": { "incident_details_with_linked_entities": { "summary": "Incident details with linked entities", "description": "An example response showing a complete incident with associated approval requests and external issues.", "value": { "id": "incident-12345", "title": "Network Outage in Data Center", "status": "Investigating", "linked_approvals": [ { "id": "approval-67890", "status": "Pending", "created_at": "2023-10-01T12:00:00Z", "workforce_task_id": "task-54321", "risk_level": "High", "action_description": "Escalate to network team", "escalation_console_path": "/escalations/approval-67890", "workforce_inbox_path": "/workforce/inbox" } ], "linked_external_issues": [ { "id": "ext-issue-98765", "provider": "Jira", "external_key": "JIRA-1234", "issue_url": "https://jira.example.com/browse/JIRA-1234", "fingerprint": "abc123xyz", "created_at": "2023-10-01T11:45:00Z" } ], "workbench_links": { "workforce_inbox": "/workforce/inbox", "escalation_paths": [ { "approval_id": "approval-67890", "path": "/escalations/approval-67890", "workforce_task_id": "task-54321" } ] } } } } } } }, "400": { "description": "Bad request due to missing or invalid incident ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_incidentid_parameter": { "summary": "Missing incidentId parameter", "description": "Shows what happens when incidentId is not provided.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing incidentId", "status": 400, "detail": "incidentId is required." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_authentication_token": { "summary": "Invalid authentication token", "description": "Response when authentication token is missing or invalid.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "User lacks the necessary permissions to view the incident.", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Incident not found with the specified ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "non-existent_incident_id": { "summary": "Non-existent incident ID", "description": "What happens when the incident ID does not exist.", "value": { "type": "https://haio.run/errors/notfound", "title": "Not Found", "status": 404, "detail": "No incident found with the given ID." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server error example", "description": "A typical server error response.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "patch": { "summary": "Update and escalate incident status seamlessly", "description": "This endpoint breathes life into incident management by allowing seamless status updates and escalations for incidents. It ensures that your organization's response to incidents is swift, keeping security tight and operations smooth. Dive into the orchestration of human and AI with a single call.", "operationId": "updateIncidentStatus", "tags": [ "Incident Management", "Control Plane" ], "x-code-hash": "c259499955e98d7e", "x-generated-at": "2026-03-31T03:42:40.652Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "investigating", "escalated", "resolved", "dismissed" ], "description": "The status to update the incident to." }, "severity": { "type": "integer", "description": "The severity level of the incident." }, "resolution_notes": { "type": "string", "description": "Notes detailing the resolution process, required if status is 'resolved' or 'dismissed'." } } }, "examples": { "escalate_incident": { "summary": "Escalate Incident", "description": "Escalate an incident to human review with detailed notes.", "value": { "status": "escalated", "resolution_notes": "Additional review required due to complexity." } } } } } }, "responses": { "200": { "description": "Successfully updated the incident status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the incident." }, "status": { "type": "string", "description": "The updated status of the incident." }, "resolved_by": { "type": "string", "description": "Passport ID of the resolver." }, "resolved_at": { "type": "string", "format": "date-time", "description": "Timestamp when the incident was resolved." }, "resolution_notes": { "type": "string", "description": "Notes about the resolution." } } }, "examples": { "successful_resolution": { "summary": "Successful Resolution", "description": "Marks the incident as resolved with notes.", "value": { "id": "inc_12345", "status": "resolved", "resolved_by": "passport_67890", "resolved_at": "2023-10-12T07:20:50.52Z", "resolution_notes": "Issue resolved after resetting the server." } } } } } }, "400": { "description": "Invalid request due to incorrect input data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_status": { "summary": "Invalid Status", "description": "The provided status is not allowed.", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid status", "status": 400, "detail": "Must be one of: open, investigating, escalated, resolved, dismissed" } } } } } }, "404": { "description": "The specified incident was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "incident_not_found": { "summary": "Incident Not Found", "description": "No incident matches the provided ID.", "value": { "type": "https://haio.run/errors/not-found", "title": "Incident not found", "status": 404, "detail": "Incident 'inc_12345' not found" } } } } } }, "500": { "description": "A server-side error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Unexpected error during incident escalation.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "esc_patch_inc_12345" } } } } } } } } }, "/v1/control-plane/escalations/:id": { "get": { "summary": "Retrieve specific escalation details", "description": "Discover the current status of a particular escalation request within your workflow. This endpoint empowers agents and systems to track and manage critical escalations, ensuring timely and effective resolution. By understanding the journey of an escalation, teams can enhance their decision-making and responsiveness.", "operationId": "getEscalationById", "tags": [ "Escalations", "Control Plane" ], "x-code-hash": "d2bf9438d80c676d", "x-generated-at": "2026-03-24T22:10:39.961Z", "responses": { "200": { "description": "Escalation details successfully retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the escalation" }, "status": { "type": "string", "description": "Current status of the escalation" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp of when the escalation was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the last update to the escalation" }, "details": { "type": "string", "description": "Additional details about the escalation" } } }, "examples": { "successful_retrieval_of_escalation": { "summary": "Successful retrieval of escalation", "description": "A typical response when fetching an existing escalation", "value": { "id": "esc-12345", "status": "pending", "createdAt": "2023-10-11T14:32:00Z", "updatedAt": "2023-10-12T09:15:00Z", "details": "Awaiting approval from upper management" } } } } } }, "400": { "description": "Invalid request due to missing or malformed id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_id": { "summary": "Missing ID", "description": "Error when no escalation ID is provided", "value": { "type": "https://haio.run/errors/validation", "title": "Missing id", "status": 400, "detail": "id is required." } } } } } }, "401": { "description": "Authentication required to access escalation details", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_request": { "summary": "Unauthenticated request", "description": "Error when the user is not authenticated", "value": { "type": "https://haio.run/errors/authentication", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access escalation details." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "Error when the user lacks the necessary permissions", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view this escalation." } } } } } }, "404": { "description": "Escalation not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "escalation_not_found": { "summary": "Escalation not found", "description": "Error when the escalation ID does not exist", "value": { "type": "https://haio.run/errors/not-found", "title": "Escalation Not Found", "status": 404, "detail": "The escalation with id 'esc-unknown' could not be found." } } } } } }, "500": { "description": "Internal server error while retrieving escalation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "Unexpected error during escalation retrieval", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/escalations/:id/respond": { "post": { "summary": "Respond to an escalation request", "description": "In the dynamic world of Human-AI orchestration, escalations can arise requiring human oversight. This endpoint allows authorized users to respond to such escalations, fostering a collaborative decision-making process between humans and AI, ensuring transparency and accountability in task management.", "operationId": "respondToEscalation_1", "tags": [ "Escalations", "Approvals" ], "x-code-hash": "17f957dd02a203fc", "x-generated-at": "2026-03-24T22:11:01.013Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "description": "The decision on the escalation", "enum": [ "approved", "approved_with_modifications", "rejected", "request_changes", "delegated", "overridden" ] }, "comment": { "type": "string", "description": "Optional comment explaining the decision" }, "modified_params": { "type": "object", "description": "Optional parameters modified during decision" } }, "required": [ "decision" ] }, "examples": { "approve_escalation": { "summary": "Approve Escalation", "description": "An example of approving an escalation with a comment", "value": { "decision": "approved", "comment": "Approved after reviewing the details", "modified_params": {} } } } } } }, "responses": { "200": { "description": "The escalation has been successfully responded to, ensuring the decision is logged and acted upon.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The updated status of the escalation" }, "decision": { "type": "string", "description": "The decision made on the escalation" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request due to missing or invalid fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing id", "status": 400, "detail": "id is required." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Valid Passport credentials are required." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to respond to this escalation." } } } } } }, "404": { "description": "Not Found when the specified escalation does not exist", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Escalation Not Found", "status": 404, "detail": "No escalation found with the specified id." } } } } } }, "409": { "description": "Conflict due to escalation not being in a pending state", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/conflict", "title": "Escalation Not Pending", "status": 409, "detail": "The escalation has already been resolved or is expired." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/billing/subscription": { "get": { "summary": "Retrieve Current Subscription Details", "description": "Unlock the door to your organization's billing insights with this endpoint. It seamlessly fetches the current subscription status, allowing you to explore whether you're in a free trial or a paid plan. This is essential for organizations to keep track of their subscription lifecycle and ensure continuous service.", "operationId": "getBillingSubscription", "tags": [ "Billing", "Subscription" ], "x-code-hash": "4d001c31403b52ee", "x-generated-at": "2026-03-24T22:14:47.874Z", "responses": { "200": { "description": "Successfully retrieved the subscription details, including status, trial end date, and plan name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The current status of the subscription, such as 'active' or 'trial'." }, "trial_ends_at": { "type": "string", "format": "date-time", "description": "The ISO 8601 formatted date when the trial period ends, if applicable." }, "plan_name": { "type": "string", "description": "The name of the subscription plan." } } }, "examples": { "active_subscription_example": { "summary": "Active Subscription Example", "description": "An organization with an active subscription.", "value": { "status": "active", "trial_ends_at": null, "plan_name": "Professional" } }, "trial_subscription_example": { "summary": "Trial Subscription Example", "description": "An organization currently in a trial period.", "value": { "status": "trial", "trial_ends_at": "2023-12-01T00:00:00Z", "plan_name": "Starter" } } } } } }, "403": { "description": "Forbidden: Organization context is required to access billing information.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_context_example": { "summary": "Missing Org Context Example", "description": "The user did not select an organization before accessing billing.", "value": { "type": "https://haio.run/errors/authorization", "title": "Org context required", "status": 403, "detail": "Select an organization before accessing billing. Org context is set via session refresh with orgDid." } } } } } }, "500": { "description": "Internal Server Error: An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An unexpected issue occurred on the server side.", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/billing/plans": { "get": { "summary": "Retrieve Available Billing Plans", "description": "Dive into the diverse world of HUMAN's billing plans. This endpoint uncovers a treasure trove of active plans, each replete with their unique entitlements. By understanding the structure of these plans, organizations can tailor their engagement with HUMAN, ensuring they select the perfect tier that aligns with their operational needs.", "operationId": "getBillingPlans", "tags": [ "Billing", "Plans" ], "x-code-hash": "eb26ec82f0df4514", "x-generated-at": "2026-03-29T15:49:38.892Z", "responses": { "200": { "description": "A detailed list of active billing plans along with their entitlements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan_tier": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "base_fee_usd": { "type": "number" }, "billing_period": { "type": "string" }, "display_order": { "type": "integer" }, "limits": { "type": "object" }, "included_governed_decisions_per_month": { "type": [ "integer", "null" ] }, "governed_decision_overage_per_1k_usd": { "type": [ "number", "null" ] }, "entitlements": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "slug", "base_fee_usd", "billing_period", "display_order", "entitlements" ] } } }, "required": [ "plans" ] }, "examples": { "acme_corp_billing_plan": { "summary": "Acme Corp Billing Plan", "description": "An example illustrating the billing plan details for Acme Corp.", "value": { "plans": [ { "id": "plan_123", "name": "Pro Plan", "slug": "pro-plan", "plan_tier": "Pro", "description": "Advanced features for growing teams.", "base_fee_usd": 99.99, "billing_period": "monthly", "display_order": 1, "limits": { "users": 50, "storage": "100GB" }, "included_governed_decisions_per_month": 1000, "governed_decision_overage_per_1k_usd": 10, "entitlements": [ "priority-support", "analytics" ] } ] } } } } } }, "400": { "description": "The request was malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_example": { "summary": "Malformed Request Example", "description": "An example of a malformed request with missing parameters.", "value": { "type": "https://api.human.com/errors/malformed-request", "title": "Bad Request", "status": 400, "detail": "The request is missing required parameters.", "errors": [] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "When the user fails to provide valid authentication credentials.", "value": { "type": "https://api.human.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Valid authentication credentials are required. Please log in and try again." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "The user is authenticated but does not have the necessary permissions.", "value": { "type": "https://api.human.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these billing plans. Contact your administrator for access." } } } } } }, "404": { "description": "The resource you were trying to reach could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not Found Example", "description": "The endpoint or resource could not be found.", "value": { "type": "https://api.human.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource does not exist. Verify the URL and try again." } } } } } }, "500": { "description": "An unexpected internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "An example of when the server encounters an unexpected condition.", "value": { "type": "https://api.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/billing/portal/session": { "post": { "summary": "Initiate customer billing portal session", "description": "Embark on a seamless journey to manage your organization's billing preferences by starting a session with the Stripe billing portal. This endpoint ensures that your organization is properly set up to handle financial operations, providing a transparent and secure window into your billing world.", "operationId": "createBillingPortalSession", "tags": [ "Billing", "Stripe" ], "x-code-hash": "7d876b50bd660fd4", "x-generated-at": "2026-03-24T22:15:18.944Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "type": "string", "description": "URL to redirect to after session ends." }, "returnUrl": { "type": "string", "description": "Alternative key for return_url." } }, "required": [] }, "examples": { "custom_return_url": { "summary": "Custom Return URL", "description": "Example showing a custom return URL after billing session.", "value": { "return_url": "https://acme.com/dashboard" } } } } } }, "responses": { "200": { "description": "The billing portal session was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to the Stripe billing portal." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The organization does not have a billing customer set up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Access is denied due to missing organizational context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Failed to create billing portal session due to a server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/billing/invoices": { "get": { "summary": "Retrieve organization's billing invoices", "description": "Dive into the financial heartbeat of your organization by accessing the billing invoices tied to your cryptographic identity. This endpoint is essential for organizations to keep track of their financial transactions and ensure transparency in billing processes.", "operationId": "getBillingInvoices", "tags": [ "Billing", "Invoices" ], "x-code-hash": "bc0468f711bd22c7", "x-generated-at": "2026-03-24T22:15:33.486Z", "responses": { "200": { "description": "Successfully retrieved a list of invoices for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount_due": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "billing_reason": { "type": "string" } } } } } }, "examples": { "successful_invoice_retrieval": { "summary": "Successful Invoice Retrieval", "value": { "invoices": [ { "id": "inv_123456", "amount_due": 1500, "currency": "USD", "status": "paid", "billing_reason": "subscription_create" } ] } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "value": { "type": "https://haio.run/errors/invalid-parameter", "title": "Invalid Request Parameter", "status": 400, "detail": "The 'limit' parameter must be a positive integer." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://haio.run/errors/authentication", "title": "Authorization Required", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden access due to lack of organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "value": { "type": "https://haio.run/errors/authorization", "title": "Org context required", "status": 403, "detail": "Select an organization before accessing billing. Org context is set via session refresh with orgDid." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error when retrieving invoices.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } } }, "/v1/orgs/:orgId/workforce/tasks/batch": { "post": { "summary": "Batch Create Tasks for Organization", "description": "Efficiently initiate multiple tasks within an organization at once, saving time and effort. This endpoint is a crucial tool for companies seeking to optimize task management at scale, ensuring all tasks are properly prioritized and tracked.", "operationId": "createBatchTasks", "tags": [ "Task Management", "Workflow" ], "x-code-hash": "6bb3e89a56b10784", "x-generated-at": "2026-04-09T17:45:12.487Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "task_type": { "type": "string", "description": "The specific type of task to be executed." }, "payload": { "type": "object", "additionalProperties": true, "description": "The data required for the task, varying by task type." } }, "required": [ "task_type" ] } }, "batch_options": { "type": "object", "properties": { "priority": { "type": "string", "enum": [ "high", "normal", "low" ], "description": "Sets the priority level for the batch of tasks." }, "sla_hours": { "type": "integer", "description": "Service Level Agreement hours for task completion." }, "callback_url": { "type": "string", "description": "A public HTTPS URL to be notified upon task completion." } } } }, "required": [ "tasks" ] }, "examples": { "batch_task_creation_example": { "summary": "Batch Task Creation Example", "description": "An example showing task creation with priority and callback URL.", "value": { "tasks": [ { "task_type": "invoice_processing", "payload": { "invoice_id": "12345" } }, { "task_type": "data_entry", "payload": { "entry_id": "56789" } } ], "batch_options": { "priority": "high", "sla_hours": 24, "callback_url": "https://acme.com/webhook/task-complete" } } } } } } }, "responses": { "201": { "description": "Tasks successfully created in batch.", "content": { "application/json": { "schema": { "type": "object", "required": [ "batch_id", "task_ids" ], "properties": { "batch_id": { "type": "string", "format": "uuid", "description": "Batch identifier (correlates optional batch callback rows)." }, "task_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Created task ids in the same order as the request `tasks` array." } } } } } }, "400": { "description": "Invalid request due to missing or incorrect fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'tasks' array is required.", "errors": [ { "field": "tasks", "code": "REQUIRED_FIELD_MISSING", "message": "tasks array is required", "expected": "array of { task_type, payload? }", "received": "null" } ] } } } } } }, "500": { "description": "Internal server error during batch task creation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Batch Task Creation Failed", "status": 500, "detail": "An unexpected error occurred." } } } } } } } } }, "/v1/orgs/:orgId/workforce/tasks": { "post": { "summary": "Create a new workforce task for an organization", "description": "This endpoint empowers internal and HumanOS callers to create tasks that are seamlessly integrated into the workforce task queue. By providing a programmatic interface, it allows for the automation and orchestration of task assignments, ensuring that tasks are efficiently routed and managed according to the organization's needs.", "operationId": "createWorkforceTask", "tags": [ "Workforce", "Tasks" ], "x-code-hash": "28e4c778647762af", "x-generated-at": "2026-04-09T17:18:43.386Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task_type": { "type": "string", "description": "The type of task to be created, defining its nature and handling." }, "priority": { "type": "string", "enum": [ "high", "normal", "low" ], "description": "The priority level of the task, influencing its position in the queue." }, "sla_minutes": { "type": "integer", "minimum": 0, "description": "Service Level Agreement time in minutes, indicating the expected completion time." }, "source": { "type": "string", "default": "api", "description": "The origin of the task creation request." }, "payload": { "type": "object", "description": "Additional data relevant to the task, specific to the task type." }, "required_caps": { "type": "array", "items": { "type": "string", "description": "Capabilities required for the task completion." } } }, "required": [ "task_type" ] }, "examples": { "standard_task_creation": { "summary": "Standard Task Creation", "description": "Creating a normal priority task for invoice processing", "value": { "task_type": "invoice_processing", "priority": "normal", "sla_minutes": 30, "source": "api", "payload": { "invoice_id": "INV-12345" }, "required_caps": [ "capability://invoice.read", "capability://invoice.write" ] } } } } } }, "responses": { "201": { "description": "Task successfully created and queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "description": "Unique identifier for the created task." }, "queue_id": { "type": [ "string", "null" ], "description": "Identifier of the queue where the task is placed." }, "assignment_id": { "type": [ "string", "null" ], "description": "Identifier of the assignment, if assigned." }, "worker_id": { "type": [ "string", "null" ], "description": "Identifier of the worker, if already assigned." }, "status": { "type": "string", "enum": [ "queued", "assigned", "auto_resolved" ], "description": "Current status of the task in the workflow." } } }, "examples": { "task_queued": { "summary": "Task Queued", "value": { "task_id": "task-67890", "queue_id": "queue-123", "assignment_id": null, "worker_id": null, "status": "queued" } } } } } }, "400": { "description": "Invalid request due to missing or incorrect parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problems/invalid-request", "title": "Bad Request", "status": 400, "detail": "task_type is required", "errors": [ { "field": "task_type", "code": "REQUIRED_FIELD_MISSING", "message": "task_type is required", "expected": "string", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid" } } } } } }, "403": { "description": "Forbidden action as the user lacks necessary permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create tasks for this organization" } } } } } }, "404": { "description": "Organization not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problems/not-found", "title": "Not Found", "status": 404, "detail": "The specified organization ID does not exist" } } } } } }, "500": { "description": "Internal server error due to unexpected circumstances", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while creating the task" } } } } } } } }, "get": { "summary": "Retrieve workforce tasks for an organization", "description": "Navigate the dynamic world of task management by retrieving a list of tasks for a specified organization. This endpoint empowers you to filter tasks based on status, priority, and queue, while offering seamless pagination to traverse large datasets with ease.", "operationId": "getOrgWorkforceTasks", "tags": [ "Workforce Management", "Tasks" ], "x-code-hash": "32bf2cc5ca4a7822", "x-generated-at": "2026-04-09T17:19:02.519Z", "responses": { "200": { "description": "A list of tasks for the specified organization, with support for filtering and pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "queue_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "successful_task_retrieval": { "summary": "Successful task retrieval", "value": { "data": [ { "task_id": "task-123", "status": "pending", "priority": "high", "queue_name": "Invoice Processing", "created_at": "2023-10-01T12:00:00Z" }, { "task_id": "task-124", "status": "completed", "priority": "low", "queue_name": "Customer Support", "created_at": "2023-09-30T09:00:00Z" } ], "has_more": true, "next_cursor": "eyJ2IjoyLCJwciI6MiwgImNyZWF0ZWRfYXQiOiIyMDIzLTEwLTAxVDEyOjAwOjAwWiIsICJ0YXNrX2lkIjoidGFzay0xMjMifQ==" } } } } } }, "400": { "description": "Invalid request parameters or malformed cursor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid Request", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor from previous response", "received": "invalid_cursor_value" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_example": { "summary": "Unauthorized Example", "value": { "type": "https://example.com/probs/auth", "title": "Unauthorized", "status": 401, "detail": "Invalid or missing authentication token. Please provide a valid token to access the resources." } } } } } }, "403": { "description": "Forbidden access to the specified organization's workforce.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_example": { "summary": "Forbidden Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access the tasks for this organization. Ensure your account has the necessary privileges." } } } } } }, "404": { "description": "Organization or resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not Found Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No organization found with the given ID. Please verify the orgId and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/orgs/:orgId/workforce/tasks/:taskId/status": { "get": { "summary": "Retrieve task status in workforce management", "description": "Discover the current status of a task within the workforce management system. This endpoint helps organizations monitor ongoing tasks, ensuring timely completion and efficient resource allocation by providing detailed insights into each task's lifecycle.", "operationId": "getWorkforceTaskStatus", "tags": [ "Workforce", "Task Management" ], "x-code-hash": "2f2bc627a413d954", "x-generated-at": "2026-04-09T17:12:23.324Z", "responses": { "200": { "description": "Successfully retrieved task status", "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "description": "Unique identifier for the task" }, "status": { "type": "string", "description": "Current status of the task" }, "assigned_worker": { "type": [ "string", "null" ], "description": "ID of the worker assigned to the task, null if unassigned" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the task was completed, null if not completed" } } }, "examples": { "default": { "summary": "Example", "value": { "task_id": "task-12345", "status": "in-progress", "assigned_worker": "worker-6789", "completed_at": null } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The task ID provided is not valid.", "errors": [ "taskId must be a valid UUID." ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided. Ensure you have a valid Passport." } } } } } }, "403": { "description": "Forbidden access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/access-denied", "title": "Access Denied", "status": 403, "detail": "You do not have permission to view this task status. Verify your Passport capabilities." } } } } } }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/task-not-found", "title": "Task Not Found", "status": 404, "detail": "No task found with the given ID. Please verify the task ID and try again." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the task status. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/tasks/:taskId/outcomes": { "get": { "summary": "Retrieve task outcome history", "description": "Uncover the complete history of a task's outcomes, providing a transparent view into its provenance timeline. This endpoint offers organizations a way to trace the evolution of a task, ensuring clarity and accountability in workforce management.", "operationId": "getWorkforceTaskOutcomes", "tags": [ "Workforce", "Tasks", "Outcomes" ], "x-code-hash": "74a82bf63e584290", "x-generated-at": "2026-04-09T17:42:52.830Z", "responses": { "200": { "description": "Successfully retrieved the task outcome history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Outcome rows from `workforce_outcomes`, newest `decided_at` first (same shape as returned by the API).", "items": { "type": "object", "properties": { "outcome_id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "worker_id": { "type": "string", "format": "uuid" }, "decision": { "type": "string", "enum": [ "submitted", "approved", "rejected", "needs_changes", "escalated" ] }, "notes": { "type": "string", "nullable": true }, "risk_class": { "type": "string", "nullable": true }, "artifacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "governed_decision_event_id": { "type": "string", "nullable": true }, "decided_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp in UTC" } } } }, "has_more": { "type": "boolean", "description": "Whether more outcomes exist after this page." }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page; null when `has_more` is false." } }, "required": [ "data", "has_more", "next_cursor" ] }, "examples": { "successful_task_outcome_retrieval": { "summary": "Successful Task Outcome Retrieval", "description": "Retrieve all outcomes for task ID 123 from organization 'acme'.", "value": { "data": [ { "task_id": "123", "outcome_id": "outcome-456", "status": "completed", "decided_at": "2023-09-02T14:48:00Z" }, { "task_id": "123", "outcome_id": "outcome-457", "status": "pending", "decided_at": "2023-09-01T11:30:00Z" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "A request attempted with an invalid cursor value.", "value": { "type": "https://docs.humanplatform.com/errors/invalid-request", "title": "Invalid Request Parameters", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor from previous response", "received": "bad-cursor" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials_example": { "summary": "Missing Credentials Example", "description": "The request is made without providing valid authentication credentials.", "value": { "type": "https://docs.humanplatform.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided. Please include valid credentials in the request." } } } } } }, "403": { "description": "Forbidden access due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "The user does not have permission to access outcomes for this task.", "value": { "type": "https://docs.humanplatform.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please verify your access rights." } } } } } }, "404": { "description": "The requested task or organization could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "task_not_found_example": { "summary": "Task Not Found Example", "description": "The task ID provided does not exist for the specified organization.", "value": { "type": "https://docs.humanplatform.com/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "Task with ID '123' not found in organization 'acme'. Please verify the task ID and try again." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "An unexpected error occurred on the server.", "value": { "type": "https://docs.humanplatform.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/tasks/:taskId/submit": { "post": { "summary": "Submit results for a workforce task", "description": "In the bustling world of HUMAN orchestration, submitting your task results is the final triumphant step. This endpoint ensures that your contributions to the workforce are recorded, verified, and directed towards the next stage of processing. It embodies the harmonious collaboration between human workers and AI, ensuring each task is completed with transparency and efficiency.", "operationId": "submitWorkforceTaskResult", "tags": [ "Workforce", "Tasks" ], "x-code-hash": "b0767084f1f0612a", "x-generated-at": "2026-04-09T17:45:32.551Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "The result data of the task, encapsulating the output produced by the worker." }, "time_spent": { "type": "integer", "description": "Time spent by the worker on this task, in minutes." }, "difficulty_rating": { "type": "integer", "description": "A subjective rating of task difficulty provided by the worker, on a scale from 1 to 5." } }, "required": [ "result" ] }, "examples": { "invoice_processing_task": { "summary": "Invoice Processing Task", "description": "Submission of results for processing an invoice in the 'acme' organization.", "value": { "result": { "invoice_number": "INV-1001", "total_amount": 2500, "approved": true }, "time_spent": 45, "difficulty_rating": 3 } } } } } }, "responses": { "200": { "description": "The task result was successfully submitted and recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "status", "submitted_at", "next_step" ], "properties": { "task_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "submitted" ], "description": "Task awaits reviewer (WC-07)." }, "submitted_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp in UTC when the submission was recorded." }, "next_step": { "type": "string", "description": "Client UX hint for the post-submit flow.", "example": "quality_review" } } } } } }, "400": { "description": "The request body is malformed or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "result object is required", "errors": [ { "field": "result", "code": "REQUIRED_FIELD_MISSING", "message": "The result field is required and must be an object.", "expected": "object", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be an active workforce worker to submit task results." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to submit results for this task." } } } } } }, "404": { "description": "The task specified by `taskId` was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified task does not exist." } } } } } }, "500": { "description": "An internal server error occurred while processing your request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/tasks/:taskId/review": { "post": { "summary": "Submit task review results", "description": "In the world of AI-human collaboration, every task completed deserves a review. This endpoint empowers you to submit your verdict on a task's outcome, ensuring quality and fostering continuous improvement in shared workflows.", "operationId": "submitTaskReview", "tags": [ "Task Management", "Workforce" ], "x-code-hash": "830c95d6f842bb3d", "x-generated-at": "2026-04-09T17:13:27.264Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "boolean", "description": "Indicates if the task result is approved." }, "quality_score": { "type": "number", "description": "A score reflecting the quality of the completed task.", "minimum": 0, "maximum": 100 }, "feedback": { "type": "string", "description": "Optional feedback on the task result." }, "corrections": { "type": "string", "description": "Details of any corrections needed." } }, "required": [ "approved" ] }, "examples": { "positive_review": { "summary": "Positive Review", "description": "Submitting a positive review with high quality score.", "value": { "approved": true, "quality_score": 95, "feedback": "Exceptional work, no corrections needed." } } } } } }, "responses": { "200": { "description": "Task review submitted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "The ID of the reviewed task." }, "status": { "type": "string", "description": "Current status of the task post-review." }, "reviewSummary": { "type": "string", "description": "A summary of the review outcome." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing or incorrect fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body must include an 'approved' boolean field.", "errors": [ { "field": "approved", "code": "REQUIRED_FIELD_MISSING", "message": "approved boolean is required" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/permission-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to review this task." } } } } } }, "404": { "description": "Task not found with the provided ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The task with ID 12345 was not found." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/tasks/:taskId": { "get": { "summary": "Retrieve task details for a workforce", "description": "Explore the inner workings of your organization by retrieving detailed information about a specific workforce task. This endpoint not only reveals the task's status but also uncovers its journey through the organizational queue and current assignment state, providing a comprehensive view of task orchestration.", "operationId": "getWorkforceTaskDetails", "tags": [ "Workforce", "Tasks" ], "x-code-hash": "fc7112c086d042dc", "x-generated-at": "2026-04-09T17:13:50.445Z", "responses": { "200": { "description": "Successfully retrieved task details, including assignment and queue information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The unique identifier for the task." }, "org_id": { "type": "string", "description": "The unique identifier for the organization." }, "queue_name": { "type": "string", "description": "The name of the queue this task is associated with." }, "assignment_id": { "type": [ "string", "null" ], "description": "The unique identifier for the current assignment of the task, if assigned." }, "worker_id": { "type": [ "string", "null" ], "description": "The unique identifier for the worker currently assigned to the task, if assigned." }, "assignment_state": { "type": [ "string", "null" ], "description": "The current state of the task assignment (e.g., 'assigned', 'in-progress', 'completed')." }, "assigned_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The timestamp when the task was last assigned." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The timestamp when the task was started, if applicable." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The timestamp when the task was completed, if applicable." } }, "required": [ "task_id", "org_id" ] }, "examples": { "example_with_completed_task": { "summary": "Example with Completed Task", "description": "A scenario where a task has been completed by a worker.", "value": { "task_id": "task-123", "org_id": "org-acme", "queue_name": "Invoice Processing", "assignment_id": "assign-456", "worker_id": "worker-789", "assignment_state": "completed", "assigned_at": "2023-10-10T14:48:00Z", "started_at": "2023-10-10T14:50:00Z", "completed_at": "2023-10-10T15:00:00Z" } } } } } }, "400": { "description": "Invalid request due to missing or incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_parameter": { "summary": "Missing Parameter", "value": { "type": "https://example.com/probs/invalid-params", "title": "Invalid Request Parameters", "status": 400, "detail": "The 'orgId' parameter is required.", "errors": [ { "field": "orgId", "message": "This parameter cannot be empty." } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this task." } } } } } }, "404": { "description": "Task not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "task_not_found": { "summary": "Task Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Task not found", "status": 404, "detail": "No task found with ID 'task-123' in organization 'org-acme'." } } } } } }, "500": { "description": "Internal server error during task retrieval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/queues": { "get": { "summary": "Retrieve workforce queue details for organization", "description": "Unleash the power of your organization by accessing a detailed view of workforce queues. This endpoint allows you to harness insights into task distribution, easily identifying pending and active tasks across different queues. Perfect for managers seeking to optimize task allocation and ensure smooth operations.", "operationId": "getWorkforceQueues", "tags": [ "Organizations", "Workforce" ], "x-code-hash": "5a98986ce67f82d3", "x-generated-at": "2026-03-27T15:39:57.765Z", "responses": { "200": { "description": "Successfully retrieved a list of workforce queues with task counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "queue_id": { "type": "string", "description": "Unique identifier for the queue" }, "name": { "type": "string", "description": "The name of the workforce queue" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the queue was created" }, "pending_count": { "type": "integer", "description": "Number of tasks in the queue that are pending" }, "active_count": { "type": "integer", "description": "Number of tasks in the queue that are currently active" } }, "required": [ "queue_id", "name", "created_at", "pending_count", "active_count" ] } }, "limit": { "type": "integer", "description": "The maximum number of queues returned" }, "hasMore": { "type": "boolean", "description": "Indicates if there are more queues available beyond the current page" } }, "required": [ "data", "limit", "hasMore" ] }, "examples": { "acme_corp_task_queues": { "summary": "Acme Corp Task Queues", "description": "A snapshot of task queues for Acme Corp, illustrating pending and active tasks.", "value": { "data": [ { "queue_id": "q-1", "name": "Invoice Processing", "created_at": "2023-10-01T12:00:00Z", "pending_count": 5, "active_count": 2 }, { "queue_id": "q-2", "name": "Customer Support", "created_at": "2023-09-29T10:00:00Z", "pending_count": 3, "active_count": 7 } ], "limit": 10, "hasMore": false } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "An example of a request that failed due to an invalid cursor.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Bad Request", "status": 400, "detail": "Invalid pagination cursor", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "valid cursor token", "received": "invalid_token" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_example": { "summary": "Missing Authentication Example", "description": "An example of a request that failed due to missing authentication.", "value": { "type": "https://example.com/probs/auth-required", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "An example of a request that failed due to insufficient permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found_example": { "summary": "Organization Not Found Example", "description": "An example of a request that failed because the organization ID was not found.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization with the given ID was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An example of a request that resulted in a server error.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "summary": "Create a new workforce queue", "description": "In a dynamic organization, managing tasks efficiently is key. This endpoint allows you to create a new queue within your organization's workforce, ensuring that tasks are routed effectively to the right personnel. By defining task types and worker capabilities, you tailor the flow to meet your operational demands.", "operationId": "createWorkforceQueue", "tags": [ "Organization", "Workforce" ], "x-code-hash": "c5debb2327388492", "x-generated-at": "2026-03-27T15:40:18.122Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the queue" }, "description": { "type": "string", "description": "A brief description of the queue" }, "task_types": { "type": "array", "items": { "type": "string" }, "description": "List of task types assigned to this queue" }, "worker_ids": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of workers eligible for this queue" }, "capability_filter": { "type": "object", "description": "Criteria to filter workers based on capabilities" }, "visibility": { "type": "string", "enum": [ "internal_only", "public" ], "description": "Visibility status of the queue" } }, "required": [ "name" ] }, "examples": { "create_a_support_queue": { "summary": "Create a support queue", "description": "Demonstrates creating a queue for handling customer support tasks", "value": { "name": "Customer Support", "description": "Handles all incoming customer queries", "task_types": [ "support_request", "inquiry" ], "worker_ids": [ "worker123", "worker456" ], "capability_filter": { "certification": [ "support-certified" ], "experience": { "min_years": 2 } }, "visibility": "internal_only" } } } } } }, "responses": { "201": { "description": "Queue created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue_id": { "type": "string", "description": "Unique identifier for the created queue" }, "org_id": { "type": "string", "description": "Organization ID the queue belongs to" }, "name": { "type": "string", "description": "Name of the created queue" }, "description": { "type": "string", "description": "Description of the created queue" }, "task_types": { "type": "array", "items": { "type": "string" } }, "worker_ids": { "type": "array", "items": { "type": "string" } }, "capability_filter": { "type": "object" }, "visibility": { "type": "string" } } }, "examples": { "successful_creation_of_support_queue": { "summary": "Successful creation of support queue", "value": { "queue_id": "queue789", "org_id": "acme", "name": "Customer Support", "description": "Handles all incoming customer queries", "task_types": [ "support_request", "inquiry" ], "worker_ids": [ "worker123", "worker456" ], "capability_filter": { "certification": [ "support-certified" ], "experience": { "min_years": 2 } }, "visibility": "internal_only" } } } } } }, "400": { "description": "Bad Request due to validation errors", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_queue_name": { "summary": "Missing queue name", "value": { "type": "https://api.human/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "One or more fields are invalid", "errors": [ { "field": "name", "code": "REQUIRED_FIELD_MISSING", "message": "Queue name is required", "expected": "string", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized access example", "value": { "type": "https://api.human/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect" } } } } } }, "403": { "description": "Forbidden: Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions_example": { "summary": "Insufficient permissions example", "value": { "type": "https://api.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create a queue in this organization" } } } } } }, "404": { "description": "Not Found: Organization not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found_example": { "summary": "Organization not found example", "value": { "type": "https://api.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization ID provided does not exist" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal server error example", "value": { "type": "https://api.human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } } } }, "/v1/orgs/:orgId/workforce/queues/:queueId": { "patch": { "summary": "Update workforce queue details", "description": "Refine your organization's task orchestration by updating key attributes of a workforce queue. Whether enhancing the queue's purpose with a fresh name or adjusting its visibility, this endpoint empowers you to keep task routing aligned with evolving business needs.", "operationId": "updateWorkforceQueue", "tags": [ "Workforce", "Queue Management" ], "x-code-hash": "71874edd4a2a6e0d", "x-generated-at": "2026-03-27T15:40:38.200Z", "responses": { "200": { "description": "The queue was successfully updated.", "content": { "application/json": {} } }, "400": { "description": "Invalid request due to incorrect data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access when the user lacks necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified queue or organization was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/orgs/:orgId/workforce/queues/:queueId/claim": { "post": { "summary": "Claim next task from workforce queue", "description": "This endpoint empowers a registered worker to claim the oldest eligible task from their organization's designated queue. Utilizing a safe, concurrent mechanism, it ensures tasks are claimed exactly once, preventing overlaps and ensuring integrity in task assignment.", "operationId": "claimTaskFromQueue", "tags": [ "Workforce", "Task Management" ], "x-code-hash": "355f53dda38518bb", "x-generated-at": "2026-03-27T15:40:55.521Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation": { "type": "object", "properties": { "to": { "type": "string", "description": "The Passport DID of the worker claiming the task." } }, "required": [ "to" ] } }, "required": [ "delegation" ] }, "examples": { "standard_claim_request": { "summary": "Standard Claim Request", "description": "A worker with a valid Passport DID claims a task.", "value": { "delegation": { "to": "passport:did:worker123" } } } } } } }, "responses": { "200": { "description": "Task successfully claimed by the worker.", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "The unique identifier of the claimed task." }, "taskDetails": { "type": "object", "description": "Details of the claimed task, including metadata relevant to the worker." } } }, "examples": { "successful_task_claim": { "summary": "Successful Task Claim", "value": { "taskId": "task789", "taskDetails": { "title": "Review invoice #456", "dueDate": "2023-11-30T23:59:59Z" } } } } } } }, "204": { "description": "No eligible task found for the worker to claim.", "content": { "application/json": { "examples": { "no_task_available": { "summary": "No Task Available", "value": null } } } } }, "400": { "description": "Malformed request due to incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request_example": { "summary": "Invalid Request Example", "value": { "type": "https://humanapi.com/problems/bad-request", "title": "Bad Request", "status": 400, "detail": "The 'to' field in delegation is missing or malformed." } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "value": { "type": "https://humanapi.com/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "The provided Passport DID is not authenticated." } } } } } }, "403": { "description": "Forbidden action due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_action_example": { "summary": "Forbidden Action Example", "value": { "type": "https://humanapi.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "The worker is not registered as an active workforce member in this organization." } } } } } }, "404": { "description": "Queue or organization not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "value": { "type": "https://humanapi.com/problems/not-found", "title": "Not Found", "status": 404, "detail": "The organization 'acme' or queue 'queue123' does not exist." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_error_example": { "summary": "Internal Error Example", "value": { "type": "https://humanapi.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/routing-rules": { "get": { "summary": "Retrieve organization's task routing rules", "description": "In the bustling world of HUMAN's orchestration, routing rules are the silent conductors ensuring tasks land in the right queues. This API endpoint unveils the orchestration within your organization, mapping each task type to its designated queue, ensuring efficiency and safety in human-AI collaboration.", "operationId": "getOrgWorkforceRoutingRules", "tags": [ "Workforce", "Task Routing" ], "x-code-hash": "a0775018b9196a3f", "x-generated-at": "2026-03-27T15:41:19.512Z", "responses": { "200": { "description": "A list of routing rules detailing how tasks are directed to queues for an organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "task_type": { "type": "string" }, "default_queue_id": { "type": "string" }, "queue_name": { "type": "string" }, "queue_task_types": { "type": "array", "items": { "type": "string" } } }, "required": [ "task_type", "default_queue_id", "queue_name", "queue_task_types" ] } }, "limit": { "type": "integer" }, "cursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "hasMore" ] }, "examples": { "routing_rules_example": { "summary": "Routing Rules Example", "description": "A snapshot of routing rules for an organization.", "value": { "data": [ { "task_type": "invoice_processing", "default_queue_id": "queue-123", "queue_name": "Invoice Queue", "queue_task_types": [ "invoice_processing" ] }, { "task_type": "customer_support", "default_queue_id": "queue-456", "queue_name": "Support Queue", "queue_task_types": [ "customer_support", "technical_support" ] } ], "limit": 10, "hasMore": false } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination_cursor": { "summary": "Invalid Pagination Cursor", "description": "An invalid cursor token is provided.", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid Request Parameters", "status": 400, "detail": "The provided pagination cursor is invalid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "valid cursor token", "received": "INVALIDCURSOR123" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Access token is missing or invalid.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access is denied due to invalid credentials. Ensure your access token is correct and try again." } } } } } }, "403": { "description": "Forbidden access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_forbidden": { "summary": "Access Forbidden", "description": "User lacks the necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these routing rules. Contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "Organization not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "The specified organization ID does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization with ID 'org-789' was not found. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the issue persists." } } } } } } } }, "post": { "summary": "Create or update task routing rule", "description": "Define how tasks are routed by associating them with default queues within your organization. This endpoint empowers automated task distribution, ensuring efficiency and alignment with organizational workflows. By crafting these rules, you enable seamless orchestration between human and AI capabilities, optimizing task management.", "operationId": "createOrUpdateRoutingRule", "tags": [ "Task Routing", "Organization Management" ], "x-code-hash": "fdb01b98c2d738eb", "x-generated-at": "2026-03-27T15:41:41.184Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task_type": { "type": "string", "description": "The type of task this rule applies to." }, "default_queue_id": { "type": "string", "format": "uuid", "description": "The queue ID where tasks of this type are routed by default." }, "requires_human": { "type": "boolean", "description": "Indicates if human intervention is required for this task type." }, "reviewer_count": { "type": "integer", "description": "Number of reviewers needed for tasks of this type." }, "escalation_policy": { "type": "object", "description": "Policy dictating task escalation parameters." } }, "required": [ "task_type", "default_queue_id" ] }, "examples": { "invoice_processing_rule": { "summary": "Invoice Processing Rule", "description": "Example of setting a routing rule for invoice processing tasks.", "value": { "task_type": "invoice_processing", "default_queue_id": "8f8c1d1e-1e1b-4b8a-b6e4-2b3a5e6dbe1e", "requires_human": true, "reviewer_count": 2, "escalation_policy": { "escalation_time": "24h", "notify_roles": [ "manager", "admin" ] } } } } } } }, "responses": { "201": { "description": "The routing rule was successfully created or updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "task_type": { "type": "string" }, "default_queue_id": { "type": "string", "format": "uuid" }, "requires_human": { "type": "boolean" }, "reviewer_count": { "type": "integer" }, "escalation_policy": { "type": "object" } } }, "examples": { "default": { "summary": "Example", "value": { "org_id": "acme-corp", "task_type": "invoice_processing", "default_queue_id": "8f8c1d1e-1e1b-4b8a-b6e4-2b3a5e6dbe1e", "requires_human": true, "reviewer_count": 2, "escalation_policy": { "escalation_time": "24h", "notify_roles": [ "manager", "admin" ] } } } } } } }, "400": { "description": "The request body is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/validation-error", "title": "Invalid request body", "status": 400, "detail": "The request body contains invalid fields.", "errors": [ { "field": "task_type", "code": "REQUIRED_FIELD_MISSING", "message": "task_type is required", "expected": "string", "received": "undefined" }, { "field": "default_queue_id", "code": "REQUIRED_FIELD_MISSING", "message": "default_queue_id is required", "expected": "uuid", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/authentication-error", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/permission-error", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The specified queue was not found in the organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/not-found", "title": "Queue not found", "status": 404, "detail": "Queue '8f8c1d1e-1e1b-4b8a-b6e4-2b3a5e6dbe1e' not found in this organization." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/routing-rules/:ruleId": { "patch": { "summary": "Update Workforce Routing Rule Details", "description": "Fine-tune the orchestration of tasks within your organization by updating a specific workforce routing rule. This endpoint allows you to modify key attributes of a routing rule, ensuring that tasks are efficiently managed and aligned with your organization's evolving needs.", "operationId": "updateWorkforceRoutingRule", "tags": [ "Workforce", "Routing" ], "x-code-hash": "3cf7412a5f2734aa", "x-generated-at": "2026-03-27T15:42:08.180Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_queue_id": { "type": "string", "description": "The ID of the default queue to assign tasks to. Must belong to the organization." }, "requires_human": { "type": "boolean", "description": "Flag indicating if human intervention is required for tasks routed by this rule." }, "reviewer_count": { "type": "integer", "description": "The number of reviewers required for tasks." }, "escalation_policy": { "type": "object", "description": "JSON object detailing the escalation policy." } }, "required": [] }, "examples": { "updating_default_queue_and_reviewers": { "summary": "Updating Default Queue and Reviewers", "description": "Example showcasing updating default queue and reviewer count for a rule.", "value": { "default_queue_id": "queue-1234", "reviewer_count": 2 } } } } } }, "responses": { "200": { "description": "The routing rule was successfully updated with the provided details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule_id": { "type": "string" }, "org_id": { "type": "string" }, "default_queue_id": { "type": "string" }, "requires_human": { "type": "boolean" }, "reviewer_count": { "type": "integer" }, "escalation_policy": { "type": "object" } } }, "examples": { "default": { "summary": "Example", "value": { "rule_id": "rule-5678", "org_id": "acme", "default_queue_id": "queue-1234", "requires_human": true, "reviewer_count": 2, "escalation_policy": {} } } } } } }, "400": { "description": "The request was invalid due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "No fields to update.", "errors": [] } } } } } }, "401": { "description": "The client must authenticate itself to get the requested response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Missing or invalid authentication token." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this routing rule." } } } } } }, "404": { "description": "The server can not find the requested resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "Routing rule 'rule-5678' not found." } } } } } }, "500": { "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "summary": "Remove a workforce routing rule", "description": "In the ever-evolving landscape of AI-driven task management, maintaining an agile and precise routing system is crucial. This endpoint allows organizations to surgically remove outdated or incorrect routing rules, ensuring optimal workflow orchestration and AI safety. By deleting a rule, you streamline your task routing, fostering efficiency and accuracy.", "operationId": "deleteWorkforceRoutingRule", "tags": [ "Workforce Management", "Routing Rules" ], "x-code-hash": "c376e8d1eaf23766", "x-generated-at": "2026-03-27T15:42:27.686Z", "responses": { "204": { "description": "The routing rule was successfully deleted, leaving no trace behind.", "content": { "application/json": { "examples": { "successful_deletion": { "summary": "Successful Deletion", "description": "The routing rule with ID 'rule-12345' for organization 'org-67890' was successfully deleted.", "value": null } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid Parameters", "description": "The request parameters were malformed, possibly due to incorrect data types.", "value": { "type": "https://api.humanprotocol.org/problems/invalid-parameters", "title": "Invalid Parameters", "status": 400, "detail": "The orgId or ruleId parameter is invalid. Ensure both values are correctly formatted UUIDs." } } } } } }, "401": { "description": "Authentication failed due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The request was made without valid authentication credentials.", "value": { "type": "https://api.humanprotocol.org/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required and has failed or has not yet been provided. Please ensure your API token is valid and included in the request headers." } } } } } }, "403": { "description": "Permission denied for the attempted operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_operation": { "summary": "Forbidden Operation", "description": "The user does not have permission to delete this routing rule.", "value": { "type": "https://api.humanprotocol.org/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to delete this routing rule. Please check your role and permissions." } } } } } }, "404": { "description": "The specified routing rule was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "rule_not_found": { "summary": "Rule Not Found", "description": "The routing rule with the specified ID does not exist.", "value": { "type": "https://api.humanprotocol.org/problems/not-found", "title": "Not Found", "status": 404, "detail": "Routing rule 'rule-12345' not found for organization 'org-67890'. Verify that the rule ID and organization ID are correct." } } } } } }, "500": { "description": "An unexpected error occurred on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An internal server error occurred while processing the request.", "value": { "type": "https://api.humanprotocol.org/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while attempting to delete the routing rule. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/orgs/:orgId/workforce/workers": { "get": { "summary": "Retrieve workforce workers by organization", "description": "Dive into the dynamic world of workforce management by fetching a curated list of workers associated with your organization. This endpoint empowers you to filter workers by status and paginate results, ensuring you always have the right people at your fingertips for an efficient operation.", "operationId": "getWorkforceWorkers", "tags": [ "Workforce", "Organization" ], "x-code-hash": "2637bcc5c2f43836", "x-generated-at": "2026-03-27T15:42:46.650Z", "responses": { "200": { "description": "A paginated list of workers with active assignment counts and passport display names.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "worker_id": { "type": "string" }, "org_id": { "type": "string" }, "status": { "type": "string" }, "active_assignments": { "type": "integer" }, "passport_display_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "cursorField": { "type": "string" } } }, "examples": { "successful_retrieval_with_pagination": { "summary": "Successful retrieval with pagination", "description": "Fetching workers for the 'acme' organization with 2 active assignments.", "value": { "data": [ { "worker_id": "w123", "org_id": "org-acme", "status": "active", "active_assignments": 2, "passport_display_name": "John Doe", "created_at": "2023-10-05T12:34:56Z" } ], "hasMore": false, "limit": 10, "cursorField": "created_at" } } } } } }, "400": { "description": "Invalid request parameters were provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "A scenario where an invalid cursor was provided for pagination.", "value": { "type": "https://api.human.com/problems/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The provided pagination cursor is invalid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque cursor from previous response", "received": "invalid_cursor_value" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "An example of a request without valid authentication credentials.", "value": { "type": "https://api.human.com/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access this resource." } } } } } }, "403": { "description": "You do not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "An example where the user lacks sufficient permissions.", "value": { "type": "https://api.human.com/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have the necessary permissions to access this resource." } } } } } }, "404": { "description": "The specified organization could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found_example": { "summary": "Organization Not Found Example", "description": "A request for an organization that does not exist.", "value": { "type": "https://api.human.com/problems/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The organization with ID 'org-unknown' was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "An example of a server-side error.", "value": { "type": "https://api.human.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "summary": "Register a new worker in organization", "description": "This endpoint integrates a human workforce into the HUMAN platform by associating a cryptographic identity, known as a Passport DID, with an organization. This empowers enterprises to harness verified human skills, ensuring efficient task routing and provenance tracking.", "operationId": "registerWorker", "tags": [ "Workforce Management", "Human Resources" ], "x-code-hash": "d1205ca8d5836c94", "x-generated-at": "2026-03-27T15:43:09.482Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "Decentralized Identifier (DID) representing the worker's cryptographic identity." }, "workforce_roles": { "type": "array", "items": { "type": "string" }, "description": "List of roles assigned to the worker within the organization." }, "capability_refs": { "type": "array", "items": { "type": "string", "pattern": "^capability://" }, "description": "References to specific capabilities the worker possesses." }, "max_concurrent": { "type": "integer", "default": 5, "description": "Maximum number of concurrent tasks the worker can handle." } }, "required": [ "passport_did" ] }, "examples": { "register_john_doe": { "summary": "Register John Doe", "description": "Illustrates adding a new worker, John Doe, with specific roles and capabilities.", "value": { "passport_did": "did:example:123456789abcdefghi", "workforce_roles": [ "data-analyst", "quality-assurance" ], "capability_refs": [ "capability://data-analytics", "capability://qa-testing" ], "max_concurrent": 3 } } } } } }, "responses": { "201": { "description": "The worker was successfully registered. The response includes the worker's details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "worker_id": { "type": "string", "description": "Unique identifier for the worker within the organization." }, "org_id": { "type": "string", "description": "Identifier for the organization." }, "passport_did": { "type": "string", "description": "The worker's Passport DID." }, "workforce_roles": { "type": "array", "items": { "type": "string" } }, "capability_refs": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "description": "Current status of the worker." }, "max_concurrent": { "type": "integer" } }, "required": [ "worker_id", "org_id", "passport_did", "status" ] }, "examples": { "default": { "summary": "Example", "value": { "worker_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "org_id": "org-acme", "passport_did": "did:example:123456789abcdefghi", "workforce_roles": [ "data-analyst", "quality-assurance" ], "capability_refs": [ "capability://data-analytics", "capability://qa-testing" ], "status": "active", "max_concurrent": 3 } } } } } }, "400": { "description": "Bad Request due to missing or invalid input data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body is invalid.", "errors": [ { "field": "passport_did", "code": "REQUIRED_FIELD_MISSING", "message": "passport_did is required", "expected": "string (DID format)", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid authentication token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing or invalid authentication token. Please provide a valid bearer token." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to register workers in this organization." } } } } } }, "404": { "description": "Not Found when the specified resources do not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified organization or Passport DID does not exist." } } } } } }, "500": { "description": "Internal Server Error indicating an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/workers/:workerId": { "patch": { "summary": "Update a worker's profile in an organization", "description": "Modify the attributes of a worker within your organization, seamlessly aligning skills and roles. This endpoint empowers organizations to dynamically adapt their workforce capabilities in response to evolving needs, ensuring optimal efficiency and productivity.", "operationId": "updateWorkerProfile", "tags": [ "Organization", "Workforce Management" ], "x-code-hash": "e3e200f41c06f6a8", "x-generated-at": "2026-03-27T15:43:32.179Z", "responses": { "200": { "description": "The worker's profile was successfully updated with the new attributes.", "content": { "application/json": {} } }, "400": { "description": "The request was malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden operation due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified worker or organization could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/orgs/:orgId/workforce/assignments": { "get": { "summary": "Retrieve workforce task assignments", "description": "Discover the orchestration of human and AI efforts by viewing task assignments in your organization. This endpoint empowers workers by displaying their specific tasks, while administrators can observe all assignments across the workforce, enhancing transparency and operational efficiency.", "operationId": "getOrgWorkforceAssignments", "tags": [ "Workforce Management", "Assignments" ], "x-code-hash": "df4408dd041a64aa", "x-generated-at": "2026-03-27T15:43:54.644Z", "responses": { "200": { "description": "Successfully retrieved the list of task assignments for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "worker_id": { "type": "string" }, "task_id": { "type": "string" }, "state": { "type": "string" }, "task_type": { "type": "string" }, "priority": { "type": "number" }, "sla_minutes": { "type": "number" }, "payload": { "type": "object" }, "task_status": { "type": "string" }, "queue_id": { "type": "string" }, "queue_name": { "type": "string" }, "assigned_at": { "type": "string", "format": "date-time" } }, "required": [ "worker_id", "task_id", "state", "assigned_at" ] } }, "limit": { "type": "number" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorField", "hasMore" ] }, "examples": { "acme_corporation_workforce_assignments": { "summary": "Acme Corporation Workforce Assignments", "description": "An example response showing task assignments for workers in the Acme Corporation.", "value": { "data": [ { "worker_id": "abc123", "task_id": "task789", "state": "in_progress", "task_type": "invoice_processing", "priority": 2, "sla_minutes": 120, "payload": { "document_type": "invoice", "amount": 5000 }, "task_status": "active", "queue_id": "queue456", "queue_name": "Invoice Review", "assigned_at": "2023-10-15T08:30:00Z" } ], "limit": 10, "cursorField": "assigned_at", "hasMore": false } } } } } }, "400": { "description": "Invalid request due to incorrect query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_error": { "summary": "Invalid Cursor Error", "description": "An error response indicating the pagination cursor was invalid.", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The pagination cursor provided is not valid. It should be an opaque cursor from a previous response.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor, expected an opaque cursor from previous response, received: abc123cursor" } ] } } } } } }, "401": { "description": "Authentication required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication Error", "description": "An error response when authentication credentials are missing or invalid.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access this resource. Please provide valid credentials." } } } } } }, "403": { "description": "Permission denied for accessing workforce assignments.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied_error": { "summary": "Permission Denied Error", "description": "An error response indicating a lack of permissions to view all assignments.", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to view all workforce assignments. Ensure your account has the necessary permissions." } } } } } }, "404": { "description": "The requested organization or task assignments could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_error": { "summary": "Not Found Error", "description": "An error response when the specified organization or task assignments are not found.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization ID or task assignments you are looking for could not be found. Verify the organization ID and try again." } } } } } }, "500": { "description": "Internal server error encountered while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An error response indicating an unexpected server issue.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try your request again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/assignments/:assignmentId/start": { "post": { "summary": "Initiate a workforce assignment", "description": "Empower your workforce by starting an assignment with precision. This endpoint ensures that tasks are commenced by authorized individuals, maintaining the integrity and flow of organizational operations.", "operationId": "startAssignment", "tags": [ "Workforce", "Assignments" ], "x-code-hash": "6d2b73d6dd1dd90a", "x-generated-at": "2026-03-27T15:44:07.942Z", "responses": { "200": { "description": "Assignment successfully started, returning assignment details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assignmentId": { "type": "string" }, "status": { "type": "string", "enum": [ "started" ] }, "workerId": { "type": "string" } }, "required": [ "assignmentId", "status", "workerId" ] }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was invalid or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Forbidden action due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "Assignment not found or already started.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "Internal server error. Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/orgs/:orgId/workforce/assignments/:assignmentId/complete": { "post": { "summary": "Complete workforce assignment with decision", "description": "Empower your workforce with decisive closure! This endpoint allows a human worker to submit a final decision on a task, completing the assignment with clarity and precision. By enforcing explicit decision-making, it ensures transparency and accountability in task management.", "operationId": "completeAssignment", "tags": [ "Workforce", "Assignments" ], "x-code-hash": "0d678a9e6c392bfc", "x-generated-at": "2026-03-27T15:44:29.034Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected", "needs_changes", "escalated" ], "description": "The final decision made on the assignment." }, "notes": { "type": "string", "description": "Additional notes required if decision is 'rejected' or 'needs_changes'." }, "risk_class": { "type": "string", "description": "Optional risk classification for the decision." }, "artifacts": { "type": "object", "description": "Optional artifacts related to the decision." } }, "required": [ "decision" ] }, "examples": { "approve_assignment": { "summary": "Approve Assignment", "description": "Submitting an 'approved' decision for a completed task.", "value": { "decision": "approved", "notes": "All criteria met. Proceed with closure.", "risk_class": "low", "artifacts": {} } } } } } }, "responses": { "200": { "description": "The assignment was successfully completed with the provided decision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assignment_id": { "type": "string", "description": "The unique identifier of the assignment." }, "decision": { "type": "string", "description": "The decision made on the assignment." }, "status": { "type": "string", "description": "The current status of the assignment." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid input was provided. Check the decision and any required notes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-input", "title": "Invalid Request", "status": 400, "detail": "Invalid decision value provided.", "errors": [ { "field": "decision", "code": "INVALID_VALUE", "message": "decision must be one of: approved, rejected, needs_changes, escalated", "expected": "approved | rejected | needs_changes | escalated", "received": "invalid_option" } ] } } } } } }, "401": { "description": "The user is not authenticated to perform this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You need to be logged in to complete an assignment." } } } } } }, "403": { "description": "User lacks permission to complete the assignment in the specified organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to complete this assignment in this organization." } } } } } }, "404": { "description": "The specified assignment was not found or is not owned by the user.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Assignment not found or not owned by you." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected server error occurred. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/match": { "post": { "summary": "Match workforce based on capabilities", "description": "In a world where tasks demand the right talents, this endpoint finds workers with the exact capabilities your organization needs. By specifying required skills, you enable the HUMAN platform to orchestrate a match that optimizes task routing, ensuring tasks are handled by the most qualified individuals.", "operationId": "matchWorkforceToCapabilities", "tags": [ "Workforce", "Matching" ], "x-code-hash": "f753d99d0f8dec4e", "x-generated-at": "2026-04-01T23:39:47.866Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "required_capabilities": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "Identifier of the required capability" }, "min_weight": { "type": "number", "description": "Minimum weight for the capability match" } }, "required": [ "capability_id" ] }, "description": "List of capabilities with optional minimum weights" }, "limit": { "type": "integer", "maximum": 100, "description": "Maximum number of matches to return" } }, "required": [ "required_capabilities" ] }, "examples": { "basic_capability_match": { "summary": "Basic Capability Match", "description": "Find workers with specific capabilities", "value": { "required_capabilities": [ { "capability_id": "capability://coding", "min_weight": 0.8 }, { "capability_id": "capability://design" } ], "limit": 10 } } } } } }, "responses": { "200": { "description": "Successfully matched workers based on capabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "matches": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier of the worker" }, "match_score": { "type": "number", "description": "Score representing the match quality" }, "availability": { "type": "string", "enum": [ "available", "busy" ], "description": "Current availability of the worker" }, "capabilities": { "type": "array", "description": "List of capabilities the worker possesses" }, "performance": { "type": "object", "description": "Performance metrics of the worker" }, "estimated_response_time": { "type": [ "number", "null" ], "description": "Time estimate for worker response" } } } }, "total_matches": { "type": "integer", "description": "Total number of matched workers" } } }, "examples": { "successful_workforce_match": { "summary": "Successful Workforce Match", "value": { "matches": [ { "did": "did:human:123456789abcdef", "match_score": 1, "availability": "available", "capabilities": [ { "capability_id": "capability://coding", "weight": 0.85 }, { "capability_id": "capability://design", "weight": 0.9 } ], "performance": {}, "estimated_response_time": 30 } ], "total_matches": 1 } } } } } }, "400": { "description": "Validation error due to malformed request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_required_capabilities": { "summary": "Missing Required Capabilities", "value": { "type": "https://api.human.protocol/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "The required_capabilities array is required.", "errors": [ { "field": "required_capabilities", "code": "REQUIRED_FIELD_MISSING", "message": "required_capabilities array is required", "expected": "array of { capability_id, min_weight? }", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://api.human.protocol/problems/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://api.human.protocol/problems/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "value": { "type": "https://api.human.protocol/problems/not-found", "title": "Not Found", "status": 404, "detail": "The specified organization ID was not found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "https://api.human.protocol/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/orgs/:orgId/workforce/events": { "get": { "summary": "Stream workforce events for an organization", "description": "Connect to a real-time stream of workforce events tailored for your organizational role. Designed to keep human agents and AI systems synchronized, this endpoint ensures you never miss an important update in your operational sphere.", "operationId": "getWorkforceEvents", "tags": [ "Workforce", "Events" ], "x-code-hash": "5e57f6b49572b454", "x-generated-at": "2026-03-27T15:45:15.236Z", "responses": { "200": { "description": "Successfully connected to the workforce events stream.", "content": { "application/json": {} } }, "400": { "description": "Invalid request parameters were provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Access forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/humanos/tuning/effective": { "get": { "summary": "Retrieve effective HumanOS tuning actions", "description": "In a world where AI safety and human collaboration are paramount, understanding the effective tuning actions within your HumanOS ecosystem is crucial. This endpoint empowers organizations by offering insights into the most impactful tuning actions, ensuring your AI and human agents are aligned and performing at their best.", "operationId": "getEffectiveTuningActions", "tags": [ "HumanOS", "Tuning" ], "x-code-hash": "02af42ff9135411b", "x-generated-at": "2026-03-26T21:54:08.405Z", "responses": { "200": { "description": "Successfully retrieved the effective tuning actions for the specified scope and organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The Decentralized Identifier (DID) for the organization." }, "scope": { "type": "string", "description": "The scope of the tuning actions, typically 'user'." }, "effective": { "type": "array", "items": { "type": "object", "properties": { "action_type": { "type": "string" }, "payload": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } }, "actions_considered": { "type": "integer", "description": "The number of actions considered to determine the effective set." } } }, "examples": { "successful_response": { "summary": "Successful Response", "description": "A list of effective tuning actions for the organization 'acme'.", "value": { "org_did": "did:human:1234567890abcdef", "scope": "user", "effective": [ { "action_type": "optimize", "payload": { "parameter": "value" }, "created_at": "2023-10-01T12:34:56Z" } ], "actions_considered": 5 } } } } } }, "400": { "description": "Bad request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_scope": { "summary": "Invalid Scope", "description": "The scope provided was not valid.", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'scope' parameter is invalid. Accepted values are 'user' or 'system'." } } } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing Credentials", "description": "No credentials provided for accessing the resource.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please provide valid credentials." } } } } } }, "403": { "description": "Permission denied for the requested resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_forbidden": { "summary": "Access Forbidden", "description": "The user does not have the necessary permissions.", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found for the given organization DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "did_not_found": { "summary": "DID Not Found", "description": "The organization DID does not exist in the database.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "No tuning actions found for the specified organization DID." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "The server encountered an unexpected condition.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/humanos/tuning/compare-default": { "get": { "summary": "Compare Tuning to Default Settings", "description": "This endpoint unveils the hidden drift between your organization's custom HumanOS tuning and the established defaults. By examining this divergence, organizations can ensure their Human-AI orchestration aligns with desired operational standards, enhancing both efficiency and safety.", "operationId": "humanosTuningCompareDefault", "tags": [ "HumanOS", "Tuning" ], "x-code-hash": "616ccdd84936e5e7", "x-generated-at": "2026-03-26T21:54:22.282Z", "responses": { "200": { "description": "Successfully retrieved the comparison between folded tuning actions and package defaults.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier of the organization" }, "scope": { "type": "string", "description": "Scope of the tuning actions, default is 'user'" }, "effective": { "type": "object", "description": "Current effective tuning settings" }, "defaults": { "type": "object", "description": "Default tuning settings" }, "drift": { "type": "object", "properties": { "digest_mode_changed": { "type": "boolean", "description": "Indicates if the digest mode has changed" }, "muted_sources_added": { "type": "array", "items": { "type": "string" }, "description": "List of newly muted sources" } } }, "actions_considered": { "type": "integer", "description": "Number of actions considered in the comparison" } } }, "examples": { "default_tuning_comparison": { "summary": "Default Tuning Comparison", "description": "Illustrates an organization comparing their current settings with default ones.", "value": { "org_did": "did:example:acme", "scope": "user", "effective": { "digest_mode": "enhanced", "muted_sources": [ "external_news" ] }, "defaults": { "digest_mode": "standard", "muted_sources": [] }, "drift": { "digest_mode_changed": true, "muted_sources_added": [ "external_news" ] }, "actions_considered": 150 } } } } } }, "401": { "description": "Authentication required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Example when a user tries to access the endpoint without proper authentication.", "value": { "type": "about:blank", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "Example of a server error when querying the database fails.", "value": { "type": "about:blank", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/tuning/actions": { "post": { "summary": "Create a new tuning action", "description": "This endpoint empowers organizations to tailor their HumanOS interactions by registering tuning actions like setting preferences or muting sources. It's a dynamic tool for enhancing AI safety and operational precision, ensuring that actions align with organizational policies and adaptive learning strategies.", "operationId": "humanosTuningCreateAction", "tags": [ "HumanOS", "Tuning" ], "x-code-hash": "38ad4645839477a2", "x-generated-at": "2026-03-26T21:54:47.229Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action_type": { "type": "string", "enum": [ "revert_tuning", "set_digest_mode", "mute_source", "unmute_source", "set_preference" ], "description": "The type of tuning action to execute" }, "payload": { "type": "object", "description": "Parameters specific to the action type" }, "scope": { "type": "string", "enum": [ "user", "org", "team" ], "description": "The scope of the tuning action" }, "approval_request_id": { "type": "string", "description": "ID for the approval request if required" }, "expires_at": { "type": "string", "format": "date-time", "description": "The expiration time of the tuning action" } }, "required": [ "action_type", "payload" ] }, "examples": { "set_preference_example": { "summary": "Set Preference Example", "description": "Illustrates setting a user preference within allowed parameters", "value": { "action_type": "set_preference", "payload": { "preference_key": "ui.theme", "value": "dark" }, "scope": "user", "expires_at": "2023-12-31T23:59:59Z" } } } } } }, "responses": { "201": { "description": "Tuning action successfully created and registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "action_id": { "type": "string", "description": "Unique identifier of the tuning action" }, "org_did": { "type": "string", "description": "Decentralized identifier for the organization" }, "action_type": { "type": "string", "description": "Type of tuning action performed" }, "scope": { "type": "string", "description": "Scope of the tuning action" }, "payload": { "type": "object", "description": "Details of the executed action" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiration timestamp of the action" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when action was created" } } }, "examples": { "default": { "summary": "Example", "value": { "action_id": "tun123456", "org_did": "did:human:acme", "action_type": "set_preference", "scope": "user", "payload": { "preference_key": "ui.theme", "value": "dark" }, "expires_at": "2023-12-31T23:59:59Z", "created_at": "2023-10-15T12:00:00Z" } } } } } }, "400": { "description": "Invalid request due to malformed input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanos.org/problems/invalid-request", "title": "Invalid Tuning Payload", "status": 400, "detail": "The tuning action payload is not valid.", "errors": [ { "field": "payload", "code": "INVALID_TUNING_PAYLOAD", "message": "Payload must adhere to the registered action type schema.", "expected": "registered tuning action payload", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanos.org/problems/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access this resource." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions or locked policies", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanos.org/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "Org- or team-scoped tuning requires approval_request_id while learning_requires_approval is enabled." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanos.org/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanos.org/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/captures": { "post": { "summary": "Submit new capture for HUMAN orchestration", "description": "Initiate a capture process on the HUMAN platform, enabling seamless orchestration between humans and AI. This endpoint is a pivotal entry point to submit diverse data types for further processing and task routing, ensuring data integrity and provenance within a decentralized system.", "operationId": "postHumanosCapture", "tags": [ "HumanOS", "Capture" ], "x-code-hash": "e475fa6eac278861", "x-generated-at": "2026-03-26T21:50:51.692Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_kind": { "type": "string", "enum": [ "text", "webhook", "audio", "video", "transcript" ], "description": "Identifies the type of data source being captured." }, "submitter_ref": { "type": "string", "description": "Reference to the entity submitting the capture." }, "scope": { "type": "string", "description": "The scope within which the capture is being made, defaults to 'org'." }, "intent": { "type": "string", "description": "The intended outcome or purpose of the capture." }, "payload_ref": { "type": "string", "description": "Reference to the payload data, if applicable." }, "payload": { "type": "object", "description": "The actual data being captured." }, "provenance_parent_id": { "type": "string", "description": "ID of the parent capture, if this is a continuation or related capture." }, "effective_config_keys": { "type": "object", "description": "Configuration keys influencing capture processing." }, "enqueue_invocation": { "type": "boolean", "description": "Flag indicating whether an invocation should be enqueued." }, "enqueue_human_call": { "type": "boolean", "description": "Flag indicating whether a human call task should be queued." }, "invocation_task_type": { "type": "string", "description": "Specifies the type of task to invoke if enqueuing." }, "trace_id": { "type": "string", "description": "Trace identifier for tracking invocation." }, "invocation_input": { "type": "object", "description": "Input details for the invocation task." } }, "required": [ "source_kind" ] }, "examples": { "capture_text_data": { "summary": "Capture Text Data", "description": "Submits a text-based capture for processing by HUMAN.", "value": { "source_kind": "text", "submitter_ref": "did:human:acme-agent", "scope": "org", "intent": "transcription", "payload": { "text": "Meeting notes from the quarterly review." } } } } } } }, "responses": { "201": { "description": "Capture successfully submitted and processed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "capture_id": { "type": "string" }, "org_did": { "type": "string" }, "source_kind": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "submitter_ref": { "type": "string" }, "scope": { "type": "string" }, "payload_ref": { "type": "string" }, "intent": { "type": "string" }, "provenance_parent_id": { "type": "string" }, "effective_config_keys": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "invocation_enqueued": { "type": "boolean" }, "async_execution_id": { "type": "string" }, "capture_invocation_error": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "capture_id": "cap_123456", "org_did": "did:human:acme", "source_kind": "text", "submitted_at": "2023-10-01T12:00:00Z", "submitter_ref": "did:human:acme-agent", "scope": "org", "payload_ref": "ref_987654", "intent": "transcription", "provenance_parent_id": null, "effective_config_keys": {}, "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-01T12:00:00Z", "invocation_enqueued": true, "async_execution_id": "exe_654321", "capture_invocation_error": null } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-input", "title": "Invalid input data", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "source_kind", "code": "INVALID_VALUE", "message": "source_kind must be one of text, webhook, audio, video, transcript", "expected": "enum", "received": "image" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/authentication-required", "title": "Authentication required", "status": 401, "detail": "Delegation required. Please ensure that a valid delegation is provided." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/resource-not-found", "title": "Resource not found", "status": 404, "detail": "The requested resource could not be found. Please verify the endpoint and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve HumanOS Task Captures", "description": "Unlock insights into task orchestration by fetching a list of captures associated with your organization's decentralized identity. This endpoint empowers organizations to track provenance and understand task flows through the HUMAN platform.", "operationId": "getHumanosCaptures", "tags": [ "HumanOS", "TaskManagement" ], "x-code-hash": "851bfbf903189e91", "x-generated-at": "2026-03-26T21:51:17.483Z", "responses": { "200": { "description": "Successfully retrieved the list of task captures, enabling the organization to review and analyze task orchestration details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "capture_id": { "type": "string" }, "org_did": { "type": "string" }, "source_kind": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "submitter_ref": { "type": "string" }, "scope": { "type": "string" }, "payload_ref": { "type": "string" }, "payload": { "type": "object" }, "intent": { "type": "string" }, "provenance_parent_id": { "type": "string" }, "effective_config_keys": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "capture_id", "org_did", "created_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "total_count": { "type": "integer", "nullable": true } } }, "examples": { "successful_capture_retrieval": { "summary": "Successful Capture Retrieval", "description": "An organization retrieves a paginated list of task captures for analysis.", "value": { "data": [ { "capture_id": "cap-12345", "org_did": "did:example:acme", "source_kind": "invoice_processing", "submitted_at": "2023-10-15T12:34:56Z", "submitter_ref": "agent-007", "scope": "financial", "payload_ref": "payload-123", "payload": { "invoice_id": "inv-001", "amount": 1000 }, "intent": "process_invoice", "provenance_parent_id": "parent-001", "effective_config_keys": [ "key1", "key2" ], "created_at": "2023-10-14T11:22:33Z", "updated_at": "2023-10-14T11:22:33Z" } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Invalid request parameters. Likely due to incorrect pagination parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination": { "summary": "Invalid Pagination", "value": { "type": "https://example.com/probs/invalid-pagination", "title": "Invalid Request Parameters", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ "limit must be greater than zero" ] } } } } } }, "401": { "description": "Authentication required. The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://example.com/probs/authentication", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please ensure your request includes valid delegation credentials." } } } } } }, "403": { "description": "Permission denied. The request is authenticated but not authorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please check your access rights." } } } } } }, "404": { "description": "Resource not found. The specified captures could not be located.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "captures_not_found": { "summary": "Captures Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No captures found for the specified organization. Verify the organization DID and try again." } } } } } }, "500": { "description": "Internal server error. An unexpected condition was encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/humanos/captures/:capture_id": { "get": { "summary": "Retrieve detailed capture information", "description": "Uncover the tapestry of HUMAN's orchestration by retrieving detailed information about a specific data capture. This endpoint empowers organizations to track and understand the provenance and intent of their AI and human interactions, enhancing transparency and accountability.", "operationId": "getCaptureDetails", "tags": [ "HumanOS", "Data Capture" ], "x-code-hash": "7150d49e7e2ba837", "x-generated-at": "2026-03-26T21:51:40.722Z", "responses": { "200": { "description": "Successfully retrieved the capture details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "capture_id": { "type": "string", "description": "Unique identifier for the capture" }, "org_did": { "type": "string", "description": "DID of the organization" }, "source_kind": { "type": "string", "description": "Type of source for the capture" }, "submitted_at": { "type": "string", "format": "date-time", "description": "Timestamp when the capture was submitted" }, "submitter_ref": { "type": "string", "description": "Reference to the submitter" }, "scope": { "type": "string", "description": "Scope of the capture" }, "payload_ref": { "type": "string", "description": "Reference to the payload" }, "payload": { "type": "object", "additionalProperties": true, "description": "Actual data captured" }, "intent": { "type": "string", "description": "Intent behind the capture" }, "provenance_parent_id": { "type": "string", "description": "ID of the parent provenance record" }, "effective_config_keys": { "type": "array", "items": { "type": "string" }, "description": "Keys of effective configuration applied" }, "created_at": { "type": "string", "format": "date-time", "description": "Capture creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last update to the capture" } } }, "examples": { "successful_retrieval": { "summary": "Successful retrieval", "description": "Details of a capture from the 'acme' organization.", "value": { "capture_id": "12345", "org_did": "did:example:acme", "source_kind": "sensor", "submitted_at": "2023-10-01T12:00:00Z", "submitter_ref": "agent:john.doe", "scope": "invoice-processing", "payload_ref": "payload:98765", "payload": { "invoice_id": "INV-1001", "amount": 2500, "currency": "USD" }, "intent": "Automated invoice processing", "provenance_parent_id": "prov:67890", "effective_config_keys": [ "config1", "config2" ], "created_at": "2023-09-30T10:00:00Z", "updated_at": "2023-10-01T11:00:00Z" } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameter": { "summary": "Invalid Parameter", "description": "The capture_id parameter was not provided.", "value": { "type": "https://example.com/probs/invalid-parameter", "title": "Invalid Request", "status": 400, "detail": "The capture_id parameter is required but was missing.", "errors": [] } } } } } }, "401": { "description": "Authentication is required but was not provided or failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "The request did not include valid authentication credentials.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required for accessing this resource. Ensure you are providing valid credentials." } } } } } }, "403": { "description": "Forbidden access due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user does not have permission to access the capture.", "value": { "type": "https://example.com/probs/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have permission to access this capture. Verify your access rights or contact your administrator." } } } } } }, "404": { "description": "The specified capture could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "capture_not_found": { "summary": "Capture Not Found", "description": "The capture ID provided does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Capture Not Found", "status": 404, "detail": "No capture found for the specified capture_id. Please verify the ID and try again." } } } } } }, "500": { "description": "Unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/humanos/watches": { "post": { "summary": "Create a new HumanOS watch", "description": "The endpoint empowers organizations to create a monitoring watch on various HumanOS entities, ensuring vigilant oversight and preemptive action. By tracking events, sources, or patterns, it provides a strategic advantage in maintaining operational integrity and safety.", "operationId": "createHumanOSWatch", "tags": [ "HumanOS", "Monitoring" ], "x-code-hash": "3cae46a2488af769", "x-generated-at": "2026-03-26T21:52:03.686Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_ref": { "type": "string", "description": "The reference to the target entity or pattern to watch." }, "watch_kind": { "type": "string", "enum": [ "entity", "source", "event_type", "pattern" ], "description": "The kind of watch to establish, dictating the monitoring scope." }, "owner_ref": { "type": "string", "description": "Identifier for the owner of the watch, defaulting to the context's delegation if not provided." }, "scope": { "type": "string", "description": "Scope of the watch, typically 'org' for organization-wide." }, "schedule": { "type": "object", "description": "JSON object representing the watch's scheduling parameters." } }, "required": [ "target_ref", "watch_kind" ] }, "examples": { "basic_watch_setup": { "summary": "Basic Watch Setup", "description": "Creating a watch for monitoring a specific event type within an organization.", "value": { "target_ref": "event_type:invoice_processed", "watch_kind": "event_type", "owner_ref": "did:example:123456789abcdefghi", "scope": "org", "schedule": { "interval": "daily", "time": "09:00" } } } } } } }, "responses": { "201": { "description": "The watch was successfully created. Returns details of the new watch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "watch_id": { "type": "string" }, "org_did": { "type": "string" }, "target_ref": { "type": "string" }, "watch_kind": { "type": "string" }, "owner_ref": { "type": "string" }, "scope": { "type": "string" }, "schedule": { "type": "object" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad request due to invalid JSON or missing/incorrect fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error during watch creation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "summary": "Retrieve active HumanOS watch entries", "description": "In the HumanOS, watches are guardians of the orchestration protocol, monitoring vast landscapes of tasks and capabilities. This endpoint reveals a curated list of these sentinels, filtered by your organizational identity, ensuring only those you are permitted to view are displayed. The power of delegation and oversight is at your fingertips, enabling you to manage the intricate web of tasks with precision.", "operationId": "getHumanosWatches", "tags": [ "HumanOS", "Monitoring" ], "x-code-hash": "797bda7aa614b667", "x-generated-at": "2026-03-26T21:52:45.642Z", "responses": { "200": { "description": "A list of HumanOS watches successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "watch_id": { "type": "string" }, "org_did": { "type": "string" }, "target_ref": { "type": "string" }, "watch_kind": { "type": "string" }, "owner_ref": { "type": "string" }, "scope": { "type": "string" }, "schedule": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "watch_id", "org_did", "target_ref", "watch_kind", "owner_ref", "scope", "schedule", "status", "created_at", "updated_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total_count": { "type": [ "integer", "null" ] } }, "required": [ "data", "has_more" ] }, "examples": { "acme_corp's_active_watches": { "summary": "Acme Corp's Active Watches", "description": "Retrieve the list of watches currently monitored by Acme Corp, showing task oversight in action.", "value": { "data": [ { "watch_id": "watch-abc123", "org_did": "did:example:acme", "target_ref": "capability://invoice.processing", "watch_kind": "task_monitor", "owner_ref": "did:example:alice", "scope": "global", "schedule": "daily", "status": "active", "created_at": "2023-10-11T08:00:00Z", "updated_at": "2023-10-12T10:00:00Z" } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Invalid request parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit": { "summary": "Invalid Limit", "description": "The limit parameter was not a valid integer.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ "'limit' must be greater than zero" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "The request lacked proper delegation credentials.", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation required. Please provide valid organizational credentials." } } } } } }, "403": { "description": "Forbidden access to the requested resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user lacks necessary permissions to access the resource.", "value": { "type": "https://example.com/probs/permission-error", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "watch_not_found": { "summary": "Watch Not Found", "description": "No watches were found for the specified criteria.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "No watches found for the given organization DID." } } } } } }, "500": { "description": "Server encountered an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "Unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/humanos/watches/:watch_id/evaluate": { "post": { "summary": "Evaluate a Watch Cycle for Feedback", "description": "In the intricate dance between humans and AI, feedback is the music. This endpoint lets organizations capture and store evaluation feedback for a specific watch cycle, enhancing the transparency and auditability of AI decisions. By anchoring an evaluation in the distributed ledger, you ensure that your AI's decisions are not only accountable but also improvable.", "operationId": "evaluateWatchCycle", "tags": [ "HumanOS", "Evaluation" ], "x-code-hash": "e879312c0c9cd487", "x-generated-at": "2026-03-26T21:52:22.600Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provenance_id": { "type": "string", "description": "An optional identifier for provenance tracking, providing a cryptographic link to prior events." } }, "required": [] }, "examples": { "evaluate_watch_with_provenance": { "summary": "Evaluate Watch with Provenance", "description": "An evaluation including a provenance pointer for enhanced traceability", "value": { "provenance_id": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "responses": { "201": { "description": "The evaluation feedback was successfully recorded and stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evaluation_feedback_id": { "type": "string", "description": "Unique ID for the recorded feedback event." }, "watch_id": { "type": "string", "description": "The watch identifier for which feedback was recorded." }, "org_did": { "type": "string", "description": "Decentralized identifier for the organization." }, "evaluated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the evaluation was recorded." }, "provenance_pointer": { "type": "string", "description": "Optional pointer to a provenance record." } } }, "examples": { "default": { "summary": "Example", "value": { "evaluation_feedback_id": "789e4567-e89b-12d3-a456-426614174111", "watch_id": "watch123", "org_did": "did:example:acme", "evaluated_at": "2023-10-01T12:34:56Z", "provenance_pointer": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "400": { "description": "Invalid request payload or parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/bad-request", "title": "Invalid Request", "status": 400, "detail": "The provided provenance_id is not valid.", "errors": [ "provenance_id must be a non-empty string." ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication-required", "title": "Authentication Failed", "status": 401, "detail": "Delegation required. Please include a valid delegation token." } } } } } }, "403": { "description": "The client does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to evaluate this watch." } } } } } }, "404": { "description": "The specified watch could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Watch Not Found", "status": 404, "detail": "The watch with ID watch123 could not be found for organization did:example:acme." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/humanos/watches/:watch_id": { "get": { "summary": "Retrieve details of a specific watch", "description": "Discover the intricate details of a specific HumanOS watch. This endpoint reveals how tasks are orchestrated within your organization by fetching comprehensive data about a watch, including its status and schedule. It's a lens into understanding how tasks are managed and monitored, ensuring the right skills are applied at the right time.", "operationId": "getHumanosWatchById", "tags": [ "HumanOS", "Watches" ], "x-code-hash": "a67e05f94663443d", "x-generated-at": "2026-03-26T21:53:01.301Z", "responses": { "200": { "description": "Successfully retrieved the watch details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "watch_id": { "type": "string" }, "org_did": { "type": "string" }, "target_ref": { "type": "string" }, "watch_kind": { "type": "string" }, "owner_ref": { "type": "string" }, "scope": { "type": "string" }, "schedule": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "watch_id", "org_did", "target_ref", "watch_kind", "owner_ref", "scope", "schedule", "status", "created_at", "updated_at" ] }, "examples": { "watch_details_example": { "summary": "Watch Details Example", "description": "An example showing the details of a specific watch.", "value": { "watch_id": "watch123", "org_did": "did:human:org:acme", "target_ref": "task:invoice-processing", "watch_kind": "realtime", "owner_ref": "agent:john.doe", "scope": "organization", "schedule": "0 0 * * *", "status": "active", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T12:00:00Z" } } } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials_example": { "summary": "Missing Credentials Example", "description": "An error response when no credentials are provided.", "value": { "type": "https://humanprotocol.org/errors/authentication", "title": "Authentication Error", "status": 401, "detail": "Delegation required" } } } } } }, "404": { "description": "The specified watch was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "nonexistent_watch_example": { "summary": "Nonexistent Watch Example", "description": "An error response when the specified watch does not exist.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "Watch not found" } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "generic_server_error_example": { "summary": "Generic Server Error Example", "description": "An error response for a generic server issue.", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/artifacts": { "post": { "summary": "Create a new HUMAN artifact", "description": "This endpoint allows organizations to craft and store digital artifacts, defining their type and metadata for enhanced provenance tracking. It empowers teams to maintain a transparent history of digital creations, facilitating AI collaboration with human oversight.", "operationId": "createHumanosArtifact", "tags": [ "Artifacts", "HumanOS" ], "x-code-hash": "a4d23d4181b7a764", "x-generated-at": "2026-03-26T21:47:22.515Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact_type": { "type": "string", "description": "The type of the artifact, must be a valid dot-namespace kind." }, "metadata": { "type": "object", "description": "Metadata specific to the artifact kind." }, "owner_ref": { "type": "string", "description": "Reference to the owner of the artifact." }, "schema_ref": { "type": "string", "description": "Reference to the schema applicable to the artifact." }, "capture_id": { "type": "string", "description": "Identifier for the capture session, if applicable." }, "title": { "type": "string", "description": "A brief title for the artifact." }, "body": { "type": "object", "description": "The actual content of the artifact." }, "media_type": { "type": "string", "description": "Media type of the artifact content." }, "body_storage_ref": { "type": "string", "description": "Reference for storage of large artifact content." }, "production": { "type": "object", "description": "Production-related metadata." }, "created_by": { "type": "object", "description": "Actor reference for the entity creating the artifact." }, "provenance_summary": { "type": "string", "description": "A summary of the provenance action." } }, "required": [ "artifact_type" ] }, "examples": { "standard_artifact_creation": { "summary": "Standard Artifact Creation", "description": "This example demonstrates creating a basic artifact with essential fields.", "value": { "artifact_type": "document.invoice", "metadata": { "category": "Finance", "author": "John Doe" }, "owner_ref": "did:example:123456", "title": "Q3 Financial Report", "body": { "content": "This is the content of the report." }, "media_type": "application/json" } } } } } }, "responses": { "201": { "description": "The artifact was successfully created and stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact_id": { "type": "string", "description": "Unique identifier for the created artifact." }, "org_did": { "type": "string", "description": "DID of the organization creating the artifact." }, "artifact_type": { "type": "string", "description": "Type of the created artifact." } } }, "examples": { "default": { "summary": "Example", "value": { "artifact_id": "art-xyz123", "org_did": "did:example:123456", "artifact_type": "document.invoice" } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body is not valid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required for this operation." } } } } } }, "403": { "description": "The server understood the request, but it refuses to authorize it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The resource you are looking for does not exist." } } } } } }, "500": { "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve a list of artifacts", "description": "Delve into the HUMAN platform's vast repository of artifacts, each a testimony to the collective intelligence of humans and AI. This endpoint lets you navigate through a curated list of organizational artifacts, filtered by type and lifecycle state, empowering you to track the evolution of human and AI collaboration.", "operationId": "getHumanosArtifacts", "tags": [ "Artifacts", "HumanOS" ], "x-code-hash": "42811a1ca199233f", "x-generated-at": "2026-03-26T21:48:30.148Z", "responses": { "200": { "description": "Successfully retrieved a list of artifacts, optionally filtered by type and lifecycle state, with pagination support.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "artifact_id": { "type": "string", "description": "Unique identifier of the artifact" }, "org_did": { "type": "string", "description": "Decentralized identifier for the organization" }, "artifact_type": { "type": "string", "description": "Type classification of the artifact" }, "schema_ref": { "type": "string", "description": "Reference to the schema used by the artifact" }, "owner_ref": { "type": "string", "description": "Reference to the owner of the artifact" }, "lifecycle_state": { "type": "string", "description": "Current lifecycle state of the artifact" }, "revision": { "type": "integer", "description": "Revision number of the artifact" }, "capture_id": { "type": "string", "description": "Identifier for the capture event associated with the artifact" }, "metadata": { "type": "object", "description": "Additional metadata associated with the artifact" }, "production": { "type": "boolean", "description": "Indicates if the artifact is in production" }, "title": { "type": "string", "description": "Title of the artifact" }, "media_type": { "type": "string", "description": "Media type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp of the artifact" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp of the artifact" } }, "required": [ "artifact_id", "org_did", "artifact_type", "created_at" ] } }, "has_more": { "type": "boolean", "description": "Indicates if there are more artifacts available beyond the current page" }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page of results" }, "total_count": { "type": [ "integer", "null" ], "description": "Total number of artifacts matching the query, if available" } } }, "examples": { "artifacts_list_for_acme_corp": { "summary": "Artifacts list for Acme Corp", "description": "Retrieve a list of artifacts belonging to the Acme Corporation, filtered by type and state.", "value": { "data": [ { "artifact_id": "artifact-1234", "org_did": "did:example:acme", "artifact_type": "document", "schema_ref": "schema-5678", "owner_ref": "owner-9012", "lifecycle_state": "active", "revision": 3, "capture_id": "capture-3456", "metadata": { "subject": "Invoice processing" }, "production": true, "title": "Invoice Document", "media_type": "application/pdf", "created_at": "2023-10-01T12:34:56Z", "updated_at": "2023-10-02T12:34:56Z" } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Invalid request due to malformed query parameters. Ensure all parameters are correct and retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination_parameters": { "summary": "Invalid pagination parameters", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'limit' parameter must be a positive integer." } } } } } }, "401": { "description": "Authentication required. Ensure that the appropriate credentials are provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing authentication", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please authenticate and retry." } } } } } }, "403": { "description": "Access forbidden. You do not have permission to access these artifacts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these artifacts." } } } } } }, "404": { "description": "Artifacts not found. The specified organization or filters did not match any artifacts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_artifacts_found": { "summary": "No artifacts found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No artifacts found matching the specified criteria." } } } } } }, "500": { "description": "Internal server error. An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_scenario": { "summary": "Server error scenario", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/artifacts/:artifact_id": { "patch": { "summary": "Update Artifact Lifecycle State", "description": "This endpoint orchestrates the delicate dance of artifact lifecycle transitions within the HUMAN platform, ensuring compliance with organizational policies. It exists to securely manage the evolution of artifacts, reflecting their journey from inception to completion, while respecting the constraints of the Fourth Law policy.", "operationId": "updateArtifactLifecycleState", "tags": [ "Artifacts", "Lifecycle Management" ], "x-code-hash": "94f0105d18ae4bba", "x-generated-at": "2026-03-26T21:47:43.832Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lifecycle_state": { "type": "string", "description": "The new lifecycle state for the artifact.", "enum": [ "draft", "submitted", "approved", "rejected", "archived" ] }, "approval_request_id": { "type": "string", "description": "The ID of the approval request, required for certain transitions." } }, "required": [ "lifecycle_state" ] }, "examples": { "approve_artifact": { "summary": "Approve Artifact", "description": "Transition an artifact to the approved state with a valid approval request ID.", "value": { "lifecycle_state": "approved", "approval_request_id": "approval-12345" } } } } } }, "responses": { "200": { "description": "Artifact lifecycle updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact_id": { "type": "string", "description": "The unique identifier for the artifact." }, "lifecycle_state": { "type": "string", "description": "The current lifecycle state of the artifact." }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp of the update." } } }, "examples": { "default": { "summary": "Example", "value": { "artifact_id": "artifact-67890", "lifecycle_state": "approved", "updated_at": "2023-11-01T12:45:00Z" } } } } } }, "400": { "description": "Invalid JSON or lifecycle state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.os/errors/invalid-input", "title": "Invalid Request", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON.", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.os/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access this artifact." } } } } } }, "403": { "description": "User is not authorized to perform this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.os/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this artifact." } } } } } }, "404": { "description": "The specified artifact was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.os/errors/not-found", "title": "Artifact Not Found", "status": 404, "detail": "Artifact with ID artifact-67890 not found." } } } } } }, "409": { "description": "Conflict in lifecycle state transition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.os/errors/conflict", "title": "Conflict", "status": 409, "detail": "Artifact lifecycle_state cannot transition as requested.", "errors": [ { "field": "lifecycle_state", "code": "INVALID_ARTIFACT_TRANSITION", "message": "Cannot transition artifact from draft to approved", "expected": "submitted", "received": "approved" } ] } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.os/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } }, "get": { "summary": "Retrieve Artifact with Provenance Details", "description": "Uncover the history and details of an artifact within the HUMAN platform. This endpoint provides not only the artifact's core data but also its provenance and revision chain, ensuring a comprehensive understanding of its journey and transformations. It's designed to empower users with transparency and traceability, crucial for trust in Human-AI orchestration.", "operationId": "getArtifactDetails", "tags": [ "HumanOS", "Artifacts" ], "x-code-hash": "54818a23683ecd10", "x-generated-at": "2026-03-26T21:50:28.437Z", "responses": { "200": { "description": "The artifact details were successfully retrieved, including provenance and revision chain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "sequence": { "type": "integer" }, "action": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } }, "revision_chain": { "type": "array", "items": { "type": "string" } } } }, "examples": { "acme_corp_artifact_retrieval": { "summary": "Acme Corp Artifact Retrieval", "description": "Retrieve artifact details for Acme Corp's invoice processing system.", "value": { "artifact_id": "artifact-12345", "name": "Invoice Processing System", "description": "Handles the processing of invoices for Acme Corp.", "created_at": "2023-10-01T12:00:00Z", "provenance": [ { "sequence": 1, "action": "created", "timestamp": "2023-09-01T12:00:00Z" }, { "sequence": 2, "action": "updated", "timestamp": "2023-09-15T12:00:00Z" } ], "revision_chain": [ "rev-abcde", "rev-fghij" ] } } } } } }, "400": { "description": "The request was invalid. Ensure the artifact_id is correctly formatted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_artifact_id_format": { "summary": "Invalid Artifact ID Format", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid request", "status": 400, "detail": "The provided artifact ID is not in a valid format. Please check and try again." } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_required": { "summary": "Delegation Required", "value": { "type": "https://humanprotocol.org/errors/authentication-required", "title": "Authentication required", "status": 401, "detail": "Delegation required. Please authenticate and try again." } } } } } }, "404": { "description": "The specified artifact was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "artifact_not_found": { "summary": "Artifact Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not found", "status": 404, "detail": "Artifact not found. Verify the artifact ID and organization DID." } } } } } }, "500": { "description": "An internal server error occurred. Please try again later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/artifacts/:artifact_id/explain": { "get": { "summary": "Retrieve artifact explanation bundle", "description": "Dive deep into the workings of your AI artifact with this endpoint. It unveils the intricate policies and learning adaptations that shape your artifact's lifecycle, providing insights into the AI decisions and their provenance. This is where AI transparency meets operational intelligence.", "operationId": "getArtifactExplainBundle", "tags": [ "HumanOS", "Artifact" ], "x-code-hash": "ccf17aed75a21921", "x-generated-at": "2026-03-26T21:48:02.343Z", "responses": { "200": { "description": "Successfully retrieved the explanation bundle for the specified artifact, including policy details and learning adaptations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "description": "A brief summary of the artifact's state and applied policy." }, "factors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "string", "enum": [ "policy", "preference", "inference", "fact" ] } } } }, "related_work_refs": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "artifact", "capture", "watch", "approval_request", "async_execution", "workforce_task", "learning_proposal", "tuning_action", "feedback_event" ] }, "id": { "type": "string" }, "org_did": { "type": "string" } } } }, "confidence": { "type": "object", "properties": { "score": { "type": [ "number", "null" ] }, "policy_applied_id": { "type": "string" } } }, "learning": { "$ref": "#/components/schemas/LearningExplainMetadata" } } }, "examples": { "artifact_explanation_for_acme_corp": { "summary": "Artifact explanation for Acme Corp", "description": "An insightful explanation of an artifact belonging to Acme Corp, revealing its state and the decisions influencing it.", "value": { "summary": "Artifact 12345 is in state active. Effective HumanOS org policy (P8) is applied as hos_pol:acme:2023-10-05T14:48:00Z.", "factors": [ { "code": "lifecycle", "label": "Lifecycle", "detail": "active", "source": "fact" }, { "code": "fourth_law_threshold", "label": "Fourth Law threshold", "detail": "Org effective policy uses confidence review below 0.85 (resolved from hos_pol:acme:2023-10-05T14:48:00Z).", "source": "policy" } ], "related_work_refs": [ { "kind": "artifact", "id": "12345", "org_did": "acme" } ], "confidence": { "score": null, "policy_applied_id": "hos_pol:acme:2023-10-05T14:48:00Z" }, "learning": { "proposal_id": "lp-6789", "tuning_action_id": "ta-4321", "feedback_ids": [ "fb-111", "fb-222" ] } } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access this resource. Ensure your credentials include the necessary delegation." } } } } } }, "404": { "description": "The specified artifact could not be found within the organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/artifact-not-found", "title": "Artifact Not Found", "status": 404, "detail": "No artifact with ID 12345 found for organization acme. Verify the artifact ID and organization DID." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/humanos/feedback/events": { "post": { "summary": "Submit Feedback Event for HumanOS", "description": "This endpoint lets organizations send feedback events to HumanOS, enabling a collaborative environment between human efforts and AI. By doing so, it ensures that the AI is continuously learning and evolving based on real-world inputs and organizational policies.", "operationId": "submitHumanosFeedbackEvent", "tags": [ "HumanOS", "Feedback" ], "x-code-hash": "da5fa1a815ac8015", "x-generated-at": "2026-03-26T21:53:24.698Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "description": "The scope of the feedback event, defaults to 'user'." }, "payload_type": { "type": "string", "description": "The type of feedback event being submitted. Must be a known HumanOS v1 feedback event type." }, "passport_did": { "type": "string", "description": "The Passport DID associated with the feedback event." }, "target_kind": { "type": "string", "description": "The kind of target entity for the feedback." }, "target_id": { "type": "string", "description": "The identifier of the target entity." }, "payload": { "type": "object", "description": "Additional data related to the feedback event." } }, "required": [ "payload_type" ] }, "examples": { "basic_feedback_submission": { "summary": "Basic Feedback Submission", "description": "A simple example of submitting a feedback event with mandatory fields.", "value": { "scope": "team", "payload_type": "task_completion", "passport_did": "did:human:abcd1234", "target_kind": "task", "target_id": "task-5678", "payload": { "completion_time": "2023-10-01T12:00:00Z", "outcome": "success" } } } } } } }, "responses": { "201": { "description": "Feedback event successfully recorded in HumanOS.", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback_id": { "type": "string", "description": "The unique identifier of the recorded feedback event." }, "org_did": { "type": "string", "description": "The organization's DID." }, "scope": { "type": "string", "description": "The scope of the feedback event." }, "payload_type": { "type": "string", "description": "Type of the feedback event recorded." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the feedback event was created." } } }, "examples": { "default": { "summary": "Example", "value": { "feedback_id": "evt-9012", "org_did": "did:org:acme123", "scope": "team", "payload_type": "task_completion", "created_at": "2023-10-01T12:15:00Z" } } } } } }, "400": { "description": "Bad Request - Invalid input provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanos.api/errors/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized - Delegation required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanos.api/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please authenticate with a valid delegation token." } } } } } }, "403": { "description": "Forbidden - Feedback event type not allowed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanos.api/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "The payload_type 'task_completion' is not allowed by your organization's learning policy. Please review the allowed feedback event types." } } } } } }, "404": { "description": "Not Found - Resource does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanos.api/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found. Please check the target_id and try again." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanos.api/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } }, "get": { "summary": "Retrieve feedback events for an organization", "description": "Explore the trail of feedback events that have shaped the human-AI collaboration within your organization. This endpoint unravels the narrative of how feedback flows through the HUMAN ecosystem, tracking its origins and destinations.", "operationId": "getHumanOSFeedbackEvents", "tags": [ "Feedback", "HumanOS" ], "x-code-hash": "9aca19856913ad6d", "x-generated-at": "2026-03-26T21:53:45.667Z", "responses": { "200": { "description": "Successfully retrieves a list of feedback events associated with the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "feedback_id": { "type": "string" }, "org_did": { "type": "string" }, "passport_did": { "type": "string" }, "scope": { "type": "string" }, "payload_type": { "type": "string" }, "target_kind": { "type": "string" }, "target_id": { "type": "string" }, "payload": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total_count": { "type": [ "integer", "null" ] } } }, "examples": { "successful_retrieval_of_feedback_events": { "summary": "Successful retrieval of feedback events", "value": { "data": [ { "feedback_id": "12345", "org_did": "did:human:acme", "passport_did": "did:human:agent007", "scope": "task_review", "payload_type": "comment", "target_kind": "task", "target_id": "task-67890", "payload": { "comment": "Great work on the project!" }, "created_at": "2023-10-01T12:34:56Z" } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Bad Request: Invalid query parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid limit parameter", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ "Invalid value for 'limit', expected a positive integer" ] } } } } } }, "401": { "description": "Unauthorized: Missing or invalid authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_required": { "summary": "Delegation required", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please authenticate with a valid organization DID." } } } } } }, "403": { "description": "Forbidden: Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these feedback events." } } } } } }, "404": { "description": "Not Found: The specified resource does not exist", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization not found", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The organization with DID 'did:human:acme' does not exist." } } } } } }, "500": { "description": "Internal Server Error: Unexpected condition encountered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_connection_error": { "summary": "Database connection error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while connecting to the database. Please try again later." } } } } } } } } }, "/v1/humanos/artifacts/export": { "get": { "summary": "Export Artifacts with Provenance Data", "description": "Retrieve a detailed export of your organization's artifacts, complete with provenance. This endpoint empowers organizations to track the lineage and history of each artifact, ensuring transparency and accountability in task management. Ideal for auditing and operational insights.", "operationId": "exportArtifactsWithProvenance", "tags": [ "Artifacts", "Export" ], "x-code-hash": "e3ed1a25c6d16884", "x-generated-at": "2026-03-26T21:48:50.218Z", "responses": { "200": { "description": "Artifacts exported successfully, with provenance details included.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Organization's DID" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "artifact_id": { "type": "string", "description": "Unique identifier for the artifact" }, "artifact_type": { "type": "string", "description": "Type of the artifact" }, "lifecycle_state": { "type": "string", "description": "Current lifecycle state of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "provenance": { "type": "array", "items": { "type": "object", "description": "Provenance details for the artifact" } } } } }, "exported_at": { "type": "string", "format": "date-time", "description": "Export timestamp" }, "has_more": { "type": "boolean", "description": "Indicates if more artifacts are available" }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for paginating through results" } } }, "examples": { "successful_json_export": { "summary": "Successful JSON Export", "description": "A JSON export of artifacts with provenance for the organization.", "value": { "org_did": "did:human:acme-org-123", "artifacts": [ { "artifact_id": "a1b2c3", "artifact_type": "invoice", "lifecycle_state": "processed", "created_at": "2023-10-01T12:00:00Z", "provenance": [ { "step": 1, "action": "created", "timestamp": "2023-10-01T12:00:00Z", "agent": "did:human:agent-456" }, { "step": 2, "action": "verified", "timestamp": "2023-10-02T14:00:00Z", "agent": "did:human:agent-789" } ] } ], "exported_at": "2023-10-05T15:00:00Z", "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Bad request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_query_parameter": { "summary": "Invalid Query Parameter", "value": { "type": "https://humanprotocol.org/errors/invalid-query", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'format' parameter must be either 'csv' or 'json'." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://humanprotocol.org/errors/authentication", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access when the user does not have permission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to export artifacts." } } } } } }, "404": { "description": "Not Found when the organization DID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Organization Not Found", "status": 404, "detail": "The organization DID 'did:human:acme-org-123' was not found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/artifacts/:artifact_id/provenance": { "get": { "summary": "Retrieve provenance for artifact", "description": "Uncover the journey of an artifact within the HUMAN ecosystem. This endpoint allows organizations to trace the provenance of their artifacts, providing an insightful look into its history and transformations, ensuring transparency and fraud prevention.", "operationId": "getArtifactProvenance", "tags": [ "Artifacts", "Provenance", "Transparency" ], "x-code-hash": "a0ee43b79380c89c", "x-generated-at": "2026-03-26T21:49:07.932Z", "responses": { "200": { "description": "Successfully retrieved the artifact's provenance details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "sequence": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "action": { "type": "string" }, "performedBy": { "type": "string" } }, "required": [ "sequence", "timestamp", "action", "performedBy" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total_count": { "type": [ "integer", "null" ] } }, "required": [ "data", "has_more", "next_cursor", "total_count" ] }, "examples": { "successful_provenance_retrieval": { "summary": "Successful Provenance Retrieval", "description": "An example response showing the provenance of an artifact.", "value": { "data": [ { "sequence": 1, "timestamp": "2023-10-01T12:00:00Z", "action": "created", "performedBy": "did:human:abc123" }, { "sequence": 2, "timestamp": "2023-10-02T15:30:00Z", "action": "updated", "performedBy": "did:human:def456" } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "description": "An example of invalid query parameter usage.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request Parameters", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ "limit" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "An example response for missing authentication.", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Ensure your request includes valid credentials." } } } } } }, "404": { "description": "Artifact not found in the database.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "artifact_not_found": { "summary": "Artifact Not Found", "description": "An example where the artifact ID does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Artifact Not Found", "status": 404, "detail": "The specified artifact could not be found in your organization's records. Verify the artifact ID and try again." } } } } } }, "500": { "description": "Internal server error due to unforeseen circumstances.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "generic_server_error": { "summary": "Generic Server Error", "description": "An example response for server-side issues.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } }, "post": { "summary": "Record artifact provenance", "description": "As digital artifacts evolve, tracking their history is paramount. This endpoint allows organizations to chronicle the provenance of an artifact, ensuring transparency and accountability in its lifecycle. By embedding a cryptographic signature, it guarantees authenticity and trustworthiness.", "operationId": "postArtifactProvenance", "tags": [ "Artifact Management", "Provenance Tracking" ], "x-code-hash": "a685db23f9a73e0a", "x-generated-at": "2026-03-26T21:49:48.625Z", "responses": { "201": { "description": "The provenance was successfully recorded, returning the sequence number.", "content": { "application/json": {} } }, "400": { "description": "The provided request was malformed, such as invalid JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "The request lacked proper authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified artifact was not found in the organization's records.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/humanos/artifacts/:artifact_id/provenance/verify": { "get": { "summary": "Verify the provenance of an artifact", "description": "Unravel the intricate history of your digital artifacts with our provenance verification. This endpoint allows organizations to validate the integrity and authenticity of their artifacts by checking their provenance hashes, ensuring trust and transparency in the HUMAN platform.", "operationId": "verifyArtifactProvenance", "tags": [ "HumanOS", "Provenance" ], "x-code-hash": "63e57231b204cb34", "x-generated-at": "2026-03-26T21:49:31.183Z", "responses": { "200": { "description": "Successfully verified the provenance hashes for the artifact.", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact_id": { "type": "string", "description": "The unique identifier of the artifact." }, "verified": { "type": "boolean", "description": "Indicates if the integrity of the artifact's provenance hashes is verified." }, "message": { "type": "string", "description": "A human-readable message describing the verification result." } } }, "examples": { "successful_verification": { "summary": "Successful Verification", "value": { "artifact_id": "123e4567-e89b-12d3-a456-426614174000", "verified": true, "message": "Provenance verified successfully." } } } } } }, "400": { "description": "Bad request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_input": { "summary": "Malformed Input", "value": { "type": "https://api.human.com/probs/malformed-input", "title": "Invalid Request", "status": 400, "detail": "The artifact ID provided is not in a valid format. Please verify the ID and try again." } } } } } }, "401": { "description": "Authentication required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://api.human.com/probs/authentication-required", "title": "Authentication Error", "status": 401, "detail": "Delegation required. Please authenticate using a valid Passport or contact your administrator." } } } } } }, "403": { "description": "Forbidden access to the artifact's provenance details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_org_access": { "summary": "Unauthorized Org Access", "value": { "type": "https://api.human.com/probs/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have permission to verify the provenance of this artifact. Ensure your organization has the correct capabilities." } } } } } }, "404": { "description": "Artifact not found in the system.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "artifact_not_found": { "summary": "Artifact Not Found", "value": { "type": "https://api.human.com/probs/not-found", "title": "Artifact Not Found", "status": 404, "detail": "The artifact with the specified ID does not exist or you do not have access. Please check the ID and try again." } } } } } }, "500": { "description": "Internal server error during provenance verification.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://api.human.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while verifying the artifact's provenance. Please try again later or contact support." } } } } } } } } }, "/v1/humanos/artifacts/:artifact_id/revise": { "post": { "summary": "Revise existing artifact for enhancement", "description": "Revise an existing artifact to incorporate updates or corrections, ensuring the artifact evolves with your organization's needs. This endpoint facilitates the continuous improvement of your digital assets, promoting agility and precision in Human-AI orchestration.", "operationId": "reviseArtifact", "tags": [ "HumanOS", "Artifacts" ], "x-code-hash": "7d1f42b7d9fec210", "x-generated-at": "2026-03-26T21:50:11.493Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Optional new title for the artifact." }, "metadata": { "type": "object", "description": "Optional metadata specific to the artifact's kind." }, "body": { "type": "object", "description": "The content of the artifact, constrained by size." }, "media_type": { "type": "string", "description": "The media type of the artifact content." }, "summary": { "type": "string", "description": "A brief summary of the changes made during the revision." } } }, "examples": { "revise_invoice_processing_artifact": { "summary": "Revise Invoice Processing Artifact", "description": "An example of revising an artifact related to invoice processing in the 'acme' organization.", "value": { "title": "Updated Invoice Processing", "metadata": { "version": "2.0", "description": "Enhanced invoice processing logic." }, "body": { "steps": [ "Verify invoice integrity", "Apply tax calculations", "Generate payment instructions" ] }, "media_type": "application/json", "summary": "Improved step-by-step guide for invoice processing." } } } } } }, "responses": { "201": { "description": "Artifact successfully revised and stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact_id": { "type": "string", "description": "The unique identifier of the revised artifact." }, "revision": { "type": "integer", "description": "The revision number of the artifact." }, "title": { "type": "string", "description": "The title of the revised artifact." }, "metadata": { "type": "object", "description": "The metadata of the revised artifact." }, "body": { "type": "object", "description": "The new content of the revised artifact." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to incorrect JSON structure or payload size.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/payload-too-large", "title": "Payload Too Large", "status": 400, "detail": "body exceeds max size of 5242880 bytes", "errors": [ { "field": "body", "code": "PAYLOAD_TOO_LARGE", "message": "body exceeds max size of 5242880 bytes" } ] } } } } } }, "401": { "description": "Authentication required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to perform this action." } } } } } }, "403": { "description": "Permission denied for revising the specified artifact.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to revise this artifact." } } } } } }, "404": { "description": "The specified artifact could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/not-found", "title": "Artifact Not Found", "status": 404, "detail": "The artifact with the specified ID does not exist." } } } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/orgs/:org_did/cp-extensions": { "get": { "summary": "Retrieve organization's CP extensions", "description": "Explore the vibrant ecosystem of Control Panel extensions tailored for your organization. This endpoint empowers admins by offering a detailed list of extensions, showcasing each tool's capabilities and potential to enhance your organization's operational efficiency.", "operationId": "getCpExtensions", "tags": [ "Organizations", "ControlPanel" ], "x-code-hash": "91287df9fc9c5be8", "x-generated-at": "2026-03-27T15:34:11.101Z", "responses": { "200": { "description": "Successfully retrieved list of CP extensions for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier of the organization" }, "extensions": { "type": "array", "items": { "type": "object", "properties": { "cp_extension_id": { "type": "string", "description": "Extension identifier" }, "installation_id": { "type": "string", "description": "Installation identifier" }, "asset_id": { "type": "string", "description": "Asset identifier" }, "source_kind": { "type": "string", "description": "Source type of the extension" }, "sections": { "type": "array", "items": { "type": "string" } }, "alerts": { "type": "array", "items": { "type": "string" } }, "rendering_modes": { "type": "array", "items": { "type": "string" } }, "capabilities": { "$ref": "#/components/schemas/CpExtensionCapabilitiesSnapshot" }, "asset_name": { "type": "string", "description": "Name of the asset" }, "asset_type": { "type": "string", "description": "Type of the asset" }, "trust_tier": { "type": "string", "description": "Trust tier of the asset" } } } } } }, "examples": { "successfully_retrieved_extensions": { "summary": "Successfully retrieved extensions", "value": { "org_did": "did:example:123456789", "extensions": [ { "cp_extension_id": "ext-001", "installation_id": "inst-123", "asset_id": "asset-456", "source_kind": "plugin", "sections": [ "dashboard", "reporting" ], "alerts": [ "low-battery", "overload" ], "rendering_modes": [ "dark", "light" ], "capabilities": [ "capability://analyze", "capability://report" ], "asset_name": "Advanced Analytics", "asset_type": "Software", "trust_tier": "high" } ] } } } } } }, "400": { "description": "Bad Request - Invalid parameters provided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid parameters", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters are incorrect. Ensure the 'org_did' is valid." } } } } } }, "401": { "description": "Unauthorized - Delegation required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden - Delegation org mismatch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "org_mismatch": { "summary": "Org mismatch", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Delegation org does not match the requested organization. Access denied." } } } } } }, "404": { "description": "Not Found - Organization not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization not found", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified organization does not exist. Verify the 'org_did' and try again." } } } } } }, "500": { "description": "Internal Server Error - Unexpected error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/agents/:agentId/artifacts": { "get": { "summary": "Retrieve Agent Artifacts with Provenance", "description": "Uncover the wealth of artifacts associated with a specific agent within an organization, tracing the lineage and evolution of each piece. This endpoint helps ensure transparency and trust in AI-driven tasks by presenting a detailed history of artifact creation and modification.", "operationId": "getAgentArtifacts", "tags": [ "Artifacts", "Agents" ], "x-code-hash": "c2bb5fc403fd2e01", "x-generated-at": "2026-03-26T22:19:46.370Z", "responses": { "200": { "description": "Successfully retrieved artifacts associated with the given agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "org_did": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "artifact_id": { "type": "string" }, "org_did": { "type": "string" }, "artifact_type": { "type": "string" }, "schema_ref": { "type": "string" }, "owner_ref": { "type": "string" }, "lifecycle_state": { "type": "string" }, "revision": { "type": "integer" }, "capture_id": { "type": "string" }, "metadata": { "type": "object" }, "production": { "type": "boolean" }, "title": { "type": "string" }, "media_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "artifact_id", "org_did", "artifact_type", "created_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total_count": { "type": [ "integer", "null" ] } }, "required": [ "agent_id", "org_did", "data", "has_more" ] }, "examples": { "successful_retrieval_of_artifacts": { "summary": "Successful retrieval of artifacts", "value": { "agent_id": "agent-1234", "org_did": "did:human:acme", "data": [ { "artifact_id": "artifact-5678", "org_did": "did:human:acme", "artifact_type": "document", "schema_ref": "schema-001", "owner_ref": "owner-9876", "lifecycle_state": "active", "revision": 3, "capture_id": "capture-2345", "metadata": { "key": "value" }, "production": true, "title": "Quarterly Report", "media_type": "application/pdf", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T12:00:00Z" } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Bad request due to invalid parameters or state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_state_error": { "summary": "Invalid State Error", "value": { "type": "/errors/invalid-state", "title": "Invalid State", "status": 400, "detail": "Agent has no org_id. Expected an org-scoped agent.", "errors": [ { "field": "agent", "code": "INVALID_STATE", "message": "Agent has no org_id", "expected": "org-scoped agent", "received": "agent-1234" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication Error", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing or invalid authentication token. Ensure your request includes a valid bearer token." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these artifacts. Verify your roles and permissions within the organization." } } } } } }, "404": { "description": "Agent not found within the organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Agent with ID 'agent-5678' was not found. Ensure the agent ID is correct and the agent exists in the organization." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/agents/:agentId/metrics": { "get": { "summary": "Retrieve daily agent performance metrics", "description": "Dive into the world of agent performance with this endpoint, which reveals the intricate dance of invocations, tokens, and operation durations over time. It's not just data — it's the heartbeat of your AI agents, empowering you to optimize and understand their daily rhythm.", "operationId": "getAgentMetrics", "tags": [ "Agent", "Metrics" ], "x-code-hash": "55bdff402ab00cc6", "x-generated-at": "2026-03-27T19:47:49.224Z", "responses": { "200": { "description": "Successful retrieval of agent metrics, detailing daily performance data for specified metric and time window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Unique identifier for the agent." }, "metric": { "type": "string", "enum": [ "invocations", "tokens", "duration_ms" ], "description": "The metric being tracked." }, "window_days": { "type": "integer", "description": "Number of days in the time window requested." }, "series": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "string", "format": "date-time", "description": "The start of the UTC day bucket." }, "v": { "type": "number", "description": "The metric value for the day." } } } }, "placeholder": { "type": "boolean", "description": "Indicates if the response is a placeholder." } } }, "examples": { "successful_metrics_retrieval": { "summary": "Successful Metrics Retrieval", "description": "Example of retrieving invocation metrics for an agent over a default window of 30 days.", "value": { "agent_id": "123e4567-e89b-12d3-a456-426614174000", "metric": "invocations", "window_days": 30, "series": [ { "t": "2023-10-01T00:00:00Z", "v": 12 }, { "t": "2023-10-02T00:00:00Z", "v": 15 }, { "t": "2023-10-03T00:00:00Z", "v": 8 } ], "placeholder": false } } } } } }, "400": { "description": "Invalid request due to malformed parameters or logic errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_window_days_parameter": { "summary": "Invalid window_days parameter", "value": { "type": "https://humanapi.io/problems/invalid-parameter", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'window_days' parameter must be between 1 and 90.", "errors": [ { "field": "window_days", "message": "Must be a number between 1 and 90." } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://humanapi.io/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access this endpoint. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://humanapi.io/problems/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have permission to view these metrics. Contact your administrator to request access." } } } } } }, "404": { "description": "Agent not found for the provided agentId.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "value": { "type": "https://humanapi.io/problems/not-found", "title": "Agent Not Found", "status": 404, "detail": "No agent found with the provided agentId. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error encountered during processing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanapi.io/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support." } } } } } } } } }, "/v1/agents/:agentId/policy/effective": { "get": { "summary": "Retrieve Effective Agent Policy", "description": "Unlock the power of HumanOS by accessing the effective policy for a specified agent. This endpoint helps organizations monitor and enforce skill progress gates, ensuring every agent adheres to the orchestrated protocol.", "operationId": "getAgentEffectivePolicy", "tags": [ "HumanOS", "AgentManagement" ], "x-code-hash": "afe87844903a4c8a", "x-generated-at": "2026-03-26T22:20:21.722Z", "responses": { "200": { "description": "Effectively retrieves the organization's policy envelope for the agent's progress gates, providing insight into skill tracking and compliance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "The unique identifier for the agent." }, "org_did": { "type": "string", "description": "The decentralized identifier for the organization the agent belongs to." }, "policy_json": { "type": "object", "description": "The JSON representation of the organization's policy applicable to the agent." } }, "required": [ "agent_id", "org_did", "policy_json" ] }, "examples": { "default": { "summary": "Example", "value": { "agent_id": "agent123", "org_did": "did:human:org:acme", "policy_json": { "progress_gates": [ "training_completed", "certification_passed" ] } } } } } } }, "400": { "description": "The request could not be understood by the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Agent ID format is incorrect.", "errors": [ { "field": "agentId", "message": "Agent ID must be alphanumeric." } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The specified agent could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/not-found", "title": "Not Found", "status": 404, "detail": "Agent not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/agents/deploy": { "post": { "summary": "Deploy an agent with identity minting", "description": "Embark on the journey of deploying an agent where identity and capability converge. This endpoint mints a Passport for your agent, anchoring its identity in the distributed ledger and equipping it with the skills needed for its mission. It's not just deployment; it's the birth of a digital entity.", "operationId": "deployAgent", "tags": [ "Agents", "Deployment" ], "x-code-hash": "5d10e276d9a44df1", "x-generated-at": "2026-04-02T20:12:15.167Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "manifest": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "org_id": { "type": "string" }, "org_slug": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "capability": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "confidence": { "type": "number" } }, "required": [ "description", "confidence" ] } }, "confidence": { "type": "number" } }, "required": [ "capability" ] } }, "handler": { "type": "object", "properties": { "type": { "type": "string" }, "module": { "type": "string" }, "image": { "type": "string" }, "endpoint": { "type": "string" } }, "required": [ "type" ] }, "description": { "type": "string" }, "config": { "type": "object" }, "environment": { "type": "object" }, "limits": { "type": "object", "properties": { "max_execution_time_ms": { "type": "integer" }, "max_memory_mb": { "type": "integer" }, "max_cost_per_run": { "type": "number" } } }, "tags": { "type": "array", "items": { "type": "string" } }, "template_id": { "type": "string" } }, "required": [ "name", "version", "org_id", "capabilities", "handler" ] }, "profile": { "type": "string", "default": "hosted" } }, "required": [ "manifest" ] }, "examples": { "deploy_a_new_agent": { "summary": "Deploy a new agent", "description": "Deploys an agent named 'invoice-processor' for the 'acme' organization with AI capabilities.", "value": { "manifest": { "name": "invoice-processor", "version": "1.0.0", "org_id": "did:org:acme", "org_slug": "acme", "capabilities": [ { "capability": "process_invoices", "evidence": [ { "description": "Validated by QA team", "confidence": 0.9 } ] } ], "handler": { "type": "docker", "image": "acme/invoice-processor:1.0.0" }, "description": "An agent dedicated to processing invoices efficiently.", "tags": [ "finance", "automation" ] } } } } } } }, "responses": { "201": { "description": "Agent successfully deployed with a minted Passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" }, "passport_id": { "type": "string" }, "org_id": { "type": "string" }, "org_agent_id": { "type": "string" }, "org_slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "uri": { "type": "string" }, "handler": { "type": "object", "properties": { "type": { "type": "string" }, "module": { "type": "string" }, "image": { "type": "string" }, "endpoint": { "type": "string" } } }, "deployed_at": { "type": "string", "format": "date-time" }, "deployed_by": { "type": "string" }, "template_id": { "type": "string" }, "identity": { "type": "object", "properties": { "org": { "type": "object", "properties": { "did": { "type": "string" }, "slug": { "type": "string" } } }, "agent": { "type": "object", "properties": { "did": { "type": "string" }, "uri": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "authority": { "type": "object", "properties": { "delegated_by": { "type": "string" }, "principal": { "type": "string" }, "delegation_id": { "type": "string" } } }, "template": { "type": "object", "properties": { "id": { "type": "string" } } } } }, "endpoints": { "type": "object", "properties": { "invoke": { "type": "string" }, "dashboard": { "type": "string" } } }, "provenance": { "type": "object", "properties": { "deployment_id": { "type": "string" }, "attestation_id": { "type": "string" }, "ledger_url": { "type": "string" } } } } }, "examples": { "invoice-processor": { "summary": "invoice-processor" } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.sh/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request payload is missing required fields.", "errors": [ { "field": "manifest.name", "code": "MISSING_FIELD", "message": "Agent name is required." } ] } } } } } }, "401": { "description": "Authentication is required to deploy an agent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.sh/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to deploy an agent." } } } } } }, "403": { "description": "Permission denied to deploy an agent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.sh/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to deploy agents for this organization." } } } } } }, "404": { "description": "Resource not found or unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.sh/problems/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The specified organization or agent does not exist." } } } } } }, "500": { "description": "Internal server error during agent deployment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.sh/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during agent deployment. Please try again later." } } } } } } } } }, "/v1/agents/:agentId": { "get": { "summary": "Retrieve detailed agent information by ID", "description": "Unlock the power of your HUMAN agents by retrieving detailed information using their unique identifiers. Whether you're exploring agents by their cryptographic DIDs or their organizational identifiers, this endpoint provides a comprehensive view of an agent's identity, capabilities, and operational context.", "operationId": "getAgentById", "tags": [ "Agents", "Identity" ], "x-code-hash": "b5471283d33b31f6", "x-generated-at": "2026-03-26T22:21:50.559Z", "responses": { "200": { "description": "Successfully retrieved the agent's detailed information.", "content": { "application/json": {} } }, "400": { "description": "Invalid request format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Agent not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/agents/:agentId/pause": { "post": { "summary": "Pause an agent's task acceptance", "description": "In the dynamic world of Human-AI orchestration, sometimes an agent needs a breather. This endpoint halts an agent's ability to accept new tasks, ensuring that our orchestration remains finely tuned and agile. Whether it's for routine maintenance or strategic planning, pausing gives you control over the flow of operations.", "operationId": "pauseAgent", "tags": [ "Agent Management", "Operations" ], "x-code-hash": "aa5921f01f6ad2aa", "x-generated-at": "2026-03-26T22:22:31.285Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional explanation for pausing the agent" } }, "required": [], "additionalProperties": false }, "examples": { "routine_maintenance": { "summary": "Routine Maintenance", "description": "Pausing the agent for routine system maintenance", "value": { "reason": "Scheduled maintenance" } } } } } }, "responses": { "200": { "description": "The agent was successfully paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier of the agent" }, "status": { "type": "string", "description": "The current status of the agent" }, "paused_at": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was paused" }, "paused_by": { "type": "string", "description": "Identifier of the entity that paused the agent" }, "reason": { "type": "string", "description": "Reason provided for pausing the agent" } }, "required": [ "did", "status", "paused_at", "paused_by" ] } } }, "examples": { "successful_pause": { "summary": "Successful Pause", "value": { "agent": { "did": "did:example:123456789", "status": "paused", "paused_at": "2023-10-10T10:00:00Z", "paused_by": "did:example:org:acme", "reason": "Scheduled maintenance" } } } } } } }, "400": { "description": "Invalid request format or missing parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_agent_id": { "summary": "Missing Agent ID", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The agent ID must be provided.", "errors": [ "agentId is required" ] } } } } } }, "401": { "description": "Authentication required to pause the agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to pause an agent." } } } } } }, "403": { "description": "Permission denied to pause the agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to pause this agent." } } } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The agent with ID did:example:123456789 was not found." } } } } } }, "409": { "description": "Conflict with current agent status", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_already_paused": { "summary": "Agent Already Paused", "value": { "type": "https://humanprotocol.org/errors/conflict", "title": "Conflict", "status": 409, "detail": "The agent is already in a paused state." } }, "agent_retired": { "summary": "Agent Retired", "value": { "type": "https://humanprotocol.org/errors/conflict", "title": "Conflict", "status": 409, "detail": "Cannot pause a retired agent." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request. Please try again later." } } } } } } } } }, "/v1/agents/:agentId/resume": { "post": { "summary": "Resume a paused agent's operations", "description": "In the dynamic world of Human-AI collaboration, agents sometimes need to pause. This endpoint breathes life back into a paused agent, restoring its active status and enabling it to perform its designated tasks. It's a critical function for maintaining seamless operations and ensuring that your digital workforce is always at the ready.", "operationId": "resumeAgent_1", "tags": [ "Agents", "Operations" ], "x-code-hash": "f34fb05eafeb285b", "x-generated-at": "2026-03-26T22:22:50.266Z", "responses": { "200": { "description": "Agent successfully resumed.", "content": { "application/json": {} } }, "400": { "description": "Invalid request due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication required to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Permission denied to resume the agent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Agent not found with the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error when attempting to resume the agent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/agents/:agentId/retire": { "post": { "summary": "Permanently retire a specified agent", "description": "In the dynamic world of human and AI collaboration, sometimes an agent's journey must conclude. This endpoint allows you to retire an agent, ensuring that it can no longer participate in the orchestration process. By doing so, organizations maintain a clean and up-to-date roster of active agents, preserving the integrity and reliability of the HUMAN platform.", "operationId": "retireAgent", "tags": [ "Agents", "Lifecycle Management" ], "x-code-hash": "a4e38bb5f710faa9", "x-generated-at": "2026-03-26T22:23:11.276Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional explanation for retiring the agent." } }, "required": [], "example": { "reason": "Agent no longer needed in project" } }, "examples": { "retirement_with_reason": { "summary": "Retirement with Reason", "description": "Retiring an agent with a specific reason provided.", "value": { "reason": "Project completed, agent services no longer required" } } } } } }, "responses": { "200": { "description": "The agent has been successfully retired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier of the retired agent." }, "status": { "type": "string", "enum": [ "retired" ], "description": "The new status of the agent." }, "retired_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the agent was retired." }, "retired_by": { "type": "string", "description": "Identifier of the entity that retired the agent." }, "reason": { "type": "string", "description": "Reason provided for the agent's retirement." } } } } }, "examples": { "successful_retirement": { "summary": "Successful Retirement", "description": "Example response after successfully retiring an agent.", "value": { "agent": { "did": "did:example:123456", "status": "retired", "retired_at": "2023-10-01T12:00:00Z", "retired_by": "passport:acme:admin", "reason": "Project completed, agent services no longer required" } } } } } } }, "400": { "description": "Invalid request format or data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_reason": { "summary": "Missing Reason", "description": "Example of a request with missing or invalid data.", "value": { "type": "https://example.com/probs/invalid-data", "title": "Invalid request data", "status": 400, "detail": "The request body is malformed or contains invalid data.", "errors": [ "reason must be a string" ] } } } } } }, "401": { "description": "Authentication required to perform this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Access attempt without proper authentication.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication required", "status": 401, "detail": "You must authenticate yourself to perform this operation." } } } } } }, "403": { "description": "Permission denied for retiring the agent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_operation": { "summary": "Forbidden Operation", "description": "Attempt to retire an agent without sufficient permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Permission denied", "status": 403, "detail": "You do not have permission to retire this agent." } } } } } }, "404": { "description": "Agent not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "description": "The specified agent ID does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Agent not found", "status": 404, "detail": "No agent found with the specified ID." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A generic error on the server side.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/agents/:agentId/executions": { "get": { "summary": "Retrieve agent execution history", "description": "Delve into the rich tapestry of an agent's past activities by retrieving its execution history. This endpoint allows you to explore how agents have been invoked, their performance over time, and any associated costs or errors, providing transparency and accountability.", "operationId": "getAgentExecutions", "tags": [ "Agents", "Execution History" ], "x-code-hash": "3b37b95b891b5fba", "x-generated-at": "2026-03-26T22:23:25.967Z", "responses": { "200": { "description": "Successfully retrieved the agent's execution history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "execution_id": { "type": "string" }, "trace_id": { "type": "string" }, "invoked_by": { "type": "string" }, "delegation_id": { "type": "string" }, "invoked_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": "integer" }, "cost_usd": { "type": "number" }, "status": { "type": "string" }, "provenance_id": { "type": "string" }, "error": { "type": "string" } } } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" } } }, "examples": { "successful_retrieval_of_executions": { "summary": "Successful retrieval of executions", "description": "A list of past executions for agent 'acme:invoice-processor'.", "value": { "data": [ { "execution_id": "exec_001", "trace_id": "trace_abc123", "invoked_by": "user:john_doe", "delegation_id": "del_456", "invoked_at": "2023-10-01T15:23:00Z", "finished_at": "2023-10-01T15:24:00Z", "duration_ms": 60000, "cost_usd": 0.05, "status": "completed", "provenance_id": "prov_001", "error": null } ], "limit": 10, "cursorField": "execution_id" } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination_parameters": { "summary": "Invalid pagination parameters", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid request parameters", "status": 400, "detail": "The 'limit' query parameter must be a positive integer.", "errors": [ "Invalid 'limit' value" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization_token": { "summary": "Missing authorization token", "value": { "type": "https://example.com/probs/authentication-required", "title": "Unauthorized", "status": 401, "detail": "An authorization token is required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this agent's execution history." } } } } } }, "404": { "description": "The specified agent could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent not found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No agent found with ID 'acme:nonexistent-agent'." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/agents/:agentId/costs": { "get": { "summary": "Retrieve agent cost breakdown", "description": "Explore the detailed cost analysis of an agent over a specified period. This endpoint unveils the financial footprint of AI interactions, empowering organizations to optimize resource allocation and manage budgets effectively.", "operationId": "getAgentCosts", "tags": [ "Financial", "Analytics" ], "x-code-hash": "b783f3f89d359e6d", "x-generated-at": "2026-03-26T22:23:48.055Z", "responses": { "200": { "description": "Successfully retrieved the cost breakdown for the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_cost_usd": { "type": "number", "description": "Total cost in USD over the specified period." }, "period": { "type": "string", "description": "The period for which costs are calculated, formatted as \\d+[dh]." }, "by_day": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Specific date within the period." }, "cost_usd": { "type": "number", "description": "Cost incurred on the specific date in USD." } } } }, "top_executions": { "type": "array", "items": { "type": "object", "properties": { "execution_id": { "type": "string", "description": "Unique identifier for the execution." }, "cost_usd": { "type": "number", "description": "Cost of this particular execution in USD." }, "invoked_at": { "type": "string", "format": "date-time", "description": "Timestamp when this execution was invoked." } } } } } }, "examples": { "acmeagentcostexample": { "summary": "acmeAgentCostExample", "description": "Cost breakdown example for Acme's AI Agent over a 7-day period.", "value": { "total_cost_usd": 349.5, "period": "7d", "by_day": [ { "date": "2023-10-12", "cost_usd": 50 }, { "date": "2023-10-11", "cost_usd": 45 } ], "top_executions": [ { "execution_id": "exec12345", "cost_usd": 20, "invoked_at": "2023-10-12T08:30:00Z" } ] } } } } } }, "400": { "description": "Invalid request due to malformed query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "periodformaterror": { "summary": "periodFormatError", "description": "Example of a period format error response.", "value": { "type": "https://humanprotocol.org/errors/invalid-period-format", "title": "Invalid period format", "status": 400, "detail": "The 'period' query parameter must be in the format: '7d', '30d', etc.", "errors": [ { "field": "period", "code": "INVALID_FORMAT", "message": "Period must be in format: 7d, 30d, etc.", "expected": "e.g., '7d', '30d', '90d'", "received": "weekly" } ] } } } } } }, "401": { "description": "Unauthorized access attempt due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorizedaccessexample": { "summary": "unauthorizedAccessExample", "description": "Example response for unauthorized access.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbiddenaccessexample": { "summary": "forbiddenAccessExample", "description": "Example response for a forbidden request.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found for the specified agent ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agentnotfoundexample": { "summary": "agentNotFoundExample", "description": "Response when the specified agent ID does not exist.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Agent with ID 'acme:agent1234' was not found." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internalservererrorexample": { "summary": "internalServerErrorExample", "description": "Example response for an unexpected server error.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/agents/:agentId/versions": { "get": { "summary": "Retrieve all deployed agent versions", "description": "Explore the evolution of your AI agents with this endpoint, which lists all the deployed versions. This helps organizations track changes over time, ensuring the right skills are deployed at the right moments, ultimately enhancing AI strategy and effectiveness.", "operationId": "getAgentVersions", "tags": [ "Agents", "Versions" ], "x-code-hash": "d526afa3ecc9ae53", "x-generated-at": "2026-03-26T22:24:05.415Z", "responses": { "200": { "description": "A list of deployed versions for the specified agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string", "example": "v1.3.0" }, "deployed_at": { "type": "string", "format": "date-time", "example": "2023-10-12T14:20:00Z" }, "deployed_by": { "type": "string", "example": "john.doe@example.com" }, "status": { "type": "string", "example": "active" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 10 }, "cursor": { "type": "string", "example": "v1.2.0" } } } } }, "examples": { "agent_versions_response": { "summary": "Agent Versions Response", "description": "List of versions for the agent 'acme:123'.", "value": { "data": [ { "version": "v1.3.0", "deployed_at": "2023-10-12T14:20:00Z", "deployed_by": "john.doe@example.com", "status": "active" }, { "version": "v1.2.0", "deployed_at": "2023-09-15T09:00:00Z", "deployed_by": "jane.smith@example.com", "status": "inactive" } ], "pagination": { "limit": 10, "cursor": "v1.2.0" } } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters_example": { "summary": "Invalid Parameters Example", "description": "Occurs when a non-integer 'limit' is provided.", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Parameters", "status": 400, "detail": "The provided 'limit' value is not valid." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "Triggered when no authentication token is provided.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this endpoint." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Occurs when the user lacks the necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these agent versions." } } } } } }, "404": { "description": "Agent not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found_example": { "summary": "Agent Not Found Example", "description": "Occurs when the agent ID does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified agent could not be found." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "General error response indicating an issue on the server.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/agents/:agentId/rollback": { "post": { "summary": "Rollback an Agent to Previous Version", "description": "This endpoint allows you to roll back an agent to a previous version, providing a safety net for deployments. However, as of now, it's a blueprint for future capabilities, reminding us that the past isn't just a place—it’s a stepping stone.", "operationId": "rollbackAgent", "tags": [ "Agent Management", "Version Control" ], "x-code-hash": "088053e0062b12b7", "x-generated-at": "2026-03-26T22:24:21.963Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_version": { "type": "string", "description": "The version to which the agent should be rolled back, e.g., '1.2.2'." }, "reason": { "type": "string", "description": "Optional reason for the rollback, providing context for future reference." } }, "required": [ "target_version" ] }, "examples": { "rollback_to_version_1.2.2": { "summary": "Rollback to version 1.2.2", "description": "This example demonstrates rolling back an agent to version 1.2.2 due to a critical bug discovered in the current version.", "value": { "target_version": "1.2.2", "reason": "Critical bug in current version" } } } } } }, "responses": { "400": { "description": "Validation error due to missing or invalid fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified agent was not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "501": { "description": "Rollback functionality is not yet implemented", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/agents/:agentId/logs": { "get": { "summary": "Stream real-time logs for agents", "description": "Dive into the pulsating life of an agent with real-time log streaming. Though this feature is a placeholder for now, it promises to reveal the intricate dance of actions and reactions in your AI operations once fully implemented. Keep your eyes peeled for Phase 6e when this becomes a reality.", "operationId": "getAgentLogs", "tags": [ "Agents", "Logs" ], "x-code-hash": "193dd0a6710347da", "x-generated-at": "2026-03-26T22:24:36.585Z", "responses": { "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found_example": { "summary": "Agent not found example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Agent Not Found", "status": 404, "detail": "No agent found with DID or org_agent_id matching 'agent123'. Verify the agent ID and try again." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal server error example", "value": { "type": "https://api.haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while attempting to access the agent logs. Please try again later." } } } } } }, "501": { "description": "Feature not implemented yet", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "log_streaming_not_implemented": { "summary": "Log streaming not implemented", "value": { "type": "https://api.haio.run/errors/not-implemented", "title": "Log Streaming Not Yet Implemented", "status": 501, "detail": "Real-time log streaming is planned for Phase 6e", "remediation": [ { "step": 1, "description": "For MVP, use GET /v1/agents/:id/executions to see execution history" }, { "step": 2, "description": "Check individual execution errors in the execution detail endpoint" }, { "step": 3, "description": "Full log aggregation and streaming will be available in Phase 6e" } ] } } } } } } } } }, "/v1/orgs/:org_did/companion-modules": { "get": { "summary": "Retrieve organization's active companion modules", "description": "Unveil the ensemble of companion modules that your organization actively leverages to enhance its capabilities. This endpoint empowers you with insights into each module's specifics, facilitating strategic orchestration and informed decision-making.", "operationId": "getCompanionModules", "tags": [ "Organizations", "Companion Modules" ], "x-code-hash": "6d82fdb07818a53d", "x-generated-at": "2026-03-27T15:34:27.551Z", "responses": { "200": { "description": "Successfully retrieved active companion modules for the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier of the organization" }, "companion_modules": { "type": "array", "items": { "type": "object", "properties": { "companion_module_id": { "type": "string", "description": "Unique identifier for the companion module" }, "installation_id": { "type": "string", "description": "ID of the module's installation" }, "asset_id": { "type": "string", "description": "Associated asset's unique identifier" }, "modes": { "type": "array", "items": { "type": "string" }, "description": "Modes supported by the module" }, "panels": { "type": "array", "items": { "type": "string" }, "description": "UI panels available in the module" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Tools provided by the module" }, "quick_actions": { "type": "array", "items": { "type": "string" }, "description": "Quick actions that the module facilitates" }, "asset_name": { "type": "string", "description": "Name of the companion module's asset" }, "asset_type": { "type": "string", "description": "Type of asset associated with the module" }, "trust_tier": { "type": "string", "description": "Trust tier of the asset" } }, "required": [ "companion_module_id", "installation_id", "asset_id" ] } } }, "required": [ "org_did", "companion_modules" ] }, "examples": { "acme_corp's_active_modules": { "summary": "Acme Corp's Active Modules", "description": "An example response showing Acme Corp's active companion modules.", "value": { "org_did": "did:human:acme", "companion_modules": [ { "companion_module_id": "mod-12345", "installation_id": "inst-54321", "asset_id": "asset-67890", "modes": [ "interactive", "batch" ], "panels": [ "dashboard", "control" ], "tools": [ "analyzer", "reporter" ], "quick_actions": [ "refresh", "optimize" ], "asset_name": "Acme Analyzer", "asset_type": "analytics", "trust_tier": "high" } ] } } } } } }, "400": { "description": "Invalid request due to malformed input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_did": { "summary": "Malformed DID", "description": "The provided org_did is not properly formatted.", "value": { "type": "https://humanprotocol.org/error/invalid-input", "title": "Invalid input", "status": 400, "detail": "The 'org_did' parameter must be a valid Decentralized Identifier." } } } } } }, "401": { "description": "Authentication required due to missing delegation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "The request lacks the required delegation for authentication.", "value": { "type": "https://humanprotocol.org/error/authentication", "title": "Authentication Error", "status": 401, "detail": "Delegation required for accessing this resource. Ensure your request includes valid authorization headers." } } } } } }, "403": { "description": "Authorization failed due to mismatched delegation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "mismatched_delegation": { "summary": "Mismatched Delegation", "description": "The delegation's organization does not match the requested organization.", "value": { "type": "https://humanprotocol.org/error/authorization", "title": "Authorization Error", "status": 403, "detail": "Delegation org does not match requested organization. Verify your delegation is correctly aligned with the intended organization." } } } } } }, "404": { "description": "Organization not found due to invalid DID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "The specified organization does not exist in the system.", "value": { "type": "https://humanprotocol.org/error/not-found", "title": "Not Found", "status": 404, "detail": "Organization not found. Ensure the 'org_did' is correct and references an existing organization." } } } } } }, "500": { "description": "Internal server error during companion module retrieval", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://humanprotocol.org/error/internal-server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/orgs/:org_did/workforce/routing-config": { "get": { "summary": "Retrieve Organization Workforce Routing Config", "description": "Explore the intricate orchestration of human and AI collaboration within an organization. This endpoint unveils the current routing configuration, vital for ensuring tasks are allocated efficiently and safely. It's your window into the dynamic core of HumanOS task routing.", "operationId": "getOrgWorkforceRoutingConfig", "tags": [ "Organization", "HumanOS" ], "x-code-hash": "1715f651301993e5", "x-generated-at": "2026-03-27T15:34:46.170Z", "responses": { "200": { "description": "Successfully retrieved the organization's workforce routing configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The decentralized identifier of the organization." }, "config": { "type": "object", "description": "The JSON object containing the routing configuration details." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the configuration was last updated." } } }, "examples": { "successful_retrieval_example": { "summary": "Successful Retrieval Example", "description": "Example of a successful retrieval of routing configuration for an organization.", "value": { "org_did": "did:human:acme", "config": { "taskPriority": "high", "aiAssistanceLevel": "moderate" }, "updated_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Bad request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_organization_did": { "summary": "Invalid Organization DID", "description": "The provided organization DID is malformed.", "value": { "type": "/errors/invalid-input", "title": "Invalid Input", "status": 400, "detail": "The organization DID provided is not in a valid format. Ensure the DID follows the 'did:human:orgname' pattern." } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "Request lacks necessary delegation headers.", "value": { "type": "/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please include a valid delegation token in your request headers." } } } } } }, "403": { "description": "Forbidden due to delegation token mismatch with requested organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_org_mismatch": { "summary": "Delegation Org Mismatch", "description": "The delegation token's organization does not match the requested organization.", "value": { "type": "/errors/authorization-failed", "title": "Authorization Failed", "status": 403, "detail": "Delegation org does not match requested organization. Verify the delegation token matches the organization DID." } } } } } }, "404": { "description": "Not Found when the organization DID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "The organization with the specified DID does not exist.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Organization not found. Please ensure the organization DID is correct and exists in the system." } } } } } }, "500": { "description": "Internal Server Error due to unexpected circumstances.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "An unexpected error occurred on the server.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } }, "put": { "summary": "Update workforce routing configuration", "description": "Fine-tune your organization's task routing by configuring workforce settings. This endpoint ensures that tasks are directed efficiently to human and AI agents using up-to-date configurations, providing a seamless orchestration experience.", "operationId": "updateWorkforceRoutingConfig", "tags": [ "Workforce", "Configuration" ], "x-code-hash": "5637420243f9294c", "x-generated-at": "2026-03-27T15:35:08.698Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": true, "description": "Dynamic routing configuration settings" } }, "required": [ "config" ] }, "examples": { "acme_invoice_processing_configuration": { "summary": "Acme Invoice Processing Configuration", "description": "Configure routing for Acme's invoice processing tasks to ensure tasks are managed efficiently across teams.", "value": { "config": { "priority": "high", "agents": [ "agent:jane.doe", "agent:john.smith" ], "constraints": { "location": "remote", "expertise": "finance" } } } } } } } }, "responses": { "200": { "description": "The routing configuration was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The DID of the organization" }, "config": { "type": "object", "description": "The updated routing configuration" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last update" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Forbidden because the delegation token's organization does not match the requested organization's DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Delegation org does not match requested organization" } } } } } }, "404": { "description": "The organization specified by the DID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Organization not found" } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/workforce/work-items": { "get": { "summary": "Retrieve work items for an organization", "description": "Dive into the heart of your organization's operations by exploring a curated list of work items. This endpoint empowers you to filter tasks based on status, urgency, and routing, ensuring you're always on top of what matters most. It's designed to help you manage tasks with precision, ensuring that nothing slips through the cracks.", "operationId": "getWorkItems", "tags": [ "Workforce", "Task Management" ], "x-code-hash": "dc59e1c3af9a45a0", "x-generated-at": "2026-03-28T16:56:50.089Z", "responses": { "200": { "description": "A successful response returns a paginated list of work items for the specified organization, filtered by the provided criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "org_did": { "type": "string" }, "installation_id": { "type": "string" }, "renderer_id": { "type": "string" }, "artifact_id": { "type": "string" }, "status": { "type": "string" }, "routed_to_type": { "type": "string" }, "routed_to_id": { "type": "string" }, "routed_by": { "type": "string" }, "urgency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "actions_taken": { "type": "array", "items": { "type": "string" } }, "feedback_emitted": { "type": "boolean" } } } }, "next_cursor": { "type": "string" } } }, "examples": { "pagination_with_work_items": { "summary": "Pagination with work items", "description": "A response showing a paginated list of work items, with filtering applied.", "value": { "data": [ { "id": "wi12345", "org_did": "did:example:acme", "installation_id": "inst123", "renderer_id": "rend456", "artifact_id": "art789", "status": "completed", "routed_to_type": "personal", "routed_to_id": "did:example:john_doe", "routed_by": "did:example:hr_manager", "urgency": "high", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T14:30:00Z", "completed_at": "2023-10-03T15:00:00Z", "actions_taken": [ "reviewed", "approved" ], "feedback_emitted": true } ], "next_cursor": "eyJjcmVhdGVkX2F0IjogIjIwMjMtMTAtMDJUMTQ6MzA6MDBaIiwgIndvcmtfaXRlbV9pZCI6ICJ3aTEyMzQ1In0=" } } } } } }, "400": { "description": "The request was invalid due to missing or incorrect query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing org_did", "description": "An error response when the org_did query parameter is missing.", "value": { "type": "https://humanprotocol.org/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "org_did query parameter is required", "errors": [ { "field": "org_did", "code": "REQUIRED_QUERY_PARAM", "message": "org_did query parameter is required", "expected": "did", "received": "missing" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing delegation token", "description": "An error response when delegation is required but not provided.", "value": { "type": "https://humanprotocol.org/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "The client does not have permission to access the requested organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "mismatched_organization_access": { "summary": "Mismatched organization access", "description": "An error response when the delegation does not match the requested organization.", "value": { "type": "https://humanprotocol.org/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Delegation org does not match requested organization" } } } } } }, "404": { "description": "The specified organization was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization not found", "description": "An error response when the specified organization does not exist.", "value": { "type": "https://humanprotocol.org/probs/not-found", "title": "Not Found", "status": 404, "detail": "Organization not found" } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server error example", "description": "An example of a server error occurring during the request.", "value": { "type": "https://humanprotocol.org/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred" } } } } } } } }, "post": { "summary": "Create a new workforce work item", "description": "This endpoint orchestrates the creation of a new work item within the HUMAN platform's workforce module. It enables organizations to delegate tasks efficiently while ensuring compliance through cryptographic identity verification and capability tracking. Whether you're routing tasks to a personal agent or a team, this endpoint ensures the task is correctly assigned and tracked.", "operationId": "createWorkforceWorkItem", "tags": [ "Workforce", "Task Management" ], "x-code-hash": "f03364391d170fcf", "x-generated-at": "2026-03-28T16:57:20.949Z", "responses": { "201": { "description": "The work item was successfully created.", "content": { "application/json": {} } }, "400": { "description": "Invalid request due to missing or incorrect fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication error due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Authorization error when the delegation does not match the requested organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found error when the organization or workforce module is not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error due to an unexpected condition encountered by the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/workforce/work-items/:work_item_id": { "get": { "summary": "Retrieve detailed work item information", "description": "Unlock the intricate details of a specific work item within the HUMAN ecosystem. This endpoint enables organizations to track and manage workforce tasks with precision, ensuring each task aligns with their strategic goals and operational needs.", "operationId": "getWorkItemDetails", "tags": [ "Workforce", "TaskManagement" ], "x-code-hash": "dca4211bf43dd3dc", "x-generated-at": "2026-03-27T15:04:27.979Z", "responses": { "200": { "description": "Successfully retrieved work item details, offering a snapshot of its current status and metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the work item" }, "org_did": { "type": "string", "description": "Decentralized identifier for the organization" }, "installation_id": { "type": "string", "description": "The ID of the installation associated with the work item" }, "renderer_id": { "type": "string", "description": "Identifier for the renderer" }, "artifact_id": { "type": "string", "description": "Associated artifact ID" }, "status": { "type": "string", "description": "Current status of the work item" }, "routed_to_type": { "type": "string", "description": "Type of entity the task is routed to" }, "routed_to_id": { "type": "string", "description": "Identifier of the entity the task is routed to" }, "routed_by": { "type": "string", "description": "Identifier of the entity that routed the task" }, "urgency": { "type": "string", "description": "Urgency level of the task" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "completed_at": { "type": "string", "format": "date-time", "description": "Completion timestamp, if applicable" }, "actions_taken": { "type": "string", "description": "Description of actions taken on the task" }, "feedback_emitted": { "type": "string", "description": "Feedback provided for the task" } } }, "examples": { "acme_corp_work_item_example": { "summary": "Acme Corp Work Item Example", "description": "Details of a work item processed by Acme Corp", "value": { "id": "wi-123456", "org_did": "did:human:acme", "installation_id": "inst-001", "renderer_id": "renderer-007", "artifact_id": "artifact-789", "status": "in_progress", "routed_to_type": "agent", "routed_to_id": "agent-42", "routed_by": "agent-5", "urgency": "high", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T15:30:00Z", "completed_at": null, "actions_taken": "Reviewed documentation, initiated process", "feedback_emitted": "Positive feedback" } } } } } }, "400": { "description": "The request could not be understood due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_work_item_id_example": { "summary": "Missing work_item_id Example", "description": "Example when the work_item_id parameter is missing.", "value": { "type": "https://example.com/probs/validation-error", "title": "Bad Request", "status": 400, "detail": "The request could not be understood due to validation errors.", "errors": [ { "field": "work_item_id", "code": "REQUIRED_FIELD", "message": "work_item_id path parameter is required", "expected": "string", "received": "empty" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "Example of an error when no delegation token is provided.", "value": { "type": "https://example.com/probs/auth-error", "title": "Unauthorized", "status": 401, "detail": "Delegation required to access this resource." } } } } } }, "403": { "description": "The user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Example when the delegation org does not match the requested organization.", "value": { "type": "https://example.com/probs/permission-error", "title": "Forbidden", "status": 403, "detail": "Delegation org does not match requested organization." } } } } } }, "404": { "description": "The requested work item could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "work_item_not_found_example": { "summary": "Work Item Not Found Example", "description": "Example when the specified work item does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Work item not found." } } } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "Example of a server error during request processing.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/workforce/work-items/:work_item_id/action": { "post": { "summary": "Execute actions on workforce work items", "description": "This endpoint is a cornerstone of dynamic collaboration, enabling authorized agents to execute specific actions on work items in the HUMAN platform. By orchestrating tasks, it ensures that work items are processed efficiently and securely, aligning with organizational needs.", "operationId": "postWorkItemAction", "tags": [ "Workforce", "Task Management" ], "x-code-hash": "8d4f82e2df645a0b", "x-generated-at": "2026-03-28T16:57:38.522Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action_id": { "type": "string", "description": "The identifier for the action to be executed." }, "note": { "type": "string", "description": "An optional note detailing the action." }, "revised_content": { "type": "string", "description": "Revised content for edit actions." }, "form_data": { "type": "object", "description": "Additional data for form-driven actions." }, "org_did": { "type": "string", "description": "The decentralized identifier of the organization." } }, "required": [ "action_id", "org_did" ] }, "examples": { "action_execution_example": { "summary": "Action Execution Example", "description": "An agent from 'acme' organization marking a task as 'approved' with additional notes.", "value": { "action_id": "approve", "note": "Reviewed and approved by manager", "org_did": "did:org:acme123" } } } } } }, "responses": { "200": { "description": "The action was executed successfully on the work item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "actions_taken": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string" }, "note": { "type": "string" }, "actor_did": { "type": "string" }, "at": { "type": "string", "format": "date-time" } } } } } }, "examples": { "default": { "summary": "Example", "value": { "id": "workitem123", "status": "in_progress", "actions_taken": [ { "action_id": "approve", "note": "Reviewed and approved by manager", "actor_did": "did:agent:john.doe", "at": "2023-10-15T14:48:00Z" } ] } } } } } }, "400": { "description": "The request body could not be parsed as valid JSON or required fields are missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/validation", "title": "Invalid Request", "status": 400, "detail": "Request body must be JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please provide valid credentials." } } } } } }, "403": { "description": "Authorization error when delegation org does not match the requested organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authorization", "title": "Forbidden", "status": 403, "detail": "Delegation org does not match requested organization. Ensure correct org DID." } } } } } }, "404": { "description": "The specified work item was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Work item not found. Verify work item ID and org DID." } } } } } }, "500": { "description": "Internal server error during action processing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/orgs/:org_did/workforce/modules": { "get": { "summary": "Retrieve Active Workforce Modules", "description": "Unveil the capabilities of your organization by retrieving active workforce modules. This endpoint empowers you to understand and manage the skills and tools available within your organization, ensuring optimal orchestration of human and AI efforts.", "operationId": "getWorkforceModules", "tags": [ "Organizations", "Workforce Modules" ], "x-code-hash": "00cc622b3b8f8da3", "x-generated-at": "2026-03-27T15:35:34.259Z", "responses": { "200": { "description": "Successfully retrieved the active workforce modules for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier for the organization." }, "modules": { "type": "array", "items": { "type": "object", "properties": { "workforce_module_id": { "type": "string" }, "installation_id": { "type": "string" }, "asset_id": { "type": "string" }, "source_kind": { "type": "string" }, "work_item_renderers": { "type": "array" }, "routing_config": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "asset_name": { "type": "string", "nullable": true }, "asset_type": { "type": "string", "nullable": true }, "trust_tier": { "type": "string", "nullable": true } } } } } }, "examples": { "acme_corp_workforce_modules": { "summary": "Acme Corp Workforce Modules", "description": "A list of active workforce modules for Acme Corp, showcasing their installed capabilities.", "value": { "org_did": "did:example:123456", "modules": [ { "workforce_module_id": "mod-abc123", "installation_id": "inst-xyz456", "asset_id": "asset-78910", "source_kind": "AI", "work_item_renderers": [], "routing_config": {}, "created_at": "2023-10-01T12:34:56Z", "asset_name": "Invoice Processor", "asset_type": "AI Model", "trust_tier": "high" } ] } } } } } }, "400": { "description": "Invalid request due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request": { "summary": "Malformed Request", "description": "The request was not formatted correctly.", "value": { "type": "https://example.com/probs/bad-request", "title": "Bad Request", "status": 400, "detail": "The request syntax is malformed. Please verify the API request format." } } } } } }, "401": { "description": "Authentication required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "The request lacks the necessary delegation for authentication.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please ensure you have included a valid delegation in your request." } } } } } }, "403": { "description": "Authorization failure due to mismatched organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_organization_access": { "summary": "Unauthorized Organization Access", "description": "The delegation org does not match the requested organization.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Delegation org does not match requested organization. Ensure the delegation matches the organization DID in your request." } } } } } }, "404": { "description": "The specified organization was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "The requested organization does not exist in the database.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Organization not found. Verify that the org DID is correct and exists in the database." } } } } } }, "500": { "description": "Unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/discover": { "get": { "summary": "Discover HUMAN platform capabilities", "description": "Uncover the powerful orchestration capabilities of the HUMAN Protocol. This endpoint offers a glimpse into the platform's operational status and available paths, guiding users through a seamless integration into the future of Human-AI collaboration.", "operationId": "getDiscover", "tags": [ "Platform", "Discovery" ], "x-code-hash": "349a31113f6c5f04", "x-generated-at": "2026-03-27T23:16:14.150Z", "responses": { "200": { "description": "Successfully retrieved platform orientation", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "example": "HUMΛN Orchestration Protocol" }, "version": { "type": "string", "example": "v1" }, "status": { "type": "string", "enum": [ "operational", "degraded" ], "example": "operational" }, "authentication": { "type": "object", "properties": { "method": { "type": "string", "example": "Bearer token" }, "header": { "type": "string", "example": "Authorization: Bearer " }, "formats": { "type": "array", "items": { "type": "string" }, "example": [ "delegation_token", "session_jwt", "service_account_key" ] }, "guide": { "type": "string", "example": "https://docs.haio.run/authentication" } } }, "api_reference": { "type": "string", "example": "/v1/openapi.json" }, "capabilities_catalog": { "type": "string", "example": "/v1/system-capabilities" }, "knowledge": { "type": "string", "example": "https://console.haio.run/ai/llms.txt" }, "endpoints": { "type": "object", "properties": { "root": { "type": "string", "example": "/" }, "agents": { "type": "string", "example": "/v1/agents" }, "agents_call": { "type": "string", "example": "/v1/agents/call" }, "executions": { "type": "string", "example": "/v1/async-executions" }, "workforce": { "type": "string", "example": "/v1/workforce" }, "passports": { "type": "string", "example": "/v1/passports" }, "delegations": { "type": "string", "example": "/v1/delegations" }, "capabilities_routing": { "type": "string", "example": "/v1/capabilities/routing" }, "marketplace": { "type": "string", "example": "/v1/marketplace/connectors" }, "sessions": { "type": "string", "example": "/v1/sessions" }, "humanos": { "type": "string", "example": "/v1/humanos" } } }, "links": { "type": "object", "properties": { "website": { "type": "string", "example": "https://builtwithhuman.com" }, "console": { "type": "string", "example": "https://console.haio.run" }, "docs": { "type": "string", "example": "https://builtwithhuman.com/docs" } } } } }, "examples": { "operational_platform_example": { "summary": "Operational Platform Example", "description": "An example of the HUMAN Protocol platform in full operational status.", "value": { "platform": "HUMΛN Orchestration Protocol", "version": "v1", "status": "operational", "authentication": { "method": "Bearer token", "header": "Authorization: Bearer ", "formats": [ "delegation_token", "session_jwt", "service_account_key" ], "guide": "https://docs.haio.run/authentication" }, "api_reference": "/v1/openapi.json", "capabilities_catalog": "/v1/system-capabilities", "knowledge": "https://console.haio.run/ai/llms.txt", "endpoints": { "root": "/", "agents": "/v1/agents", "agents_call": "/v1/agents/call", "executions": "/v1/async-executions", "workforce": "/v1/workforce", "passports": "/v1/passports", "delegations": "/v1/delegations", "capabilities_routing": "/v1/capabilities/routing", "marketplace": "/v1/marketplace/connectors", "sessions": "/v1/sessions", "humanos": "/v1/humanos" }, "links": { "website": "https://builtwithhuman.com", "console": "https://console.haio.run", "docs": "https://builtwithhuman.com/docs" } } } } } } }, "503": { "description": "Service unavailable due to degraded database connection", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "degraded_service_example": { "summary": "Degraded Service Example", "description": "An example response when the database connection is degraded.", "value": { "type": "https://builtwithhuman.com/probs/service-unavailable", "title": "Service Unavailable", "status": 503, "detail": "The database connection is currently degraded. Please try again later." } } } } } } } } }, "/v1/async-executions/:id/pause": { "post": { "summary": "Pause asynchronous execution by ID", "description": "In the dynamic world of task management, sometimes processes need a pause. This endpoint allows you to pause a specified asynchronous execution, offering a respite for the system to handle priorities or address issues. Leveraging the HUMAN Protocol's cryptographic identity (Passport), this operation ensures secure and authorized task handling.", "operationId": "pauseAsyncExecution", "tags": [ "AsyncExecutions", "TaskManagement" ], "x-code-hash": "aa1abffe0b67b96a", "x-generated-at": "2026-03-27T23:17:50.405Z", "responses": { "200": { "description": "Successfully paused the asynchronous execution", "content": { "application/json": {} } }, "400": { "description": "Invalid request format or missing required fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication is required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden action due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified asynchronous execution was not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict due to invalid pause transition", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error occurred while processing the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/async-executions/:id/resume": { "post": { "summary": "Resume an asynchronous execution", "description": "In the dynamic world of AI-driven operations, tasks sometimes pause for various reasons. This endpoint lets authorized agents resume a paused asynchronous execution, ensuring that workflows can continue without missing a beat. By leveraging cryptographic identities and delegations, it securely manages task resumption.", "operationId": "resumeAsyncExecution", "tags": [ "AsyncExecutions", "TaskManagement" ], "x-code-hash": "7dbb6e531af42567", "x-generated-at": "2026-03-27T23:18:22.428Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "examples": { "resume_execution_request": { "summary": "Resume Execution Request", "description": "An example showing the URL with execution ID and necessary headers.", "value": { "headers": { "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "Delegation": "agent:acme/agent123" }, "url": "/v1/async-executions/12345/resume" } } } } } }, "responses": { "200": { "description": "Successfully resumed the asynchronous execution", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "job_id": { "type": "string" }, "resume_count": { "type": "integer" }, "queued_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "job_id", "resume_count", "queued_at" ] }, "examples": { "successful_resumption": { "summary": "Successful Resumption", "description": "The response after successfully resuming an execution.", "value": { "id": "12345", "status": "running", "job_id": "job_67890", "resume_count": 2, "queued_at": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "Bad request due to malformed input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_example": { "summary": "Malformed Request Example", "value": { "type": "https://docs.humanapi.com/errors/bad-request", "title": "Invalid Request", "status": 400, "detail": "The request was malformed. Ensure all parameters are correct." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing Delegation Context", "value": { "type": "https://docs.humanapi.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context. Please ensure your request includes the correct delegation header." } } } } } }, "403": { "description": "Forbidden due to lack of necessary permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_action_example": { "summary": "Forbidden Action Example", "value": { "type": "https://docs.humanapi.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "FORBIDDEN: You do not have permission to resume this execution." } } } } } }, "404": { "description": "Execution not found with the provided ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "execution_not_found_example": { "summary": "Execution Not Found Example", "value": { "type": "https://docs.humanapi.com/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The async execution with ID 12345 was not found. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error when attempting to resume execution", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "value": { "type": "https://docs.humanapi.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An internal error occurred while attempting to resume the execution. Please contact support with incident ID inc_1696528800000." } } } } } } } } }, "/v1/agents/tool-schemas": { "post": { "summary": "Discover and propose agent tool schemas", "description": "Unveil the potential of your organization by discovering agent tools tailored to your specific capabilities. This endpoint serves as a bridge between your organizational needs and the world of Human-AI orchestration, suggesting agent tools that align with your capabilities, workforce, and marketplace opportunities.", "operationId": "postToolSchemas", "tags": [ "Agent Management", "Tool Discovery" ], "x-code-hash": "fa02097eb702b3f6", "x-generated-at": "2026-03-27T23:29:25.623Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "description": "The organization's unique identifier" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of capability URIs to match against agent tools" }, "agent_ids": { "type": "array", "items": { "type": "string" }, "description": "Specific agent IDs to filter results" }, "include_workforce": { "type": "boolean", "description": "Include workforce in the search results" }, "include_marketplace": { "type": "boolean", "description": "Include marketplace suggestions in the results" } }, "required": [ "org_id" ] }, "examples": { "discover_tools_for_acme_corp": { "summary": "Discover tools for Acme Corp", "description": "Showcases a request from Acme Corp to find tools matching their capabilities", "value": { "org_id": "acme-corp", "capabilities": [ "capability://data-analysis", "capability://machine-learning" ], "agent_ids": [], "include_workforce": true, "include_marketplace": true } } } } } }, "responses": { "200": { "description": "A curated list of agent tools and suggestions based on the organization's capabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object" } } }, "human_metadata": { "type": "object", "properties": { "agent_id": { "type": "string" }, "agent_uri": { "type": "string" }, "operation": { "type": "string" }, "required_scopes": { "type": "array", "items": { "type": "string" } }, "capability_uris": { "type": "array", "items": { "type": "string" } }, "delegation_guide": { "type": "string" } } } } } }, "workforce_workers": { "type": "array", "items": { "type": "object", "properties": { "passport_id": { "type": "string" }, "display_name": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "availability_status": { "type": "string" }, "route": { "type": "string" } } } }, "marketplace_suggestions": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "install_required": { "type": "boolean" }, "install_path": { "type": "string" }, "marketplace_url": { "type": "string" } } } }, "capability_gaps": { "type": "array", "items": { "type": "string" } }, "org_id": { "type": "string" }, "tools_count": { "type": "integer" }, "workers_count": { "type": "integer" }, "suggestions_count": { "type": "integer" } } }, "examples": { "successful_discovery_for_acme_corp": { "summary": "Successful discovery for Acme Corp", "description": "The response for a successful tool discovery request by Acme Corp", "value": { "tools": [ { "type": "function", "function": { "name": "human__acme-corp__agent-123__data-analysis", "description": "Data analysis tool for agent 123", "parameters": { "type": "object", "properties": { "inputData": { "type": "string" } } } }, "human_metadata": { "agent_id": "agent-123", "agent_uri": "agent://acme-corp/agent-123", "operation": "data-analysis", "required_scopes": [ "human_api:agents:call", "human_api:agents:invoke" ], "capability_uris": [ "capability://data-analysis" ], "delegation_guide": "POST /v1/delegations — obtain scopes before calling POST /v1/agents/call" } } ], "workforce_workers": [ { "passport_id": "worker-456", "display_name": "Worker 456", "capabilities": [ "capability://data-analysis" ], "availability_status": "available", "route": "POST /v1/orgs/acme-corp/workforce/tasks" } ], "marketplace_suggestions": [], "capability_gaps": [], "org_id": "acme-corp", "tools_count": 1, "workers_count": 1, "suggestions_count": 0 } } } } } }, "400": { "description": "The request was malformed and could not be processed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_id": { "summary": "Missing org_id", "description": "Example error when org_id is not provided", "value": { "type": "https://humanprotocol.org/errors/400", "title": "Bad Request", "status": 400, "detail": "org_id is required", "errors": [ { "field": "org_id", "code": "REQUIRED_FIELD_MISSING", "message": "org_id is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_context": { "summary": "Missing delegation context", "description": "Example error when delegation context is missing", "value": { "type": "https://humanprotocol.org/errors/401", "title": "Unauthorized", "status": 401, "detail": "Missing delegation context" } } } } } }, "403": { "description": "The request is understood, but it has been refused or access is not allowed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "description": "Example error when access is denied", "value": { "type": "https://humanprotocol.org/errors/403", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource" } } } } } }, "404": { "description": "The requested resource could not be found but may be available in the future", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "Example error when the resource is not found", "value": { "type": "https://humanprotocol.org/errors/404", "title": "Not Found", "status": 404, "detail": "The specified resource was not found" } } } } } }, "500": { "description": "An unexpected error has occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "description": "Example error when an unexpected error occurs", "value": { "type": "https://humanprotocol.org/errors/500", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error has occurred. Please try again later." } } } } } } } } }, "/v1/workflows/:id/pause": { "post": { "summary": "Pause a running workflow instance", "description": "In the realm of orchestrating complex tasks, sometimes workflows need a moment to pause and breathe. This endpoint empowers users to pause an active workflow, transitioning all running nodes to a state of waiting approval. It ensures that no step is taken without consideration, while logging the pause for transparency and accountability.", "operationId": "pauseWorkflow", "tags": [ "Workflow Management", "Task Orchestration" ], "x-code-hash": "fcbfd1523d7587d1", "x-generated-at": "2026-03-28T16:50:15.506Z", "responses": { "200": { "description": "The workflow has been successfully paused, and all active nodes are now awaiting approval.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string", "description": "The unique identifier of the paused workflow." }, "status": { "type": "string", "enum": [ "paused" ], "description": "The current status of the workflow." }, "paused_nodes": { "type": "integer", "description": "Number of nodes that were paused." }, "paused_at": { "type": "string", "format": "date-time", "description": "The timestamp when the workflow was paused." } }, "required": [ "workflow_id", "status", "paused_nodes", "paused_at" ] }, "examples": { "successful_pause": { "summary": "Successful Pause", "description": "An example illustrating a successful pause of a workflow with several running nodes.", "value": { "workflow_id": "workflow-12345", "status": "paused", "paused_nodes": 3, "paused_at": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "The request is malformed or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request": { "summary": "Malformed Request", "description": "The request was missing required parameters.", "value": { "type": "https://human.api/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request was malformed. Ensure all required parameters are included and correctly formatted." } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "The user must authenticate to access this endpoint.", "value": { "type": "https://human.api/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided. Please provide a valid token." } } } } } }, "403": { "description": "The server understood the request, but it refuses to authorize it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user does not have permission to pause this workflow.", "value": { "type": "https://human.api/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to pause this workflow. Please contact your administrator." } } } } } }, "404": { "description": "The specified workflow could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "No workflow exists with the specified ID.", "value": { "type": "https://human.api/errors/not-found", "title": "Not Found", "status": 404, "detail": "Workflow with ID 'workflow-12345' was not found. Please verify the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred during the pause operation.", "value": { "type": "https://human.api/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1696512510." } } } } } } } } }, "/v1/workflows/:id/resume": { "post": { "summary": "Resume paused workflow for active processing", "description": "This endpoint is the key to unlocking potential in workflows that have hit a pause. Imagine the gears of a complex machine grinding to a halt awaiting approval—this endpoint breathes life back into them. By resuming paused nodes within a workflow's DAG, it ensures that no opportunity for progress is lost.", "operationId": "resumeWorkflow", "tags": [ "Workflows", "Execution" ], "x-code-hash": "cc0ee4a9b24717c3", "x-generated-at": "2026-03-28T16:50:29.242Z", "responses": { "200": { "description": "The workflow was successfully resumed, with nodes transitioning to a running state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string", "description": "The unique identifier for the resumed workflow." }, "status": { "type": "string", "enum": [ "running" ], "description": "The current status of the workflow after resumption." }, "resumed_nodes": { "type": "integer", "description": "Number of nodes that were resumed." }, "resumed_at": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the workflow was resumed." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request is malformed or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The workflow ID must be a valid identifier.", "errors": [ "Missing or invalid parameter: id" ] } } } } } }, "401": { "description": "Authentication failure due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication required to resume workflow." } } } } } }, "403": { "description": "Permission denied due to insufficient access rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to resume this workflow." } } } } } }, "404": { "description": "The specified workflow could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/not-found", "title": "Workflow Not Found", "status": 404, "detail": "No workflow found with ID wf-12345-acme." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while attempting to resume the workflow. Please try again later." } } } } } } } } }, "/v1/workflows/:id/trigger": { "post": { "summary": "Trigger a workflow manually", "description": "Spark the lifeline of automation by manually triggering a workflow. This endpoint initiates a new Directed Acyclic Graph (DAG) root node and sends a beacon, the `workflow.manual-trigger` event, for Inngest to capture and act upon. It's designed for those moments when you need to intervene and start a process outside the regular flow, providing flexibility and control in orchestrating complex operations.", "operationId": "triggerWorkflowManually", "tags": [ "Workflow Management", "Automation" ], "x-code-hash": "fc6f75f44c13d0c7", "x-generated-at": "2026-03-28T16:50:50.225Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "description": "Additional data to pass along with the workflow trigger" } }, "required": [] }, "examples": { "basic_trigger": { "summary": "Basic Trigger", "description": "Triggering a workflow with minimal context", "value": { "context": { "initiator": "acme-corp", "reason": "Quarterly financial report generation" } } } } } } }, "responses": { "200": { "description": "Workflow successfully triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string", "description": "The unique identifier of the triggered workflow" }, "run_id": { "type": "string", "description": "The unique identifier for this specific run" }, "status": { "type": "string", "description": "The current status of the workflow" }, "triggered_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the workflow was triggered" } } }, "examples": { "default": { "summary": "Example", "value": { "workflow_id": "wf12345", "run_id": "wrun67890", "status": "triggered", "triggered_at": "2023-10-11T14:32:08Z" } } } } } }, "400": { "description": "Invalid request due to malformed input or missing required fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Bad Request", "status": 400, "detail": "The request body is malformed. Ensure that your JSON is correctly structured and try again.", "errors": [ "Invalid JSON format" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid. Please ensure your API key is correct and try again." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Your credentials do not allow access to this resource. Please contact your administrator to request access." } } } } } }, "404": { "description": "The specified workflow was not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The workflow with ID 'wf12345' could not be found. Ensure the ID is correct and try again." } } } } } }, "500": { "description": "Internal server error occurred while processing the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while triggering the workflow. Please try again later or contact support with incident ID inc_1697031128." } } } } } } } } }, "/v1/extensions/install": { "post": { "summary": "Install an Extension for an Organization", "description": "Empower your organization by seamlessly integrating new capabilities through extensible modules. This endpoint is the gateway to enhancing your operational landscape by installing extensions that align with your strategic goals.", "operationId": "installExtension", "tags": [ "Extensions", "Organization" ], "x-code-hash": "cf787d4640e20512", "x-generated-at": "2026-03-28T16:51:08.828Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "extensionId": { "type": "string", "description": "Unique identifier of the extension to be installed." }, "config": { "type": "object", "description": "Optional configuration settings for the extension." } }, "required": [ "extensionId" ] }, "examples": { "basic_installation": { "summary": "Basic Installation", "description": "Installing the 'invoice-processor' extension with default settings.", "value": { "extensionId": "invoice-processor", "config": { "currency": "USD", "threshold": 1000 } } } } } } }, "responses": { "201": { "description": "Extension successfully installed, returning installation details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "entity_id": { "type": "string" }, "extension_id": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object" }, "status": { "type": "string" }, "triggers": { "type": [ "null", "array" ], "items": { "type": "string" } }, "installed_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "successful_installation": { "summary": "Successful Installation", "value": { "id": "inst_1234567890abcdef", "entity_id": "org_acme_corp", "extension_id": "invoice-processor", "permissions": [], "config": { "currency": "USD", "threshold": 1000 }, "status": "active", "triggers": null, "installed_at": "2023-10-05T14:48:00Z", "updated_at": "2023-10-05T14:48:00Z" } } } } } }, "400": { "description": "Malformed request body or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problem/invalid-request", "title": "Invalid JSON Body", "status": 400, "detail": "Request body must be a JSON object", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be a JSON object", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problem/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Delegation required to install extensions. Ensure your request includes valid delegation credentials." } } } } } }, "403": { "description": "Permission denied due to insufficient rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problem/permission-denied", "title": "Permission Denied", "status": 403, "detail": "Your current permissions do not allow installation of this extension. Contact your administrator to request access." } } } } } }, "500": { "description": "Unexpected error occurred during the installation process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/problem/internal-server-error", "title": "Extension Installation Failed", "status": 500, "detail": "An unexpected error occurred while installing the extension. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/extensions": { "get": { "summary": "Retrieve installed extensions for organization", "description": "Unlock the potential of your organization by exploring the array of extensions currently installed. This endpoint offers a curated view into your toolkit, empowering you to harness the full spectrum of capabilities tailored to your needs. By understanding what's active, you can strategize your next innovations and streamline operations.", "operationId": "getInstalledExtensions", "tags": [ "Extensions", "Organization" ], "x-code-hash": "2afdcc371281d95c", "x-generated-at": "2026-03-28T16:51:31.803Z", "responses": { "200": { "description": "A paginated list of installed extensions for the requesting organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "entity_id": { "type": "string" }, "extension_id": { "type": "string" }, "permissions": { "type": "object" }, "config": { "type": "object" }, "status": { "type": "string" }, "triggers": { "type": [ "object", "null" ] }, "installed_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "entity_id", "extension_id", "permissions", "config", "status", "installed_at", "updated_at" ] } }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "hasMore" ] }, "examples": { "example_of_installed_extensions": { "summary": "Example of installed extensions", "description": "Shows a typical response with two installed extensions.", "value": { "data": [ { "id": "ext-1", "entity_id": "org-acme-corp", "extension_id": "12345", "permissions": { "read": true, "write": false }, "config": { "theme": "dark" }, "status": "active", "triggers": null, "installed_at": "2023-03-15T12:34:56Z", "updated_at": "2023-09-01T08:22:30Z" }, { "id": "ext-2", "entity_id": "org-acme-corp", "extension_id": "67890", "permissions": { "read": true, "write": true }, "config": { "theme": "light" }, "status": "inactive", "triggers": { "onEvent": "update" }, "installed_at": "2023-02-10T11:30:45Z", "updated_at": "2023-10-01T09:15:20Z" } ], "limit": 10, "hasMore": false } } } } } }, "400": { "description": "The request was malformed. This often occurs when the cursor is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "Shows error details when a malformed cursor is provided.", "value": { "type": "https://humanprotocol.org/errors/validation", "title": "Invalid Cursor", "status": 400, "detail": "The provided cursor is invalid or malformed.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Cursor could not be decoded" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_example": { "summary": "Missing Delegation Example", "description": "Error when delegation information is missing.", "value": { "type": "https://humanprotocol.org/errors/authentication", "title": "Delegation Required", "status": 401, "detail": "Delegation required to list extensions." } } } } } }, "403": { "description": "The requesting entity does not have permission to view the extensions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Shows a response when access is denied due to insufficient permissions.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have permission to view the extensions for this organization." } } } } } }, "404": { "description": "No extensions found for the specified organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not Found Example", "description": "Shows a response when no extensions are found.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Extensions Not Found", "status": 404, "detail": "No extensions found for the organization 'org-acme-corp'." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "Shows a response when an unexpected server error occurs.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/extensions/:id": { "delete": { "summary": "Remove an installed extension securely", "description": "Uninstalling an extension is crucial when you no longer need its capabilities or when it's outdated. This endpoint ensures safe removal by verifying user permissions, maintaining system integrity through transactional deletions, and updating provenance records. Such careful measures protect your organization's data and AI processes.", "operationId": "removeExtension", "tags": [ "Extensions", "Management" ], "x-code-hash": "acbbe08047ed3b1a", "x-generated-at": "2026-03-28T17:24:42.226Z", "responses": { "204": { "description": "The extension was successfully uninstalled.", "content": { "application/json": { "examples": { "successful_uninstallation": { "summary": "Successful Uninstallation", "description": "An extension is removed successfully from the system.", "value": null } } } } }, "400": { "description": "Bad request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_input": { "summary": "Malformed Input", "description": "An error response indicating malformed syntax.", "value": { "type": "https://example.com/probs/bad-request", "title": "Bad Request", "status": 400, "detail": "The request could not be understood by the server due to malformed syntax." } } } } } }, "401": { "description": "Authentication required to process the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "An error response when no delegation is provided.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required to remove extensions. Please authenticate." } } } } } }, "403": { "description": "You do not have permission to remove this extension.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "An error response when the user lacks the necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to remove this extension installation." } } } } } }, "404": { "description": "The extension with the specified ID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "extension_not_found": { "summary": "Extension Not Found", "description": "An error response when the specified extension does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The extension could not be found." } } } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_error": { "summary": "Internal Error", "description": "An error response for unexpected server issues.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/extensions/:id/invoke": { "post": { "summary": "Invoke an extension's capability for action", "description": "Unlock the potential of your organization's installed extensions by invoking specific capabilities. This endpoint is the gateway to extending functionality, allowing you to orchestrate tasks and actions with precision and control. It exists to seamlessly integrate and activate the diverse capabilities within your distributed AI systems.", "operationId": "invokeExtensionCapability", "tags": [ "Extensions", "Capabilities", "HumanOS" ], "x-code-hash": "092427b740dd44b4", "x-generated-at": "2026-03-28T17:24:57.308Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capability": { "type": "string", "description": "The capability to be invoked, identified by a URI" }, "action": { "type": "string", "description": "The action to perform using the capability" }, "params": { "type": "object", "description": "Parameters required for the action" } }, "required": [ "capability" ] }, "examples": { "invoke_invoice_processing": { "summary": "Invoke Invoice Processing", "description": "Invoke the 'processInvoice' capability to automate invoice handling for the 'acme' organization.", "value": { "capability": "capability://acme/invoice/process", "action": "process", "params": { "invoiceId": "INV-12345", "amount": 1500 } } } } } } }, "responses": { "200": { "description": "The capability invocation was acknowledged and is being processed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "installation_id": { "type": "string", "description": "The ID of the extension installation" }, "extension_id": { "type": "string", "description": "The ID of the extension" }, "capability": { "type": "string", "description": "The capability that was invoked" }, "action": { "type": "string", "description": "The action that was requested" }, "params": { "type": "object", "description": "Parameters used for the action" }, "result": { "type": "null", "description": "The result of the invocation (placeholder for future implementation)" }, "status": { "type": "string", "description": "Status of the invocation request" }, "message": { "type": "string", "description": "Informational message regarding the invocation" }, "invoked_at": { "type": "string", "format": "date-time", "description": "Timestamp when the capability was invoked" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be a JSON object", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be a JSON object", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/authentication-error", "title": "Unauthorized", "status": 401, "detail": "Delegation required to invoke extensions" } } } } } }, "403": { "description": "Permission error when attempting to invoke an unauthorized extension.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/insufficient-permissions", "title": "Forbidden", "status": 403, "detail": "You do not have permission to invoke this extension installation." } } } } } }, "404": { "description": "The requested extension installation was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/not-found", "title": "Not Found", "status": 404, "detail": "Extension installation with ID 'install-456' was not found." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/extensions/:id/webhook": { "post": { "summary": "Process incoming webhooks for extensions", "description": "This endpoint orchestrates the reception of webhooks from external services for specific extensions, ensuring seamless integration and task automation. It empowers developers to extend the HUMAN platform by acknowledging incoming data from third-party sources, facilitating a real-time, responsive ecosystem.", "operationId": "processExtensionWebhook", "tags": [ "Extensions", "Webhooks" ], "x-code-hash": "e54db7917a8f167a", "x-generated-at": "2026-03-28T17:25:12.310Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "description": "The type of event triggering the webhook" }, "data": { "type": "object", "additionalProperties": true, "description": "The event-specific data payload" } }, "required": [ "event" ] }, "examples": { "example_webhook_event": { "summary": "Example Webhook Event", "description": "A webhook event triggered by an external service", "value": { "event": "invoice.processed", "data": { "invoiceId": "inv-123456", "amount": 2500, "currency": "USD" } } } } } } }, "responses": { "200": { "description": "The webhook was successfully received and acknowledged", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "description": "Indicates successful receipt" }, "installation_id": { "type": "string", "description": "The ID of the installed extension" }, "extension_id": { "type": "string", "description": "The ID of the extension that received the webhook" }, "received_at": { "type": "string", "format": "date-time", "description": "Timestamp of receipt" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request payload", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Forbidden access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "Extension not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/control-plane/executions": { "get": { "summary": "Retrieve Execution Records for Organization", "description": "Dive into the orchestration of AI and human tasks with detailed execution records. This endpoint empowers organizations by retrieving the history of task executions, allowing for insightful analysis and optimization of processes. By filtering through status and surface, organizations can pinpoint specific operations and evaluate their effectiveness.", "operationId": "getControlPlaneExecutions", "tags": [ "ControlPlane", "Executions" ], "x-code-hash": "8d491c58dc0954e8", "x-generated-at": "2026-03-28T16:53:48.067Z", "responses": { "200": { "description": "Successfully retrieved execution records.", "content": { "application/json": {} } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found for the given query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error due to unexpected issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/control-plane/executions/:id": { "get": { "summary": "Retrieve execution details by ID", "description": "Unlock the insights of your task orchestration by fetching detailed execution data through this endpoint. It bridges the gap between human and AI efforts, providing a comprehensive view of your operation's journey from start to finish. Trace every step, understand the status, and connect with the agents involved, making this endpoint your window into the orchestration process.", "operationId": "getExecutionDetailsById", "tags": [ "ControlPlane", "Execution" ], "x-code-hash": "1b665fa181f0fa9e", "x-generated-at": "2026-03-28T16:54:19.385Z", "responses": { "200": { "description": "Execution details successfully retrieved, incorporating both control plane and asynchronous execution data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the control plane execution." }, "execution_id": { "type": "string", "description": "Execution identifier, typically used to link related asynchronous executions." }, "org_did": { "type": "string", "description": "Decentralized ID of the organization responsible for the execution." }, "incident_id": { "type": "string", "description": "Identifier of the related incident, if applicable." }, "surface": { "type": "string", "description": "The surface where the execution is taking place." }, "status": { "type": "string", "description": "Current status of the execution." }, "started_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution started." }, "completed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution was completed." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Additional metadata related to the execution." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp of the execution record." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp of the execution record." }, "async_execution": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the asynchronous execution, if available." }, "task_id": { "type": "string", "description": "Task identifier associated with the asynchronous execution." }, "agent_id": { "type": "string", "description": "Identifier of the agent handling the asynchronous execution." }, "requester_passport_id": { "type": "string", "description": "Passport ID of the entity requesting the execution." }, "async_status": { "type": "string", "description": "Current status of the asynchronous execution." }, "progress_percent": { "type": "number", "description": "Progress percentage of the asynchronous execution." }, "progress_message": { "type": "string", "description": "Descriptive message about the current progress." }, "queued_at": { "type": "string", "format": "date-time", "description": "Timestamp when the task was queued for execution." }, "started_at": { "type": "string", "format": "date-time", "description": "Timestamp when the asynchronous execution started." }, "completed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the asynchronous execution was completed." } }, "description": "Details of the linked asynchronous execution, if any." } }, "required": [ "id", "execution_id", "org_did", "status", "created_at", "updated_at" ] }, "examples": { "acme_corp_execution_retrieval": { "summary": "Acme Corp Execution Retrieval", "description": "Fetching an execution record for Acme Corp, including details of a linked asynchronous task.", "value": { "id": "123e4567-e89b-12d3-a456-426614174000", "execution_id": "exec-789", "org_did": "did:human:acme-corp", "incident_id": "incident-001", "surface": "web", "status": "completed", "started_at": "2023-10-01T08:00:00Z", "completed_at": "2023-10-01T09:00:00Z", "metadata": { "priority": "high", "category": "finance" }, "created_at": "2023-09-28T07:00:00Z", "updated_at": "2023-10-01T09:05:00Z", "async_execution": { "id": "async-456", "task_id": "task-123", "agent_id": "agent-007", "requester_passport_id": "passport-xyz", "async_status": "completed", "progress_percent": 100, "progress_message": "Task completed successfully.", "queued_at": "2023-09-30T06:00:00Z", "started_at": "2023-10-01T08:30:00Z", "completed_at": "2023-10-01T09:00:00Z" } } } } } } }, "400": { "description": "Bad request due to missing or invalid execution ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_execution_id": { "summary": "Missing Execution ID", "description": "The request failed because the execution ID was not provided.", "value": { "type": "https://example.com/probs/validation-error", "title": "Bad Request", "status": 400, "detail": "execution id is required", "errors": [ { "field": "id", "code": "REQUIRED", "message": "execution id is required", "expected": "cp_executions id", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The request failed due to missing authentication token.", "value": { "type": "https://example.com/probs/auth-error", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The request was denied because the user does not have permission to view the execution details.", "value": { "type": "https://example.com/probs/permission-error", "title": "Forbidden", "status": 403, "detail": "User does not have the necessary permissions to access this resource." } } } } } }, "404": { "description": "Execution not found due to invalid execution ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "execution_not_found": { "summary": "Execution Not Found", "description": "The execution ID provided does not correspond to any existing execution.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "cp execution with ID '123e4567-e89b-12d3-a456-426614174000' not found." } } } } } }, "500": { "description": "Internal server error caused by unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred within the server.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/marketplace/install/preview": { "post": { "summary": "Preview Marketplace Bundle Installation", "description": "Embark on a journey to seamlessly preview the installation of marketplace bundles. This endpoint offers a glimpse into the future, enabling organizations to assess the impact and compatibility of installing a new bundle before committing to it, ensuring smooth transitions and maintaining operational harmony.", "operationId": "previewMarketplaceBundleInstall", "tags": [ "Marketplace", "Bundles" ], "x-code-hash": "a3ce218795a7d1ab", "x-generated-at": "2026-03-29T14:48:40.162Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset_id", "org_did" ], "properties": { "asset_id": { "type": "string", "description": "The unique identifier for the asset bundle." }, "org_did": { "type": "string", "description": "The decentralized identifier for the organization." }, "preset": { "type": "string", "enum": [ "safe", "autopilot", "custom" ], "description": "The installation preset to use, offering various levels of automation and safety." } } }, "examples": { "standard_bundle_preview": { "summary": "Standard Bundle Preview", "description": "Previewing the installation of a bundle with standard safety preset in the ACME organization.", "value": { "asset_id": "bundle12345", "org_did": "did:human:acme-org", "preset": "safe" } } } } } }, "responses": { "200": { "description": "Successfully generates a preview of the bundle installation, detailing member inclusion, delegation implications, and policy compatibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "description": "Details about the bundle members and delegation summary." }, "policy_compatibility": { "type": "object", "description": "Analysis of the bundle's policy compatibility with the organization's existing policies." } } }, "examples": { "default": { "summary": "Example", "value": { "preview": { "members": [ "agent1", "agent2" ], "delegation_summary": "Delegation is aligned with organizational policies." }, "policy_compatibility": { "compatible": true, "issues": [] } } } } } } }, "400": { "description": "Occurs when required fields are missing in the request body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing required fields", "status": 400, "detail": "asset_id and org_did are required." } } } } } }, "401": { "description": "Authentication failure due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Delegation Required", "status": 401, "detail": "Delegation required for install preview. Ensure your request includes valid delegation information." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to preview this bundle installation. Contact your administrator for access." } } } } } }, "404": { "description": "The specified asset could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Asset Not Found", "status": 404, "detail": "Asset 'bundle12345' not found. Verify the asset ID and try again." } } } } } }, "422": { "description": "The asset is not approved for installation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/asset-not-approved", "title": "Asset Not Approved", "status": 422, "detail": "The asset has not been approved for installation. Please seek approval from the asset manager." } } } } } }, "500": { "description": "An unexpected server error occurred, preventing the installation preview.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/marketplace/bundles/export": { "post": { "summary": "Export marketplace bundle for offline review", "description": "In the world of secure data management, reviewing asset bundles offline is crucial for maintaining air-gap security. This endpoint facilitates the export of a signed bundle, complete with an HMAC manifest and member digests, allowing you to safely review your assets without an active network connection.", "operationId": "exportMarketplaceBundle", "tags": [ "Marketplace", "Security" ], "x-code-hash": "0160a213bdf17d81", "x-generated-at": "2026-03-29T14:48:50.553Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle_asset_id": { "type": "string", "description": "The unique identifier of the bundle to export" } }, "required": [ "bundle_asset_id" ] }, "examples": { "export_a_bundle_for_acme_corp": { "summary": "Export a Bundle for Acme Corp", "description": "Exporting the asset bundle with ID 'bundle-12345' for review by Acme Corp's security team.", "value": { "bundle_asset_id": "bundle-12345" } } } } } }, "responses": { "200": { "description": "The bundle export was successful, providing a signed HMAC manifest and member digests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hmac_manifest": { "type": "string", "description": "The cryptographic manifest of the exported bundle" }, "member_digests": { "type": "array", "items": { "type": "string" }, "description": "An array of digests for each bundled member" } } }, "examples": { "default": { "summary": "Example", "value": { "hmac_manifest": "hmac-abc123", "member_digests": [ "digest1", "digest2", "digest3" ] } } } } } }, "400": { "description": "Bad Request due to missing or invalid data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing bundle_asset_id", "status": 400, "detail": "bundle_asset_id is required." } } } } } }, "401": { "description": "Unauthorized access due to missing delegation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Delegation Required", "status": 401, "detail": "Delegation required for bundle export." } } } } } }, "404": { "description": "The requested bundle was not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Bundle Not Found", "status": 404, "detail": "The bundle with ID 'bundle-12345' was not found." } } } } } }, "500": { "description": "Internal server error while exporting the bundle", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the bundle export." } } } } } } } } }, "/v1/control-plane/marketplace/bundles/compensate": { "post": { "summary": "Compensate bundle installation rollback", "description": "When an AI bundle installation encounters an unforeseen rollback or partial failure, the compensate endpoint restores balance. By invoking this endpoint, operators ensure the orchestration environment remains consistent, resolving issues without manual intervention.", "operationId": "compensateBundleInstallation", "tags": [ "Marketplace", "Bundles" ], "x-code-hash": "95028573a222f355", "x-generated-at": "2026-03-29T14:49:00.514Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bundle_installation_id", "org_did" ], "properties": { "bundle_installation_id": { "type": "string", "description": "Unique identifier of the bundle installation" }, "org_did": { "type": "string", "description": "Decentralized Identifier (DID) of the organization" } } }, "examples": { "typical_compensation_request": { "summary": "Typical compensation request", "description": "Request to compensate a rollback for 'acme' organization", "value": { "bundle_installation_id": "abc123xyz", "org_did": "did:human:acme-456" } } } } } }, "responses": { "200": { "description": "Successfully compensated the bundle installation rollback", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Compensation completed successfully for bundle installation abc123xyz" } } }, "examples": { "default": { "summary": "Example", "value": { "message": "Compensation completed successfully for bundle installation abc123xyz" } } } } } }, "400": { "description": "Invalid input data provided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing fields", "status": 400, "detail": "bundle_installation_id and org_did are required." } } } } } }, "401": { "description": "Delegation missing or invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Delegation required", "status": 401, "detail": "Delegation required for bundle compensate" } } } } } }, "404": { "description": "Specified bundle installation not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "Bundle installation abc123xyz not found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred." } } } } } } } } }, "/v1/control-plane/diagnostics/metrics/action-receipt-coverage": { "get": { "summary": "Retrieve Action Receipt Coverage Metric", "description": "Gauge the fidelity of human-AI interactions within your organization by examining the proportion of completed tasks that include an ActionReceipt. This metric helps ensure compliance with the ActionReceipt contract, targeting a coverage ratio of 90% or higher.", "operationId": "getActionReceiptCoverage", "tags": [ "Diagnostics", "Metrics" ], "x-code-hash": "45d00b9eef809425", "x-generated-at": "2026-03-29T14:49:12.759Z", "responses": { "200": { "description": "Successfully retrieved action receipt coverage metrics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier for the organization." }, "window_days": { "type": "integer", "description": "Number of days spanned by the sample window." }, "completed_invocations_sampled": { "type": "integer", "description": "Total number of completed human.call invocations sampled." }, "with_action_receipt": { "type": "integer", "description": "Count of completed invocations with an ActionReceipt." }, "receipt_coverage_ratio": { "type": [ "number", "null" ], "description": "Ratio of invocations with ActionReceipt. Null if no invocations." }, "note": { "type": "string", "description": "Additional notes on the metric calculation." } }, "required": [ "org_did", "window_days", "completed_invocations_sampled", "with_action_receipt", "receipt_coverage_ratio", "note" ] }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "value": { "org_did": "did:example:123456789abcdefghi", "window_days": 7, "completed_invocations_sampled": 150, "with_action_receipt": 135, "receipt_coverage_ratio": 0.9, "note": "Sampled from idempotency_keys (cached human.call responses). Target ≥ 0.9 per ActionReceipt contract." } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid": { "summary": "Missing orgDid", "value": { "type": "https://haio.run/errors/validation", "title": "Missing orgDid", "status": 400, "detail": "orgDid query parameter is required." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Valid authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found due to an incorrect endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found": { "summary": "Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested endpoint does not exist." } } } } } }, "503": { "description": "Service unavailable due to temporary server issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "service_unavailable": { "summary": "Service Unavailable", "value": { "type": "https://haio.run/errors/unavailable", "title": "Metric unavailable", "status": 503, "detail": "Could not read idempotency sample." } } } } } } } } }, "/v1/billing/compute/drilldown": { "get": { "summary": "Retrieve detailed compute billing insights", "description": "Dive into the details of your organization's compute billing usage. This endpoint empowers administrators to analyze compute costs, track resource consumption, and optimize expenses by providing granular insights into billing events. It exists to ensure transparency and promote informed decision-making within your organization.", "operationId": "getBillingComputeDrilldown", "tags": [ "Billing", "Analytics" ], "x-code-hash": "fe782edc0f102cdb", "x-generated-at": "2026-03-29T15:49:09.567Z", "responses": { "200": { "description": "A paginated list of billing events with detailed attributes reflecting resource usage and costs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "charged_at": { "type": "string", "format": "date-time" }, "feature": { "type": "string" }, "resource_type": { "type": "string" }, "quantity": { "type": "number" }, "billing_category": { "type": [ "string", "null" ] }, "execution_location": { "type": [ "string", "null" ] }, "agent_id": { "type": [ "string", "null" ] }, "delegation_id": { "type": [ "string", "null" ] }, "user_id": { "type": [ "string", "null" ] }, "workspace_id": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "tokens_used": { "type": [ "number", "null" ] }, "cost_usd": { "type": [ "number", "null" ] }, "governed_event_id": { "type": [ "string", "null" ] }, "cost_center": { "type": [ "string", "null" ] } }, "required": [ "id", "charged_at", "feature", "resource_type", "quantity" ] } }, "limit": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] } } }, "examples": { "compute_billing_drilldown_example": { "summary": "Compute Billing Drilldown Example", "description": "An example response showing detailed billing events for an organization.", "value": { "data": [ { "id": "evt_01G5T8V2YZCGT4T9B4STZ8VXV2", "charged_at": "2023-08-01T12:00:00Z", "feature": "AI Model Training", "resource_type": "GPU Hours", "quantity": 150, "billing_category": "compute", "execution_location": "us-east-1", "agent_id": "agent_12345", "delegation_id": "del_67890", "user_id": "user_112233", "workspace_id": "ws_445566", "provider": "AWS", "model": "BERT", "tokens_used": 10000, "cost_usd": 300, "governed_event_id": "gov_98765", "cost_center": "R&D" } ], "limit": 10, "nextCursor": "evt_01G5T8V2YZCGT4T9B4STZ8VXW3" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid Parameters", "value": { "type": "https://haio.run/errors/invalid-parameters", "title": "Invalid parameters provided", "status": 400, "detail": "The provided 'from' date is not valid. Ensure it follows the ISO 8601 format." } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access due to lack of permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "value": { "type": "https://haio.run/errors/authorization", "title": "Org context required", "status": 403, "detail": "Select an organization to access billing details." } }, "insufficient_plan": { "summary": "Insufficient Plan", "value": { "type": "https://haio.run/errors/entitlement-required", "title": "Billing dashboard requires Team plan or above", "status": 403, "detail": "The compute drill-down requires the billing_dashboard entitlement, included from Team plan onwards. Upgrade to unlock." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource does not exist." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/billing/compute/summary": { "get": { "summary": "Retrieve compute billing summary", "description": "Uncover a detailed breakdown of compute usage costs. This endpoint empowers organizations to gain insights into their resource consumption, enabling data-driven decisions on budgeting and optimization. Dive deep into per-user, per-app, and per-model analytics to visualize spending patterns.", "operationId": "getBillingComputeSummary", "tags": [ "Billing", "Analytics" ], "x-code-hash": "606d5909e1f06485", "x-generated-at": "2026-03-29T15:49:22.553Z", "responses": { "200": { "description": "Successfully retrieved the compute billing summary for the specified period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "by_user": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "total_quantity": { "type": "number" }, "event_count": { "type": "number" } } } }, "by_model": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "total_quantity": { "type": "number" }, "event_count": { "type": "number" } } } }, "by_feature": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "billing_category": { "type": "string" }, "total_quantity": { "type": "number" } } } } } }, "examples": { "billing_summary_for_techguru": { "summary": "Billing summary for TechGuru", "description": "A snapshot of TechGuru's compute resource usage over the past month.", "value": { "period": { "from": "2023-09-01T00:00:00Z", "to": "2023-09-30T23:59:59Z" }, "by_user": [ { "user_id": "alice@example.com", "total_quantity": 1500, "event_count": 75 }, { "user_id": "bob@example.com", "total_quantity": 1200, "event_count": 60 } ], "by_model": [ { "model": "gpt-4", "total_quantity": 1800, "event_count": 90 }, { "model": "bert-base", "total_quantity": 900, "event_count": 45 } ], "by_feature": [ { "feature": "invoice-processing", "billing_category": "compute", "total_quantity": 2000 }, { "feature": "chatbot", "billing_category": "compute", "total_quantity": 700 } ] } } } } } }, "403": { "description": "Access forbidden due to missing or insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "Attempt to access billing summary without selecting an organization.", "value": { "type": "https://haio.run/errors/authorization", "title": "Org context required", "status": 403, "detail": "Select an organization to access billing summary." } }, "insufficient_plan_entitlement": { "summary": "Insufficient Plan Entitlement", "description": "Attempt to access billing summary without the required plan.", "value": { "type": "https://haio.run/errors/entitlement-required", "title": "Billing dashboard requires Team plan or above", "status": 403, "detail": "Upgrade to Team plan or above to access usage analytics." } } } } } } } } }, "/v1/kb/documents": { "get": { "summary": "Retrieve Knowledge Base Documents", "description": "This endpoint unveils the curated tapestry of documents within your knowledge base, meticulously orchestrated to balance access with governance. Imagine delving into a library where every book is tailored to your unique Passport — this is your gateway.", "operationId": "getKbDocuments", "tags": [ "KnowledgeBase", "Documents" ], "x-code-hash": "d39abf248659f2d0", "x-generated-at": "2026-03-30T18:05:56.331Z", "responses": { "200": { "description": "Successfully retrieved the list of documents accessible to the user based on their Passport credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "path": { "type": "string" }, "classification": { "type": "string" }, "governanceTier": { "type": "string" } }, "required": [ "id", "title", "path", "classification", "governanceTier" ] } } } }, "examples": { "successful_document_retrieval": { "summary": "Successful document retrieval", "description": "A list of documents accessible to the user with 'Internal' classification.", "value": { "documents": [ { "id": "doc-123", "title": "Acme Invoices Q3", "path": "/documents/acme-invoices-q3", "classification": "Internal", "governanceTier": "Tier 2" }, { "id": "doc-456", "title": "Project Apollo Overview", "path": "/documents/project-apollo-overview", "classification": "Internal", "governanceTier": "Tier 1" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "The request lacks proper delegation credentials.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "500": { "description": "Internal server error while loading the knowledge base.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "knowledge_base_load_failure": { "summary": "Knowledge base load failure", "description": "An unexpected error occurred while accessing the knowledge base.", "value": { "type": "https://api.haio.run/errors/internal", "title": "KB Error", "status": 500, "detail": "KB load failed" } } } } } } } } }, "/v1/kb/sync": { "post": { "summary": "Synchronize Knowledge Base Index", "description": "Refresh your knowledge base index with a single request. This endpoint ensures that your knowledge base is current and ready to provide the most accurate information when called upon. Ideal for organizations seeking to maintain an up-to-date repository of knowledge.", "operationId": "syncKbIndex", "tags": [ "KnowledgeBase", "Synchronization" ], "x-code-hash": "85a4a0a688f7a880", "x-generated-at": "2026-03-30T18:06:11.778Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation": { "type": "object", "properties": { "from": { "type": "string" }, "onBehalfOf": { "type": "string" } }, "required": [ "from" ] } } }, "examples": { "sync_request_example": { "summary": "Sync Request Example", "description": "A request to synchronize the knowledge base index from an authorized user.", "value": { "delegation": { "from": "agent123", "onBehalfOf": "org456" } } } } } } }, "responses": { "200": { "description": "The knowledge base index was successfully synchronized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "synced_at": { "type": "string", "format": "date-time" }, "message": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "ok": true, "synced_at": "2023-10-05T14:48:00.000Z", "message": "KB index refreshed on next request (filesystem-backed)" } } } } } }, "400": { "description": "Bad request due to malformed syntax or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "Invalid parameters provided.", "errors": [ "Invalid delegation format." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Forbidden access when the user lacks proper permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Insufficient permissions to sync knowledge base." } } } } } }, "404": { "description": "Resource not found, indicating the knowledge base does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Knowledge base not found." } } } } } }, "500": { "description": "Internal server error due to unforeseen issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during synchronization." } } } } } } } } }, "/v1/speech/transcribe": { "post": { "summary": "Transcribe audio into text with AI", "description": "Effortlessly convert spoken words into written text through our advanced AI-driven transcription service. Perfect for capturing meeting notes, interviews, or any spoken content, ensuring every word is accounted for with precision and efficiency.", "operationId": "postSpeechTranscribe", "tags": [ "Speech", "Transcription" ], "x-code-hash": "9f700609284624fc", "x-generated-at": "2026-03-30T18:37:51.805Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audio": { "type": "string", "format": "binary", "description": "Audio file to be transcribed, in WebM format" }, "language": { "type": "string", "description": "Optional language code for transcription" } }, "required": [ "audio" ] }, "examples": { "webm_audio_transcription": { "summary": "WebM Audio Transcription", "description": "Transcribe a WebM audio file in English", "value": { "audio": "", "language": "en" } } } } } }, "responses": { "200": { "description": "Successfully transcribed audio into text", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Transcribed text of the audio" }, "language": { "type": "string", "description": "Language of the transcribed text" }, "duration_ms": { "type": "integer", "description": "Duration of the audio in milliseconds" }, "cost": { "type": "object", "properties": { "usd": { "type": "number", "description": "Cost of the transcription in USD" } } } } }, "examples": { "successful_transcription": { "summary": "Successful Transcription", "description": "Transcription of a meeting recording", "value": { "text": "Welcome to the quarterly financial meeting...", "language": "en", "duration_ms": 45000, "cost": { "usd": 0 } } } } } } }, "400": { "description": "Invalid request format or missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_audio_file": { "summary": "Missing Audio File", "description": "The request did not include the required audio file.", "value": { "type": "https://api.haio.run/errors/validation", "title": "Bad Request", "status": 400, "detail": "Missing audio file field" } } } } } }, "401": { "description": "Authentication is required to access this endpoint", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The user is not authenticated.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "500": { "description": "Internal server error during transcription", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "transcription_service_error": { "summary": "Transcription Service Error", "description": "The transcription service encountered an error.", "value": { "type": "https://api.haio.run/errors/internal", "title": "Transcription Failed", "status": 502, "detail": "Transcription failed due to an unknown error" } } } } } } } } }, "/v1/speech/synthesize": { "post": { "summary": "Synthesize text into spoken audio", "description": "Transform written text into lifelike spoken audio, bridging communication gaps effortlessly. This endpoint empowers applications to produce voice output, enhancing accessibility and user interaction by converting text into speech.", "operationId": "postSpeechSynthesize", "tags": [ "Speech", "Synthesis" ], "x-code-hash": "5a2f871f05ea602d", "x-generated-at": "2026-03-30T18:38:03.548Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content to be synthesized into speech." }, "voice_id": { "type": "string", "description": "Identifier for the voice to use. Defaults to 'alloy'." }, "format": { "type": "string", "enum": [ "mp3", "wav" ], "description": "Audio format for the output. Defaults to 'mp3'." } }, "required": [ "text" ] }, "examples": { "basic_text_synthesis": { "summary": "Basic Text Synthesis", "description": "Convert a simple text string into speech using default settings.", "value": { "text": "Hello, world!", "voice_id": "alloy", "format": "mp3" } } } } } }, "responses": { "200": { "description": "The audio content synthesized from the provided text.", "content": { "application/json": { "schema": { "type": "string", "format": "binary", "description": "Binary audio data representing the synthesized speech." }, "examples": { "default": { "summary": "Example", "description": "MP3 audio of 'Hello, world!'", "value": "" } } } } }, "400": { "description": "Bad Request due to missing or invalid input parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Missing text parameter", "value": { "type": "https://api.haio.run/errors/validation", "title": "Validation Error", "status": 400, "detail": "text is required" } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Missing Passport for authentication", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "500": { "description": "Internal server error due to misconfiguration or other issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "General synthesis failure", "value": { "type": "https://api.haio.run/errors/internal", "title": "Synthesis Failed", "status": 502, "detail": "Synthesis failed due to unexpected error." } } } } } } } } }, "/v1/signals/sources": { "post": { "summary": "Register a new signal source", "description": "Integrate a new source of data into your organization's HUMAN protocol. This endpoint allows you to specify a data source that will be tracked and analyzed for insights, helping you leverage diverse information streams efficiently.", "operationId": "postSignalsSources", "tags": [ "Data Integration", "Signal Management" ], "x-code-hash": "bec3f47f0bbaf15e", "x-generated-at": "2026-03-30T18:22:36.052Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string", "description": "The human-readable name of the signal source." }, "kind": { "type": "string", "enum": [ "website", "api", "rss", "github", "social", "upload", "custom" ], "description": "The category defining the type of signal source." }, "config": { "type": "object", "additionalProperties": true, "description": "Optional configuration settings specific to the signal source." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active", "description": "The initial status of the signal source." } } }, "examples": { "basic_signal_source": { "summary": "Basic Signal Source", "description": "Create a signal source with minimal required fields.", "value": { "name": "Acme Corp GitHub", "kind": "github", "config": { "repo": "acme/repo-name" }, "status": "active" } } } } } }, "responses": { "201": { "description": "Signal source successfully created with details of the new source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "description": "Unique identifier for the newly created signal source." }, "org_did": { "type": "string", "description": "The decentralized identifier for the organization." }, "name": { "type": "string", "description": "Name of the signal source." }, "kind": { "type": "string", "description": "Type of the signal source." }, "config": { "type": "object", "description": "Configuration settings for the signal source." }, "status": { "type": "string", "description": "Current status of the signal source." }, "last_scanned_at": { "type": [ "string", "null" ], "description": "Timestamp of the last scan, null if never scanned." }, "created_at": { "type": "string", "description": "Timestamp of when the signal source was created." }, "updated_at": { "type": "string", "description": "Timestamp of the last update to the signal source." } } }, "examples": { "default": { "summary": "Example", "value": { "source_id": "sig_src_12345", "org_did": "did:example:acme", "name": "Acme Corp GitHub", "kind": "github", "config": { "repo": "acme/repo-name" }, "status": "active", "last_scanned_at": null, "created_at": "2023-10-25T14:48:00Z", "updated_at": "2023-10-25T14:48:00Z" } } } } } }, "400": { "description": "Bad Request due to invalid input data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/validation-error", "title": "Invalid Request Body", "status": 400, "detail": "The request body contains invalid data.", "errors": [ { "field": "name", "code": "REQUIRED_FIELD_MISSING", "message": "name is required", "expected": "string", "received": "missing" } ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access this resource. Ensure your request includes valid authentication credentials." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/permission-error", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to create a signal source. Contact your administrator to obtain the necessary rights." } } } } } }, "404": { "description": "Not Found if the specified resource does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found. Verify the endpoint or resource identifier." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the problem persists." } } } } } } } }, "get": { "summary": "Retrieve paginated signal sources", "description": "Delve into the intricate network of signal sources within your organization. This endpoint is your gateway to exploring the multitude of data origins, empowering you with the oversight of source management and performance at scale. Discover the orchestration behind signal acquisition and make informed decisions based on real-time data.", "operationId": "getSignalsSources", "tags": [ "Signals", "Sources" ], "x-code-hash": "a89750f4b7e2ac36", "x-generated-at": "2026-03-30T18:22:52.553Z", "responses": { "200": { "description": "A successful retrieval of signal sources, complete with pagination details to navigate large datasets effortlessly.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "type": "string" }, "org_did": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "config": { "type": "object" }, "status": { "type": "string" }, "last_scanned_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "source_id", "org_did", "name", "kind", "created_at", "updated_at" ] } }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "hasMore", "limit", "cursorFields" ] }, "examples": { "acmeorgsignalsources": { "summary": "acmeOrgSignalSources", "description": "An example of signal sources for the 'acme' organization, illustrating pagination and source attributes.", "value": { "data": [ { "source_id": "src-001", "org_did": "did:human:org-acme", "name": "Invoice Processing", "kind": "financial", "config": { "currency": "USD" }, "status": "active", "last_scanned_at": "2023-09-25T15:00:00Z", "created_at": "2023-04-10T12:00:00Z", "updated_at": "2023-09-20T10:15:00Z" } ], "hasMore": false, "limit": 10, "cursorFields": [ "created_at", "source_id" ] } } } } } }, "400": { "description": "The request is malformed, possibly due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalidqueryparam": { "summary": "invalidQueryParam", "description": "Example of a 400 error due to invalid query parameters.", "value": { "type": "https://api.humanprotocol.org/errors/invalid-query", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'limit' query parameter must be a positive integer.", "errors": [ "limit must be a positive integer" ] } } } } } }, "401": { "description": "Authentication is required to access the resources.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authenticationerror": { "summary": "authenticationError", "description": "Example of a 401 error when no delegation is provided.", "value": { "type": "https://api.humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please ensure your request includes valid credentials." } } } } } }, "403": { "description": "The request is understood, but the server refuses to authorize it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbiddenaccess": { "summary": "forbiddenAccess", "description": "Example of a 403 error due to insufficient permissions.", "value": { "type": "https://api.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Check your access rights or contact the administrator." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resourcenotfound": { "summary": "resourceNotFound", "description": "Example of a 404 error when the signal source does not exist.", "value": { "type": "https://api.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The signal source you are looking for does not exist. Please verify the source ID." } } } } } }, "500": { "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internalservererror": { "summary": "internalServerError", "description": "Example of a 500 error due to an internal server issue.", "value": { "type": "https://api.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try your request again later." } } } } } } } } }, "/v1/signals/sources/:source_id": { "get": { "summary": "Retrieve details of a signal source", "description": "Dive into the depths of your organization's data with this endpoint, which uncovers the specific characteristics of a signal source within your organization. By securely querying this resource, you gain insights into the configurations and statuses that define your data streams, empowering data-driven decisions.", "operationId": "getSignalSourceDetails", "tags": [ "Signals", "DataManagement" ], "x-code-hash": "24a7886e4e72f36e", "x-generated-at": "2026-03-30T18:23:10.761Z", "responses": { "200": { "description": "Successfully retrieves the details of the specified signal source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "example": "source_123" }, "org_did": { "type": "string", "example": "did:example:acme" }, "name": { "type": "string", "example": "Acme Data Stream" }, "kind": { "type": "string", "example": "stream" }, "config": { "type": "object", "example": { "endpoint": "https://api.acme.com/data" } }, "status": { "type": "string", "example": "active" }, "last_scanned_at": { "type": "string", "format": "date-time", "example": "2023-09-15T13:45:30Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2023-09-14T12:34:56Z" } } }, "examples": { "example_response_for_signal_source": { "summary": "Example Response for Signal Source", "description": "Details of a signal source used by Acme organization for data streaming.", "value": { "source_id": "source_123", "org_did": "did:example:acme", "name": "Acme Data Stream", "kind": "stream", "config": { "endpoint": "https://api.acme.com/data" }, "status": "active", "last_scanned_at": "2023-09-15T13:45:30Z", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-09-14T12:34:56Z" } } } } } }, "400": { "description": "Bad Request - The request could not be understood or was missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_source_id_example": { "summary": "Malformed Source ID Example", "description": "The source_id was not properly formatted, resulting in a 400 error.", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided source_id format is incorrect." } } } } } }, "401": { "description": "Unauthorized - Authentication is required and has failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_example": { "summary": "Missing Authentication Example", "description": "The request was made without proper authentication, resulting in a 401 error.", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please authenticate and try again." } } } } } }, "403": { "description": "Forbidden - The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "The user lacks the necessary permissions to access the signal source.", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The specified signal source does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "nonexistent_source_example": { "summary": "Nonexistent Source Example", "description": "The requested source_id does not match any existing records, resulting in a 404 error.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Source not found. Please check the source_id and try again." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error_example": { "summary": "Unexpected Error Example", "description": "A server-side error caused the request to fail, resulting in a 500 error.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "patch": { "summary": "Update Signal Source Details", "description": "Modify the attributes of an existing signal source to keep your data orchestration precise and up-to-date. With HUMAN's capability graph, track and manage your signal sources efficiently, ensuring seamless integration in your AI workflows.", "operationId": "updateSignalSource", "tags": [ "Signal Management", "Data Orchestration" ], "x-code-hash": "935b8b44baf4a27a", "x-generated-at": "2026-03-30T18:23:34.161Z", "responses": { "200": { "description": "The signal source was successfully updated.", "content": { "application/json": {} } }, "400": { "description": "The request could not be processed due to invalid input data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication failed; delegation is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Permission denied for updating this signal source.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified signal source was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "summary": "Remove a signal source by ID", "description": "In the orchestration of human and AI tasks, sometimes certain data sources become obsolete or redundant. This endpoint empowers organizations to manage their signal sources dynamically, ensuring that only relevant data feeds into their Human-AI orchestration processes.", "operationId": "deleteSignalSource", "tags": [ "Signal Management", "Data Sources" ], "x-code-hash": "adbbb1bc4e81c0f7", "x-generated-at": "2026-03-30T18:23:48.127Z", "responses": { "204": { "description": "The signal source was successfully deleted, no content returned.", "content": { "application/json": {} } }, "400": { "description": "The request was malformed. Check the source ID format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_source_id": { "summary": "Invalid Source ID", "description": "The source ID format was incorrect.", "value": { "type": "https://docs.humanapi.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided source ID is not valid." } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_access": { "summary": "Unauthenticated Access", "description": "The user attempted to delete a source without being authenticated.", "value": { "type": "https://docs.humanapi.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please authenticate your request." } } } } } }, "403": { "description": "The authenticated user does not have permission to delete this source.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user lacks the necessary permissions to delete the source.", "value": { "type": "https://docs.humanapi.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to delete this signal source." } } } } } }, "404": { "description": "No signal source found with the provided ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "source_not_found": { "summary": "Source Not Found", "description": "The specified source ID does not correspond to any existing source.", "value": { "type": "https://docs.humanapi.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The signal source with the specified ID does not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "A generic server error occurred, which might be transient.", "value": { "type": "https://docs.humanapi.com/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/signals/watchlists": { "post": { "summary": "Create a new watchlist for signals", "description": "In the dynamic realm of signal monitoring, orchestrate your focus by creating watchlists tailored to organizational needs. This endpoint empowers users to define and manage collections of signals, ensuring strategic oversight and prompt action.", "operationId": "createSignalWatchlist", "tags": [ "Signals", "Watchlists" ], "x-code-hash": "653e4f2ee7777eb7", "x-generated-at": "2026-03-30T18:24:09.187Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A unique name for the watchlist." }, "description": { "type": "string", "description": "Optional description of the watchlist." }, "owner_ref": { "type": "string", "description": "Reference to the owner, defaults to requesting user's delegation ID." }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "default": "active", "description": "The operational status of the watchlist." }, "config": { "type": "object", "additionalProperties": true, "description": "Configuration settings for the watchlist." } }, "required": [ "name" ] }, "examples": { "creating_a_basic_watchlist": { "summary": "Creating a basic watchlist", "description": "This example demonstrates creating a simple active watchlist with default owner.", "value": { "name": "High Priority Alerts", "description": "Monitor high priority signals for immediate action.", "status": "active", "config": { "threshold": 5 } } } } } } }, "responses": { "201": { "description": "Watchlist successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "watchlist_id": { "type": "string", "description": "The unique identifier for the created watchlist." }, "org_did": { "type": "string", "description": "The DID of the organization owning the watchlist." }, "name": { "type": "string", "description": "The name of the created watchlist." }, "description": { "type": "string", "nullable": true, "description": "The description of the created watchlist." }, "owner_ref": { "type": "string", "description": "The reference to the owner of the watchlist." }, "status": { "type": "string", "description": "The status of the created watchlist." }, "config": { "type": "object", "description": "The configuration of the created watchlist." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the watchlist was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the watchlist was last updated." } } }, "examples": { "default": { "summary": "Example", "value": { "watchlist_id": "sig_wl_123456", "org_did": "did:example:acme", "name": "High Priority Alerts", "description": "Monitor high priority signals for immediate action.", "owner_ref": "agent_007", "status": "active", "config": { "threshold": 5 }, "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication required, delegation needed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication", "title": "Delegation required", "status": 401, "detail": "You must provide a valid delegation to access this resource." } } } } } }, "403": { "description": "Permission denied due to lack of access rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/permission-denied", "title": "Access Denied", "status": 403, "detail": "You do not have permission to create a watchlist." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The specified resource could not be found." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve organization's watchlists", "description": "Explore the curated watchlists within your organization, offering insights into tracked signals and configurations. This endpoint empowers organizations to efficiently manage and review their signal monitoring setups, ensuring timely and precise oversight.", "operationId": "getSignalsWatchlists", "tags": [ "Signals", "Watchlists" ], "x-code-hash": "5a67f7a179622b4d", "x-generated-at": "2026-03-30T18:24:26.497Z", "responses": { "200": { "description": "Successful retrieval of watchlists for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "watchlist_id": { "type": "string" }, "org_did": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner_ref": { "type": "string" }, "status": { "type": "string" }, "config": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "watchlist_id", "org_did", "name", "status", "created_at" ] } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorFields", "hasMore" ] }, "examples": { "acme_corp_watchlists": { "summary": "Acme Corp Watchlists", "description": "Retrieve Acme Corp's active watchlists for monitoring signals.", "value": { "data": [ { "watchlist_id": "wl-123", "org_did": "did:example:acme", "name": "High Priority Alerts", "description": "Monitoring critical system alerts", "owner_ref": "agent:john.doe", "status": "active", "config": { "sensitivity": "high" }, "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-10T12:00:00Z" } ], "limit": 10, "cursorFields": [ "created_at", "watchlist_id" ], "hasMore": false } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination": { "summary": "Invalid Pagination", "description": "Occurs when pagination parameters are incorrect.", "value": { "type": "https://example.com/probs/invalid-pagination", "title": "Invalid Pagination Parameters", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ "limit must be greater than 0" ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "Occurs when no authentication is provided.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please provide valid credentials." } } } } } }, "403": { "description": "Permission error indicating lack of access rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "User does not have access to the requested resource.", "value": { "type": "https://example.com/probs/access-denied", "title": "Access Denied", "status": 403, "detail": "You do not have permission to access this organization's watchlists." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "watchlist_not_found": { "summary": "Watchlist Not Found", "description": "The specified watchlist could not be located.", "value": { "type": "https://example.com/probs/watchlist-not-found", "title": "Watchlist Not Found", "status": 404, "detail": "The requested watchlist does not exist in this organization's records." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "Unexpected error during processing.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/signals/watchlists/:watchlist_id": { "get": { "summary": "Retrieve details of a specific watchlist", "description": "This endpoint allows organizations to retrieve comprehensive details of a specific watchlist they own or manage. It empowers users to access critical information such as configuration and status, supporting data-driven decision-making and proactive monitoring.", "operationId": "getWatchlistDetails", "tags": [ "Watchlists", "Signals" ], "x-code-hash": "0be9ef091211a050", "x-generated-at": "2026-03-30T18:24:39.084Z", "responses": { "200": { "description": "Successfully retrieved the watchlist details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "watchlist_id": { "type": "string" }, "org_did": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner_ref": { "type": "string" }, "status": { "type": "string" }, "config": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "source_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "watchlist_id", "org_did", "name", "status", "created_at" ] }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "description": "Details of the 'Acme Corp Threat Watchlist'.", "value": { "watchlist_id": "wl-12345", "org_did": "did:org:acme", "name": "Threat Watchlist", "description": "Monitors potential threats to Acme Corp.", "owner_ref": "agent:john.doe", "status": "active", "config": { "sensitivity": "high", "region": "global" }, "created_at": "2023-09-15T08:30:00Z", "updated_at": "2023-10-01T12:00:00Z", "source_ids": [ "src-67890", "src-54321" ] } } } } } }, "401": { "description": "Authentication failure due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "When the request lacks proper delegation.", "value": { "type": "https://humanprotocol.org/error/authentication", "title": "Authentication Error", "status": 401, "detail": "Delegation required. Ensure the correct organization delegation is provided in the request." } } } } } }, "404": { "description": "The specified watchlist could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "watchlist_not_found": { "summary": "Watchlist Not Found", "description": "Occurs when the requested watchlist ID is invalid or does not belong to the organization.", "value": { "type": "https://humanprotocol.org/error/not-found", "title": "Resource Not Found", "status": 404, "detail": "Watchlist not found. Verify the watchlist ID and ensure it belongs to your organization." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "General server error, indicating something went wrong internally.", "value": { "type": "https://humanprotocol.org/error/internal-server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } }, "patch": { "summary": "Update an existing watchlist entry", "description": "In the ever-evolving world of AI-human collaboration, keeping track of signals is crucial. This endpoint allows you to update the details of a watchlist, ensuring your team stays informed and agile. Whether it's a name change or a status update, this operation ensures your watchlists reflect the latest intelligence.", "operationId": "patchSignalsWatchlist", "tags": [ "Signals", "Watchlists" ], "x-code-hash": "7e88a1e2006dbdb5", "x-generated-at": "2026-03-30T18:24:54.829Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the watchlist." }, "description": { "type": "string", "description": "A brief description of the watchlist." }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ], "description": "The operational status of the watchlist." }, "config": { "type": "object", "description": "Configuration settings for the watchlist." } }, "required": [] }, "examples": { "update_watchlist_name": { "summary": "Update Watchlist Name", "description": "This example demonstrates updating the name and status of a watchlist.", "value": { "name": "High Priority Signals", "status": "active" } } } } } }, "responses": { "200": { "description": "The watchlist was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "watchlist_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner_ref": { "type": "string" }, "status": { "type": "string" }, "config": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "high_priority_signals": { "summary": "High Priority Signals", "description": "Key signals for top-tier clients." } } } } }, "400": { "description": "The request body is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/docs/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/docs/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access this resource." } } } } } }, "403": { "description": "You do not have permission to modify this watchlist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/docs/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to modify this watchlist." } } } } } }, "404": { "description": "The specified watchlist was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/docs/errors/not-found", "title": "Not Found", "status": 404, "detail": "Watchlist not found." } } } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/docs/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "summary": "Remove a watchlist from signals", "description": "Effortlessly manage your signal monitoring by removing watchlists no longer needed, ensuring your human-AI orchestration remains efficient and focused. This endpoint allows organizations to delete outdated or irrelevant watchlists, keeping their signal tracking streamlined.", "operationId": "deleteSignalsWatchlist", "tags": [ "Signals", "Watchlists" ], "x-code-hash": "c12073c5e4b7c055", "x-generated-at": "2026-03-30T18:25:26.302Z", "responses": { "204": { "description": "Successfully deleted the specified watchlist. The absence of content confirms the operation was completed without a hitch.", "content": { "application/json": { "examples": { "successful_deletion": { "summary": "Successful Deletion", "description": "Confirmation of watchlist removal.", "value": null } } } } }, "400": { "description": "The request was malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_example": { "summary": "Malformed Request Example", "description": "A case where the request parameters were incorrect.", "value": { "type": "https://api.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters are improperly formatted. Ensure watchlist_id is a valid UUID." } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "User attempted an action without being authenticated.", "value": { "type": "https://api.humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must authenticate to delete a watchlist. Please provide valid credentials." } } } } } }, "403": { "description": "The client does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "User lacks necessary permissions to delete the watchlist.", "value": { "type": "https://api.humanprotocol.org/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have the required permissions to delete this watchlist. Contact your admin for access." } } } } } }, "404": { "description": "The specified watchlist was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "watchlist_not_found": { "summary": "Watchlist Not Found", "description": "An attempt to delete a non-existent watchlist.", "value": { "type": "https://api.humanprotocol.org/errors/watchlist-not-found", "title": "Watchlist Not Found", "status": 404, "detail": "The watchlist with the specified ID does not exist. Please verify the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected condition was encountered.", "value": { "type": "https://api.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/signals/watchlists/:watchlist_id/sources": { "put": { "summary": "Update sources in a watchlist", "description": "This endpoint redefines the sources linked to a specific watchlist, allowing organizations to dynamically adjust their surveillance scope. By managing these sources, businesses can precisely tailor their signal monitoring to stay ahead in their domain.", "operationId": "updateWatchlistSources", "tags": [ "Watchlists", "Signals" ], "x-code-hash": "0fd9c49a33d1307b", "x-generated-at": "2026-03-30T18:25:12.515Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_ids": { "type": "array", "items": { "type": "string" }, "description": "A list of source IDs that the watchlist should monitor." } }, "required": [ "source_ids" ] }, "examples": { "attach_sources_to_a_watchlist": { "summary": "Attach sources to a watchlist", "description": "This example updates a watchlist with multiple sources.", "value": { "source_ids": [ "src123", "src456", "src789" ] } } } } } }, "responses": { "200": { "description": "Successfully updated the watchlist with new sources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "watchlist_id": { "type": "string" }, "org_did": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner_ref": { "type": "string" }, "status": { "type": "string" }, "config": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "attached_sources": { "type": "array", "items": { "type": "string" } } } }, "examples": { "market_trends": { "summary": "Market Trends", "description": "Monitoring key market indicators." } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/validation", "title": "Invalid Request", "status": 400, "detail": "The request body contains invalid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Delegation required to perform this operation. Ensure you have the necessary credentials." } } } } } }, "404": { "description": "The specified watchlist was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Watchlist not found. Verify the watchlist_id and your organization permissions." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/signals/feed": { "get": { "summary": "Retrieve curated signals feed", "description": "Dive into the dynamic world of AI and human collaboration by accessing a curated feed of signals. This endpoint empowers organizations to filter and analyze signals based on watchlists, event types, verdicts, and confidence levels. It exists to provide transparency and actionable insights, ensuring that organizations can make informed decisions swiftly.", "operationId": "getSignalsFeed", "tags": [ "Signals", "Feed" ], "x-code-hash": "8e6166cfacbec497", "x-generated-at": "2026-03-30T18:25:45.654Z", "responses": { "200": { "description": "A successful response returns a list of signals with pagination details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "signal_id": { "type": "string" }, "org_did": { "type": "string" }, "source_id": { "type": "string" }, "watchlist_id": { "type": "string" }, "event_type": { "type": "string" }, "entity_ref": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "confidence": { "type": "number" }, "relevance_score": { "type": "number" }, "verdict": { "type": "string" }, "artifact_ids": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } } }, "examples": { "successful_retrieval_of_signals": { "summary": "Successful retrieval of signals", "description": "An example response showing a list of signals for an organization with pagination.", "value": { "data": [ { "signal_id": "sig1234", "org_did": "did:org:acme", "source_id": "src456", "watchlist_id": "wl789", "event_type": "anomaly_detected", "entity_ref": "entity:ref1", "title": "Unexpected Behavior Detected", "summary": "An unusual spike in network traffic was identified.", "confidence": 0.95, "relevance_score": 0.8, "verdict": "pending", "artifact_ids": [ "art123" ], "metadata": {}, "occurred_at": "2023-10-15T14:48:00Z", "created_at": "2023-10-15T14:50:00Z" } ], "limit": 10, "cursorFields": [ "occurred_at", "signal_id" ], "hasMore": false } } } } } }, "400": { "description": "Invalid request due to parameter errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_verdict_value": { "summary": "Invalid verdict value", "description": "Occurs when an unsupported verdict value is passed.", "value": { "type": "https://docs.human.protocol/errors/invalid-verdict", "title": "Invalid Request", "status": 400, "detail": "One or more fields have an error.", "errors": [ { "field": "verdict", "code": "INVALID_VALUE", "message": "verdict filter must be pending | approved | suppressed | routed", "expected": "enum", "received": "wrong_value" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "description": "Occurs when no organization DID is provided.", "value": { "type": "https://docs.human.protocol/errors/authentication-required", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Ensure that your request includes valid credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "description": "Occurs when the user does not have permission to access the resource.", "value": { "type": "https://docs.human.protocol/errors/access-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Contact your administrator or check your access level." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "signal_not_found": { "summary": "Signal not found", "description": "Occurs when a specific signal or resource is not found.", "value": { "type": "https://docs.human.protocol/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested signal or resource could not be found. Check the identifiers provided." } } } } } }, "500": { "description": "Internal server error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "description": "Occurs due to an internal server issue.", "value": { "type": "https://docs.human.protocol/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected condition was encountered. Please try again later or contact support if the issue persists." } } } } } } } }, "post": { "summary": "Create a new signal feed entry", "description": "The POST /v1/signals/feed endpoint allows organizations to manually ingest new signals into the HUMAN platform. By crafting a feed entry, organizations can showcase their capabilities, demonstrate prowess, and ensure their skills are recognized in the HUMAN ecosystem.", "operationId": "postSignalsFeed", "tags": [ "Signals", "Feed" ], "x-code-hash": "61e9bc5df8f50963", "x-generated-at": "2026-03-30T18:38:16.746Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the signal." }, "description": { "type": "string", "description": "Detailed description of the signal." }, "timestamp": { "type": "string", "format": "date-time", "description": "The time at which the signal was generated." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags categorizing the signal." } }, "required": [ "title", "description", "timestamp" ] }, "examples": { "sample_signal_ingestion": { "summary": "Sample Signal Ingestion", "description": "This example demonstrates how an organization might submit a signal for an AI capability demonstration.", "value": { "title": "AI Capability Demonstration", "description": "A demonstration of AI capabilities integrating HUMAN Passport and Capability Graph.", "timestamp": "2023-09-15T14:30:00Z", "tags": [ "AI", "demo", "capability" ] } } } } } }, "responses": { "201": { "description": "Signal feed entry created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the created feed entry." }, "status": { "type": "string", "description": "Status of the feed entry creation." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request - Invalid JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "body", "message": "Request body must be valid JSON" } ] } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please provide valid authentication credentials." } } } } } }, "500": { "description": "Internal Server Error - Unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/signals/feed/:signal_id": { "get": { "summary": "Retrieve signal details from feed", "description": "Delve into the heartbeat of your organization by fetching detailed insights from the signal feed. This endpoint allows you to track pivotal events and analyze their importance for strategic decision-making, ensuring every action is informed by data-driven intelligence.", "operationId": "getSignalFeedById", "tags": [ "Signals", "Feed" ], "x-code-hash": "bbe32e06790045d6", "x-generated-at": "2026-03-30T18:26:26.413Z", "responses": { "200": { "description": "Successfully retrieved signal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "signal_id": { "type": "string" }, "org_did": { "type": "string" }, "source_id": { "type": "string" }, "watchlist_id": { "type": "string" }, "event_type": { "type": "string" }, "entity_ref": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "confidence": { "type": "number" }, "relevance_score": { "type": "number" }, "verdict": { "type": "string" }, "artifact_ids": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "successful_signal_retrieval": { "summary": "Successful Signal Retrieval", "value": { "signal_id": "12345", "org_did": "did:example:org123", "source_id": "source789", "watchlist_id": "watchlist456", "event_type": "anomaly_detected", "entity_ref": "entity:acme:invoice:67890", "title": "Unexpected Invoice Surge", "summary": "A sudden increase in invoice submissions was detected.", "confidence": 0.92, "relevance_score": 0.85, "verdict": "review_required", "artifact_ids": [ "artifact001", "artifact002" ], "metadata": {}, "occurred_at": "2023-10-15T14:48:00Z", "created_at": "2023-10-15T15:00:00Z" } } } } } }, "400": { "description": "Bad Request due to invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_signal_id": { "summary": "Invalid Signal ID", "value": { "type": "https://example.com/problem/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "The signal_id parameter is malformed.", "errors": [] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://example.com/problem/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Ensure your request includes valid authentication credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://example.com/problem/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this signal. Check your access rights." } } } } } }, "404": { "description": "Signal not found for the given ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "signal_not_found": { "summary": "Signal Not Found", "value": { "type": "https://example.com/problem/not-found", "title": "Signal Not Found", "status": 404, "detail": "The requested signal was not found. Verify the signal ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/problem/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/signals/feed/:signal_id/route": { "post": { "summary": "Route and Update Signal Verdict", "description": "This endpoint empowers organizations to dynamically update the verdict of a signal and adjust its routing metadata. It serves as a crucial touchpoint for ensuring signals are processed accurately and efficiently within the HUMAN Protocol, reflecting real-time decision-making and task management.", "operationId": "updateSignalRoute", "tags": [ "Signal Management", "Routing" ], "x-code-hash": "16fa71f267929834", "x-generated-at": "2026-03-30T18:26:46.472Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verdict": { "type": "string", "description": "The new verdict for the signal.", "enum": [ "pending", "approved", "suppressed", "routed" ] }, "route_action": { "type": "string", "description": "Action taken for routing the signal." }, "metadata_patch": { "type": "object", "description": "Partial metadata update for the signal." } }, "required": [] }, "examples": { "update_signal_verdict_and_route": { "summary": "Update Signal Verdict and Route", "description": "Example showing how to approve a signal and set a route action.", "value": { "verdict": "approved", "route_action": "escalate", "metadata_patch": { "priority": "high", "reviewed_by": "john.doe@example.com" } } } } } } }, "responses": { "200": { "description": "The signal's verdict and metadata have been successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "signal_id": { "type": "string" }, "org_did": { "type": "string" }, "source_id": { "type": "string" }, "watchlist_id": { "type": "string" }, "event_type": { "type": "string" }, "entity_ref": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "confidence": { "type": "number" }, "relevance_score": { "type": "number" }, "verdict": { "type": "string" }, "artifact_ids": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-json", "title": "Invalid JSON Format", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please ensure your credentials are valid and included in the request." } } } } } }, "403": { "description": "Permission error due to lack of required access rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/permission-error", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to update this signal. Check your access rights and try again." } } } } } }, "404": { "description": "Signal not found error when the specified signal does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Signal Not Found", "status": 404, "detail": "The specified signal was not found. Verify the signal ID and organization DID." } } } } } }, "500": { "description": "Server error indicating an unexpected issue on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/signals/feed/:signal_id/feedback": { "post": { "summary": "Submit feedback for a signal event", "description": "In the intricate dance of human and AI collaboration, feedback serves as the guiding hand. This endpoint allows organizations to provide nuanced feedback on specific signals, ensuring that AI-driven processes remain aligned with human intent. Whether acknowledging high impact or flagging misclassifications, this feedback loop enhances the orchestration of tasks.", "operationId": "submitSignalFeedback", "tags": [ "Signals", "Feedback" ], "x-code-hash": "2bc590fd13485951", "x-generated-at": "2026-03-30T18:27:04.601Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flag", "dismiss", "watch", "not_useful", "misclassified", "high_impact", "route_differently" ], "description": "The type of feedback being provided" }, "note": { "type": "string", "description": "Optional note elaborating on the feedback, up to 4000 characters" }, "scope": { "type": "string", "description": "The scope of feedback, defaulting to 'org' if not specified" } }, "required": [ "kind" ] }, "examples": { "feedback_on_signal_misclassification": { "summary": "Feedback on signal misclassification", "description": "This example illustrates submitting feedback when a signal is misclassified.", "value": { "kind": "misclassified", "note": "The signal was incorrectly categorized under 'urgent'.", "scope": "project" } } } } } }, "responses": { "201": { "description": "Feedback successfully submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback_event_id": { "type": "string", "description": "Unique identifier for the feedback event" }, "org_did": { "type": "string", "description": "Decentralized identifier of the organization" }, "signal_id": { "type": "string", "description": "Identifier of the signal feedback was submitted for" }, "kind": { "type": "string", "description": "The type of feedback that was submitted" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when feedback was created" } } }, "examples": { "default": { "summary": "Example", "value": { "feedback_event_id": "fdbk12345", "org_did": "did:example:acme", "signal_id": "sig7890", "kind": "misclassified", "created_at": "2023-10-15T14:23:00Z" } } } } } }, "400": { "description": "Invalid request body or parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body must be valid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Ensure your credentials are correct and try again." } } } } } }, "403": { "description": "Permission denied for accessing the signal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/permission-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to provide feedback on this signal. Check your access rights." } } } } } }, "404": { "description": "Signal not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/signal-not-found", "title": "Not Found", "status": 404, "detail": "The signal you are trying to provide feedback for does not exist. Verify the signal ID." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/webhooks/subscriptions/:subscriptionId/deliveries": { "get": { "summary": "Retrieve webhook delivery history", "description": "This endpoint unveils the rich tapestry of webhook deliveries for a specific subscription, providing insight into the lifecycle and status of each delivery attempt. Whether you're troubleshooting a missing event or analyzing delivery performance, this endpoint offers a transparent view into your webhook ecosystem.", "operationId": "getWebhookDeliveries", "tags": [ "Webhooks", "Subscriptions" ], "x-code-hash": "ce15d357c30acc40", "x-generated-at": "2026-03-31T01:30:23.551Z", "responses": { "200": { "description": "A list of webhook deliveries for the specified subscription, with pagination support.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "subscription_id": { "type": "string" }, "event_id": { "type": "string" }, "status": { "type": "string" }, "target_url": { "type": "string" }, "attempt_count": { "type": "integer" }, "max_attempts": { "type": "integer" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "last_http_status": { "type": "integer" }, "last_response_body": { "type": "string" }, "last_error": { "type": "string" }, "last_attempted_at": { "type": "string", "format": "date-time" }, "idempotency_key": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursor": { "type": "string" }, "hasMore": { "type": "boolean" }, "queue_summary": { "type": "object", "properties": { "pending": { "type": "integer" }, "delivering": { "type": "integer" }, "failed_retrying": { "type": "integer" }, "dead": { "type": "integer" }, "delivered": { "type": "integer" } } } } }, "examples": { "successful_retrieval_of_webhook_deliveries": { "summary": "Successful retrieval of webhook deliveries", "description": "Retrieve deliveries for subscription 'sub_1234' with a comprehensive view of each delivery's status.", "value": { "data": [ { "delivery_id": "del_001", "subscription_id": "sub_1234", "event_id": "evt_5678", "status": "delivered", "target_url": "https://webhook.acme.com/event", "attempt_count": 3, "max_attempts": 5, "next_attempt_at": null, "last_http_status": 200, "last_response_body": "Success", "last_error": null, "last_attempted_at": "2023-10-01T12:00:00Z", "idempotency_key": "idem_8765", "created_at": "2023-09-30T10:00:00Z", "updated_at": "2023-10-01T12:00:00Z" } ], "limit": 10, "cursor": "opaque_cursor_string", "hasMore": false, "queue_summary": { "pending": 0, "delivering": 1, "failed_retrying": 0, "dead": 0, "delivered": 99 } } } } } } }, "400": { "description": "Validation errors due to invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified subscription could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/webhooks/deliveries/:deliveryId": { "get": { "summary": "Retrieve specific webhook delivery details", "description": "Uncover the story behind your webhook delivery attempts by retrieving detailed information on a specific delivery using its unique ID. This endpoint allows organizations to audit their webhook deliveries, track attempts, and gain insights into potential issues.", "operationId": "getWebhookDeliveryDetails", "tags": [ "Webhooks", "Deliveries" ], "x-code-hash": "f5113b934b148587", "x-generated-at": "2026-03-30T21:43:44.956Z", "responses": { "200": { "description": "Webhook delivery details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryId": { "type": "string", "description": "Unique identifier for the delivery" }, "subscriptionId": { "type": "string", "description": "ID of the subscription related to this delivery" }, "eventId": { "type": "string", "description": "Event ID associated with the delivery" }, "status": { "type": "string", "description": "Current status of the delivery" }, "targetUrl": { "type": "string", "description": "The URL where the webhook was sent" }, "attemptCount": { "type": "integer", "description": "Number of attempts made to deliver the webhook" }, "maxAttempts": { "type": "integer", "description": "Maximum number of attempts allowed" }, "nextAttemptAt": { "type": "string", "format": "date-time", "description": "Time for the next attempt if any" }, "lastHttpStatus": { "type": "integer", "description": "HTTP status code from the last delivery attempt" }, "lastResponseBody": { "type": "string", "description": "Response body from the last delivery attempt" }, "lastError": { "type": "string", "description": "Last error message encountered during delivery" }, "lastAttemptedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the last delivery attempt" }, "idempotencyKey": { "type": "string", "description": "Idempotency key used for safe retries" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp of the delivery record" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last updated timestamp of the delivery record" } }, "required": [ "deliveryId", "subscriptionId", "eventId", "status", "targetUrl", "createdAt" ] }, "examples": { "successful_delivery_retrieval": { "summary": "Successful Delivery Retrieval", "description": "Details of a successful webhook delivery retrieval for organization 'acme'.", "value": { "deliveryId": "del_123456", "subscriptionId": "sub_987654", "eventId": "evt_13579", "status": "delivered", "targetUrl": "https://webhooks.acme.com/events", "attemptCount": 1, "maxAttempts": 3, "nextAttemptAt": null, "lastHttpStatus": 200, "lastResponseBody": "OK", "lastError": null, "lastAttemptedAt": "2023-10-12T14:48:00Z", "idempotencyKey": "idemp_2468", "createdAt": "2023-10-10T09:00:00Z", "updatedAt": "2023-10-12T14:48:00Z" } } } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_delivery_id": { "summary": "Invalid Delivery ID", "description": "The delivery ID 'del_invalid' was provided in an incorrect format.", "value": { "type": "/problems/invalid-parameters", "title": "Invalid request parameters", "status": 400, "detail": "The delivery ID provided is not valid.", "errors": [ { "field": "deliveryId", "message": "Delivery ID must be a valid format." } ] } } } } } }, "401": { "description": "Unauthorized - Org DID required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing Org DID", "description": "No delegation was provided, resulting in unauthorized access.", "value": { "type": "/problems/unauthorized", "title": "Unauthorized access", "status": 401, "detail": "Org DID is required to access this resource." } } } } } }, "404": { "description": "Not Found - Delivery not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "non-existent_delivery": { "summary": "Non-existent Delivery", "description": "Attempted to retrieve a delivery with ID 'del_000000' which does not exist.", "value": { "type": "/problems/not-found", "title": "Resource not found", "status": 404, "detail": "Delivery with the given ID not found." } } } } } }, "500": { "description": "Internal Server Error - Unexpected condition", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A server error occurred when attempting to process the request.", "value": { "type": "/problems/internal-error", "title": "Internal server error", "status": 500, "detail": "An unexpected condition was encountered." } } } } } } } } }, "/v1/webhooks/deliveries/:deliveryId/redeliver": { "post": { "summary": "Retry delivery of failed webhooks", "description": "In the ever-evolving landscape of automated tasks, not everything goes as planned. This endpoint allows you to breathe life back into previously failed or 'dead' webhook deliveries, setting them on the path to success once more. It's a second chance for your integrations to communicate effectively.", "operationId": "redeliverWebhookDelivery", "tags": [ "Webhooks", "Delivery" ], "x-code-hash": "f39e49eb373478a6", "x-generated-at": "2026-03-30T21:44:06.621Z", "responses": { "200": { "description": "The webhook delivery has been successfully queued for redelivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "status": { "type": "string" }, "redelivered_at": { "type": "string", "format": "date-time" } }, "required": [ "delivery_id", "status", "redelivered_at" ] }, "examples": { "successful_redelivery": { "summary": "Successful Redelivery", "description": "Shows a webhook delivery that has been successfully queued for a retry.", "value": { "delivery_id": "123e4567-e89b-12d3-a456-426614174000", "status": "pending", "redelivered_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Bad Request due to missing or invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_did": { "summary": "Missing Org DID", "description": "An attempt to redeliver without a valid Org DID.", "value": { "type": "https://humandao.org/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "Org DID required", "errors": [ { "field": "authorization", "code": "ORG_DID_REQUIRED", "message": "Org DID required", "received": "no delegation" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Occurs when the user does not have valid credentials.", "value": { "type": "https://humandao.org/errors/authentication-failed", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid." } } } } } }, "403": { "description": "Forbidden action due to a lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_action": { "summary": "Forbidden Action", "description": "Occurs when the user attempts an action they do not have permission for.", "value": { "type": "https://humandao.org/errors/permission-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to redeliver this webhook." } } } } } }, "404": { "description": "Not Found error when the specified delivery ID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delivery_not_found": { "summary": "Delivery Not Found", "description": "Occurs when the specified delivery ID cannot be found.", "value": { "type": "https://humandao.org/errors/resource-not-found", "title": "Not Found", "status": 404, "detail": "Delivery 123e4567-e89b-12d3-a456-426614174000 not found." } } } } } }, "409": { "description": "Conflict error when attempting to redeliver a non-failed delivery.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_delivery_state": { "summary": "Invalid Delivery State", "description": "The webhook cannot be redelivered because its current state is not 'failed' or 'dead'.", "value": { "type": "https://humandao.org/errors/webhook-redeliver-invalid-state", "title": "Cannot Redeliver", "status": 409, "detail": "Redelivery is only allowed for failed or dead deliveries. Current status: completed." } } } } } }, "500": { "description": "Internal Server Error for unforeseen issues during processing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A general error occurred on the server.", "value": { "type": "https://humandao.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Failed to queue redelivery due to an unexpected error." } } } } } } } } }, "/v1/telemetry/author-emit": { "post": { "summary": "Emit Tenant-Safe Telemetry Events", "description": "Harness the power of telemetry by securely emitting tenant-specific events into the HUMAN platform's telemetry bus. This endpoint facilitates the tracking of diverse activities within an organization, empowering informed decision-making and AI orchestration.", "operationId": "telemetryAuthorEmit", "tags": [ "Telemetry", "HUMAN Protocol" ], "x-code-hash": "b11f2e164b1d4378", "x-generated-at": "2026-03-30T23:56:40.966Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "The type of event being recorded, e.g., 'invoice_processed'." }, "payload": { "type": "object", "description": "Additional data related to the event, allowing for context-rich telemetry." }, "subject": { "type": "string", "description": "An optional subject identifier related to the event, such as a user ID." }, "idempotency_key": { "type": "string", "description": "A unique key to ensure idempotency of event emission." }, "emitter_agent_did": { "type": "string", "description": "DID of the agent emitting this event. Can be inferred from delegation constraints." } }, "required": [ "event_type", "emitter_agent_did" ] }, "examples": { "emit_invoice_processed_event": { "summary": "Emit Invoice Processed Event", "description": "Example showing a telemetry event for an invoice processing action.", "value": { "event_type": "invoice_processed", "payload": { "invoice_id": "INV-12345", "amount": 1000, "currency": "USD" }, "subject": "user-6789", "idempotency_key": "key-unique-001", "emitter_agent_did": "did:example:agent123" } } } } } }, "responses": { "201": { "description": "Telemetry event successfully emitted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Unique identifier for the recorded telemetry event." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of the event creation." } } }, "examples": { "default": { "summary": "Example", "value": { "event_id": "evt-98765", "created_at": "2023-10-12T07:20:50.52Z" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid JSON format", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "received": "unparseable" } ] } } } } } }, "401": { "description": "Authentication error due to missing delegation context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/authentication-error", "title": "Missing delegation context", "status": 401, "detail": "Missing or invalid delegation context in request." } } } } } }, "403": { "description": "Authorization failure due to invalid organization DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/authorization-error", "title": "Invalid organization DID", "status": 403, "detail": "Delegation must carry a valid organization DID for telemetry author emit." } } } } } }, "500": { "description": "Internal server error when processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } } }, "/v1/control-plane/devices/:deviceId": { "delete": { "summary": "Unenroll device from organization's control plane", "description": "Remove a device from the organization's orchestration network, cascading updates throughout the system. This endpoint ensures that devices no longer required or transferred are securely and thoroughly unenrolled, maintaining system integrity and security.", "operationId": "unenrollDevice", "tags": [ "Device Management", "Control Plane" ], "x-code-hash": "b4804c5396090b76", "x-generated-at": "2026-03-31T00:23:27.606Z", "responses": { "204": { "description": "The device was successfully unenrolled from the control plane.", "content": { "application/json": { "examples": { "successful_unenrollment": { "summary": "Successful Unenrollment", "description": "The device with ID 12345 was successfully unenrolled from the organization with DID acme:org:9876.", "value": null } } } } }, "400": { "description": "Bad request due to missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_deviceid": { "summary": "Missing deviceId", "description": "Example of a request missing the deviceId parameter.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing deviceId", "status": 400, "detail": "deviceId path parameter is required." } }, "missing_orgdid": { "summary": "Missing orgDid", "description": "Example of a request missing the orgDid parameter.", "value": { "type": "https://haio.run/errors/validation", "title": "Missing orgDid", "status": 400, "detail": "orgDid query parameter is required for scoped delete." } } } } } }, "401": { "description": "Unauthorized request due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The request was made without valid authentication credentials.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have permission to unenroll devices.", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permissions to unenroll devices in this organization." } } } } } }, "404": { "description": "Device not found for the specified organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "device_not_found": { "summary": "Device Not Found", "description": "The device with the given ID does not exist within the specified organization.", "value": { "type": "https://haio.run/errors/not-found", "title": "Device Not Found", "status": 404, "detail": "Device '12345' not found for this org." } } } } } }, "500": { "description": "Internal server error encountered during the unenrollment process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected condition was encountered on the server.", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during the unenrollment process. Please try again later." } } } } } } } }, "patch": { "summary": "Update Device Metadata Seamlessly", "description": "Enhance your device management by updating specific metadata properties effortlessly. This endpoint allows organizations to refine device configurations, such as setting or clearing the intent dispatch URL, which is crucial for diagnostic probes. By keeping your device metadata up-to-date, you maintain seamless command plane operations.", "operationId": "updateDeviceMetadata", "tags": [ "ControlPlane", "DeviceManagement" ], "x-code-hash": "ccc610d0fcd0cc98", "x-generated-at": "2026-04-04T18:15:41.370Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "properties": { "intent_dispatch_url": { "type": [ "string", "null" ], "description": "URL for intent dispatch, or null to clear." } }, "required": [ "intent_dispatch_url" ] } }, "required": [ "metadata" ] }, "examples": { "update_intent_dispatch_url": { "summary": "Update Intent Dispatch URL", "description": "Set the intent dispatch URL for diagnostics.", "value": { "metadata": { "intent_dispatch_url": "https://diagnostics.acme.org/probe" } } } } } } }, "responses": { "200": { "description": "The device metadata was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "examples": { "successful_metadata_update": { "summary": "Successful Metadata Update", "value": { "metadata": { "intent_dispatch_url": "https://diagnostics.acme.org/probe", "last_updated": "2023-10-01T12:34:56Z" } } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Validation Error", "status": 400, "detail": "metadata object is required", "errors": [ { "field": "metadata", "code": "REQUIRED_FIELD_MISSING", "message": "metadata object is required", "expected": "object", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or not been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Missing or invalid authentication token." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to modify this device." } } } } } }, "404": { "description": "The specified device was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Device Not Found", "status": 404, "detail": "Device '12345' not found for this org." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/webhooks/subscriptions/:id/test": { "post": { "summary": "Initiate a Webhook Subscription Test", "description": "This endpoint allows organizations to queue a synthetic test delivery for their webhook subscriptions. It's a powerful tool to ensure that your webhook configurations are correctly set up and ready to receive events. By simulating a webhook event, organizations can verify the integrity and responsiveness of their integrations.", "operationId": "postWebhookSubscriptionTest", "tags": [ "Webhooks", "Testing" ], "x-code-hash": "523f4b9fe79d9f96", "x-generated-at": "2026-03-31T03:40:21.513Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orgDid": { "type": "string", "description": "Decentralized identifier for the organization initiating the test" } }, "required": [ "orgDid" ] }, "examples": { "initiate_test_delivery": { "summary": "Initiate Test Delivery", "description": "Example of a request to initiate a test delivery for webhook subscription with a valid org DID.", "value": { "orgDid": "did:example:123456789abcdefghi" } } } } } }, "responses": { "200": { "description": "The test delivery was successfully queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "The identifier of the webhook subscription" }, "event_id": { "type": "string", "description": "The event identifier for the synthetic test" }, "delivery_id": { "type": "string", "description": "The unique identifier for this delivery" }, "event_type": { "type": "string", "description": "The type of event, indicating this is a test" }, "queue_status": { "type": "string", "description": "Status of the delivery queue" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request due to missing or invalid data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "Org DID required", "errors": [ { "field": "authorization", "code": "ORG_DID_REQUIRED", "message": "Org DID required", "received": "no delegation" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication-error", "title": "Unauthorized", "status": 401, "detail": "Authorization credentials are missing or invalid." } } } } } }, "404": { "description": "The subscription id was not found or is not an active external webhook.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Subscription sub-abc123 not found or not an active external webhook." } } } } } }, "503": { "description": "The delivery queue is saturated, preventing new deliveries.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/webhook-delivery-queue-saturated", "title": "Delivery Queue Saturated", "status": 503, "detail": "This org has reached the maximum number of pending webhook deliveries. Retry after deliveries drain or raise WEBHOOK_ORG_PENDING_DELIVERIES_CAP.", "remediation": [ { "step": 1, "description": "Inspect dead-letter and pending rows in the Command Plane webhook delivery log; redeliver or clear stuck work." } ] } } } } } } } } }, "/v1/control-plane/marketplace/partner-feed": { "get": { "summary": "Retrieve deduplicated partner incident feed", "description": "Gain insights into marketplace incidents impacting your assets with this endpoint. By leveraging your Passport, it filters and summarizes incidents, providing a concise view of issues that matter most to your organization. Discover the root causes and suggested fixes quickly, ensuring you can take prompt action.", "operationId": "getPartnerFeed", "tags": [ "Marketplace", "Incidents" ], "x-code-hash": "ba72b8e15af23e63", "x-generated-at": "2026-03-31T01:28:43.033Z", "responses": { "200": { "description": "Successfully retrieved the deduplicated incident feed for the publisher", "content": { "application/json": { "schema": { "type": "object", "properties": { "publisher_id": { "type": "string", "description": "The Passport ID of the requesting publisher" }, "generated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the feed was generated" }, "data": { "type": "array", "items": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "Unique identifier for the incident pattern" }, "problem_summary": { "type": "string", "description": "A brief description of the incident problem" }, "suggested_fix_steps": { "type": "array", "items": { "type": "string" }, "description": "List of proposed actions to resolve the incident" }, "incident_ids": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of incidents included in this pattern" }, "severity": { "type": "string", "description": "The severity level of the incident" }, "status": { "type": "string", "description": "Current status of the incident" }, "affected_asset_id": { "type": [ "string", "null" ], "description": "ID of the affected asset, if any" }, "occurrence_count": { "type": "integer", "description": "Number of times this incident pattern has occurred" }, "first_seen_at": { "type": "string", "format": "date-time", "description": "Timestamp when the incident was first detected" }, "last_seen_at": { "type": "string", "format": "date-time", "description": "Timestamp when the incident was last detected" } }, "required": [ "fingerprint", "problem_summary", "suggested_fix_steps", "incident_ids", "severity", "status", "occurrence_count", "first_seen_at", "last_seen_at" ] }, "description": "A list of deduplicated incident patterns affecting the publisher's assets" } }, "required": [ "publisher_id", "generated_at", "data" ] }, "examples": { "successful_incident_feed_retrieval": { "summary": "Successful Incident Feed Retrieval", "description": "Retrieves the incident feed for a publisher with Passport ID 'publisher-123'.", "value": { "publisher_id": "publisher-123", "generated_at": "2023-10-15T12:34:56Z", "data": [ { "fingerprint": "abc123def456ghi789jkl012", "problem_summary": "Elevated error rate (12.5%) for 'Asset X'", "suggested_fix_steps": [ "Check API integration", "Verify configuration settings" ], "incident_ids": [ "incident-001", "incident-002" ], "severity": "high", "status": "investigating", "affected_asset_id": "asset-001", "occurrence_count": 2, "first_seen_at": "2023-10-10T08:00:00Z", "last_seen_at": "2023-10-12T16:30:00Z" } ] } } } } } }, "400": { "description": "Bad Request due to invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid Parameters", "description": "Occurs when request parameters are improperly formatted.", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "The request parameters were invalid. Ensure all required fields are correctly formatted.", "errors": [ "publisher_id must be a valid string" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "Occurs when the delegation context is missing or invalid.", "value": { "type": "https://example.com/probs/authentication", "title": "Authentication Required", "status": 401, "detail": "Delegation required for partner feed. Please include a valid delegation context in your request." } } } } } }, "403": { "description": "Forbidden access when the user lacks permission to view the feed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "Occurs when the user lacks the necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "Not Found when the requested resource does not exist", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Occurs when the specified resource cannot be found.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found. Verify the resource ID and try again." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Occurs when the server encounters an unexpected error.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/incidents/metrics/summary": { "get": { "summary": "Retrieve summary of incident metrics", "description": "Dive into the heart of your organization’s incident handling with this endpoint. It provides a comprehensive summary of incident metrics, filtered by severity and status, empowering you to understand patterns and improve response strategies. This endpoint exists to ensure that organizations can proactively manage and mitigate incidents before they escalate.", "operationId": "getIncidentMetricsSummary", "tags": [ "Incident Management", "Metrics" ], "x-code-hash": "d310cde88aef3d0c", "x-generated-at": "2026-03-31T03:37:51.253Z", "responses": { "200": { "description": "Metrics summary retrieved successfully, detailing incidents by severity and status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": [ "string", "null" ], "description": "Decentralized Identifier for the organization, or null if not specified." }, "total_count": { "type": "integer", "description": "Total number of incidents found." }, "by_severity": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Breakdown of incidents by severity." }, "by_status": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Breakdown of incidents by status." }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string" }, "status": { "type": "string" }, "count": { "type": "integer" } } }, "description": "Detailed breakdown of each incident metric." } } }, "examples": { "incident_metrics_summary_for_acme_corp": { "summary": "Incident Metrics Summary for Acme Corp", "description": "Acme Corp’s incident metrics summary shows a balanced view of incidents by severity and status.", "value": { "org_did": "did:example:acme", "total_count": 42, "by_severity": { "critical": 10, "high": 15, "medium": 12, "low": 5 }, "by_status": { "open": 20, "resolved": 22 }, "breakdown": [ { "severity": "critical", "status": "open", "count": 5 }, { "severity": "critical", "status": "resolved", "count": 5 }, { "severity": "high", "status": "open", "count": 10 }, { "severity": "high", "status": "resolved", "count": 5 } ] } } } } } }, "400": { "description": "Bad request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_query_parameter_example": { "summary": "Invalid Query Parameter Example", "description": "An example of an invalid query parameter error response.", "value": { "type": "/problems/invalid-query", "title": "Invalid query parameters", "status": 400, "detail": "The 'org_did' query parameter is invalid. Ensure it follows the DID specification format." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_failure_example": { "summary": "Authentication Failure Example", "description": "An example error response for authentication failure.", "value": { "type": "/problems/authentication-failed", "title": "Authentication failed", "status": 401, "detail": "Access token is missing or invalid. Please log in and try again." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions_example": { "summary": "Insufficient Permissions Example", "description": "An example of a forbidden access error response.", "value": { "type": "/problems/insufficient-permissions", "title": "Insufficient permissions", "status": 403, "detail": "You do not have permission to access this resource. Contact your administrator for access rights." } } } } } }, "404": { "description": "Not found error when the requested resource does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "description": "An example error response for a not found resource.", "value": { "type": "/problems/resource-not-found", "title": "Resource not found", "status": 404, "detail": "The requested incidents metric summary could not be found. Verify the resource identifier and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "An example error response for an internal server error.", "value": { "type": "/problems/internal-server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later. If the problem persists, contact support." } } } } } } } } }, "/v1/control-plane/incidents/:incidentId/remediation-suggest": { "post": { "summary": "Suggest remediation for an incident", "description": "This endpoint crafts a thoughtful remediation suggestion for a given incident, weaving together AI predictions and human insights. It empowers organizations to address incidents with precision, ensuring safety and compliance through seamless task orchestration.", "operationId": "postIncidentRemediationSuggest", "tags": [ "Incident Management", "HumanOS" ], "x-code-hash": "2b90a33a6cc6ac0e", "x-generated-at": "2026-03-31T03:38:05.658Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enqueue_agent_trigger": { "type": "boolean", "description": "Flag to trigger an agent if true." } }, "required": [] }, "examples": { "basic_remediation_suggestion": { "summary": "Basic remediation suggestion", "description": "A request to suggest remediation without agent trigger.", "value": { "enqueue_agent_trigger": false } }, "trigger_agent_on_remediation": { "summary": "Trigger agent on remediation", "description": "A request that suggests remediation and triggers an agent.", "value": { "enqueue_agent_trigger": true } } } } } }, "responses": { "200": { "description": "Successful remediation suggestion with AI-enhanced guidance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "incident_id": { "type": "string", "description": "Unique identifier of the incident." }, "mode": { "type": "string", "description": "Suggested mode of remediation." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "detail": { "type": "string", "description": "Details of the remediation step." } } } } } }, "examples": { "successful_remediation_suggestion": { "summary": "Successful remediation suggestion", "value": { "incident_id": "12345", "mode": "automatic", "steps": [ { "detail": "Review access logs for unauthorized access attempts." } ] } } } } } }, "400": { "description": "Bad Request - Missing required data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_incidentid": { "summary": "Missing incidentId", "value": { "type": "https://haio.run/errors/validation", "title": "Missing incidentId", "status": 400, "detail": "incidentId is required." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid credentials", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Not Found - Incident does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "incident_not_found": { "summary": "Incident not found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified incident was not found." } } } } } }, "500": { "description": "Internal Server Error - A problem occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/incidents/:incidentId/external-issue": { "post": { "summary": "Link External Issue to Incident", "description": "In the high-stakes world of incident management, every moment counts. This endpoint empowers you to link an external issue from popular trackers like Jira or GitHub directly to an incident, ensuring seamless integration and comprehensive incident resolution history.", "operationId": "linkExternalIssueToIncident", "tags": [ "Incident Management", "Integration" ], "x-code-hash": "0925724b23a010a7", "x-generated-at": "2026-03-31T03:38:21.056Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "linear", "jira", "github" ], "description": "The external provider where the issue is tracked" }, "external_key": { "type": "string", "description": "A stable identifier for the issue within the external tracker" }, "issue_url": { "type": "string", "format": "uri", "description": "The direct URL to the issue in the external tracker" } }, "required": [ "provider", "external_key", "issue_url" ] }, "examples": { "jira_issue_link": { "summary": "Jira Issue Link", "description": "Linking a Jira issue to an incident", "value": { "provider": "jira", "external_key": "JIRA-123", "issue_url": "https://jira.example.com/browse/JIRA-123" } } } } } }, "responses": { "201": { "description": "The external issue was successfully linked to the incident", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The organization DID associated with the incident" }, "incident_id": { "type": "string", "description": "The ID of the incident" }, "provider": { "type": "string", "description": "The provider of the external issue" }, "fingerprint": { "type": "string", "description": "A unique fingerprint representing the external issue linkage" }, "external_key": { "type": "string", "description": "The stable key of the external issue" }, "issue_url": { "type": "string", "format": "uri", "description": "The URL of the external issue" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing or incorrect parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing incidentId", "status": 400, "detail": "incidentId is required.", "errors": [ { "field": "provider", "code": "INVALID_VALUE", "message": "provider must be linear, jira, or github", "expected": "linear|jira|github", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to access this resource." } } } } } }, "403": { "description": "Forbidden access despite valid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Incident not found for the given ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Incident Not Found", "status": 404, "detail": "No incident found with ID: inc-456" } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/checkpoints/:id/resume": { "post": { "summary": "Resume an Interrupted Agent Execution", "description": "In the fast-paced world of AI orchestration, interruptions can occur. This endpoint allows you to resume an agent’s workflow that was previously paused, ensuring seamless continuity in your operations. By providing a decision or input, you breathe life back into your processes, picking up precisely where they left off.", "operationId": "resumeCheckpoint", "tags": [ "Agent Management", "Workflow Control" ], "x-code-hash": "e9b9767a00b3152f", "x-generated-at": "2026-04-01T18:44:45.486Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resume_value": { "description": "The decision or input required to resume the checkpoint.", "type": "string" } }, "required": [ "resume_value" ] }, "examples": { "approval_decision_for_invoice_processing": { "summary": "Approval Decision for Invoice Processing", "description": "Resuming an invoice processing agent with the manager's approval decision.", "value": { "resume_value": "approved" } } } } } }, "responses": { "200": { "description": "The checkpoint was successfully resumed, and the agent is back in action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkpoint_id": { "type": "string", "description": "The unique identifier of the resumed checkpoint." }, "status": { "type": "string", "enum": [ "resumed" ], "description": "Indicates that the checkpoint has been successfully resumed." }, "resumed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the checkpoint was resumed." } } }, "examples": { "default": { "summary": "Example", "value": { "checkpoint_id": "chkpt_12345", "status": "resumed", "resumed_at": "2023-10-12T08:45:00Z" } } } } } }, "400": { "description": "The checkpoint is not in an 'interrupted' state or the request body is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/conflict", "title": "Checkpoint not in interrupted state", "status": 400, "detail": "Checkpoint chkpt_12345 is in status 'completed'; only 'interrupted' checkpoints can be resumed.", "errors": [] } } } } } }, "401": { "description": "Authentication delegation is missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Missing delegation context", "status": 401, "detail": "The request is missing a valid delegation context. Ensure your request includes a proper authentication delegation from your organization." } } } } } }, "403": { "description": "The requesting organization does not own the checkpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Authorization Error", "status": 403, "detail": "You do not have access to this checkpoint. Verify that your organization owns this checkpoint and retry the request." } } } } } }, "404": { "description": "The specified checkpoint could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Checkpoint Not Found", "status": 404, "detail": "The checkpoint with ID chkpt_12345 was not found. Please verify the ID and try again." } } } } } }, "500": { "description": "An internal server error occurred while attempting to resume the checkpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while resuming the checkpoint. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/builder/workflows": { "post": { "summary": "Create a new Builder workflow", "description": "Embark on a journey to orchestrate tasks with ease by creating a new Builder workflow. This endpoint empowers organizations to define and manage workflows, streamlining operations and enhancing productivity. Whether you're just starting with a draft or deploying a full-fledged workflow, this endpoint is your gateway to efficient task orchestration.", "operationId": "createBuilderWorkflow", "tags": [ "Task Management", "Workflow Builder" ], "x-code-hash": "b866abe4f737e787", "x-generated-at": "2026-04-01T23:23:30.067Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The display name of the workflow. Defaults to 'Untitled workflow'." }, "scope": { "type": "string", "enum": [ "personal", "workspace", "org" ], "description": "Defines the visibility scope of the workflow. Defaults to 'workspace'." }, "manifest": { "type": "object", "description": "A detailed JSON object representing the workflow's structure." }, "lifecycle_state": { "type": "string", "description": "The current lifecycle state of the workflow, e.g., 'draft'. Defaults to 'draft'." } }, "required": [] }, "examples": { "create_draft_workflow": { "summary": "Create Draft Workflow", "description": "This example demonstrates creating a draft workflow with default settings.", "value": { "name": "Invoice Processing", "scope": "workspace", "manifest": { "kind": "humanos.workflow.v1", "id": "wf-1634235600000", "name": "Invoice Processing", "version": "1.0.0", "publisher": "human", "steps": [], "triggers": [] }, "lifecycle_state": "draft" } } } } } }, "responses": { "201": { "description": "The workflow was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the workflow." }, "org_id": { "type": "string", "description": "Organization ID associated with the workflow." }, "owner_did": { "type": "string", "description": "Decentralized Identifier of the workflow owner." }, "name": { "type": "string", "description": "Display name of the workflow." }, "scope": { "type": "string", "enum": [ "personal", "workspace", "org" ], "description": "Visibility scope of the workflow." }, "lifecycle_state": { "type": "string", "description": "Current lifecycle state of the workflow." }, "manifest": { "type": "object", "description": "JSON object representing the workflow's structure." }, "version": { "type": "integer", "description": "Version number of the workflow." }, "builder_flags": { "type": "object", "description": "Flags for the workflow builder." }, "published_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workflow was published." }, "activated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workflow was activated." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workflow was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last update to the workflow." } } }, "examples": { "successful_workflow_creation": { "summary": "Successful Workflow Creation", "value": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "org_id": "org-1a2b3c", "owner_did": "did:human:123456789abcdefghi", "name": "Invoice Processing", "scope": "workspace", "lifecycle_state": "draft", "manifest": { "kind": "humanos.workflow.v1", "id": "wf-1634235600000", "name": "Invoice Processing", "version": "1.0.0", "publisher": "human", "steps": [], "triggers": [] }, "version": 1, "builder_flags": {}, "published_at": null, "activated_at": null, "created_at": "2023-10-10T14:48:00Z", "updated_at": "2023-10-10T14:48:00Z" } } } } } }, "400": { "description": "The request is missing required organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Authentication failed due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "value": { "type": "https://haio.run/errors/authentication", "title": "Authentication failed", "status": 401, "detail": "Invalid authentication credentials provided." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://haio.run/errors/authorization", "title": "Access forbidden", "status": 403, "detail": "You do not have permission to create a workflow in this organization." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Resource not found", "status": 404, "detail": "The specified workflow or related resource does not exist." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } }, "get": { "summary": "Retrieve organization-specific workflow details", "description": "Explore the dynamic landscape of your organization's workflows with this endpoint. It offers a window into the lifecycle, scope, and status of active workflows, empowering you to oversee and optimize your processes with precision.", "operationId": "getBuilderWorkflows", "tags": [ "Workflows", "Organization" ], "x-code-hash": "3318c6b71fc0e4fb", "x-generated-at": "2026-04-01T23:23:43.982Z", "responses": { "200": { "description": "Successfully retrieved the list of workflows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the workflow" }, "name": { "type": "string", "description": "Name of the workflow" }, "lifecycle_state": { "type": "string", "description": "Current state of the workflow" }, "scope": { "type": "string", "description": "Scope of the workflow" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "lifecycle_state", "scope", "updated_at" ] } }, "limit": { "type": "integer", "description": "Number of workflows requested" }, "hasMore": { "type": "boolean", "description": "Indicates if more workflows are available" }, "cursorField": { "type": "string", "description": "Field used for pagination cursor" } }, "required": [ "data", "limit", "hasMore", "cursorField" ] }, "examples": { "successful_retrieval_of_workflows": { "summary": "Successful retrieval of workflows", "value": { "data": [ { "id": "workflow-123", "name": "Invoice Processing", "lifecycle_state": "active", "scope": "finance", "updated_at": "2023-10-15T12:34:56Z" }, { "id": "workflow-456", "name": "Order Fulfillment", "lifecycle_state": "pending", "scope": "sales", "updated_at": "2023-10-14T11:22:33Z" } ], "limit": 2, "hasMore": true, "cursorField": "updated_at" } } } } } }, "400": { "description": "Bad Request: Missing or invalid organization context", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_context_missing": { "summary": "Organization context missing", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized: Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication error", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authorization credentials not provided or invalid." } } } } } }, "403": { "description": "Forbidden: Access to this resource is denied", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view these workflows." } } } } } }, "500": { "description": "Internal Server Error: Unexpected problem occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/workflows/intent": { "post": { "summary": "Initiate workflow intent creation", "description": "Embark on the journey of crafting a new workflow intent, a crucial step in automating human-AI collaboration. This endpoint enables you to define the blueprint for a workflow, setting the stage for seamless orchestration and task execution.", "operationId": "createWorkflowIntent", "tags": [ "Workflows", "Intent" ], "x-code-hash": "6a02d4611ab9e82e", "x-generated-at": "2026-04-01T23:22:51.672Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the workflow intent" }, "description": { "type": "string", "description": "A detailed description of what the workflow intends to achieve" }, "capabilityGraph": { "type": "array", "items": { "type": "string", "description": "A list of capabilities required for this workflow" } } }, "required": [ "name", "capabilityGraph" ] }, "examples": { "create_invoice_processing_workflow": { "summary": "Create Invoice Processing Workflow", "description": "An example of creating a workflow intent for processing invoices in the 'acme' organization.", "value": { "name": "Invoice Processing", "description": "Handles the processing of invoices submitted by vendors.", "capabilityGraph": [ "capability://document/parse", "capability://payment/execute" ] } } } } } }, "responses": { "201": { "description": "The workflow intent was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the newly created workflow intent" }, "status": { "type": "string", "description": "Current status of the workflow intent creation" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Request is malformed or contains invalid JSON.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "You lack the permissions to create a workflow intent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "The endpoint or resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/builder/workflows/from-companion": { "post": { "summary": "Create workflow from Companion suggestion", "description": "This endpoint empowers organizations to transform AI-driven insights from the HUMAN Companion into executable workflows. By bridging AI suggestions with organizational processes, it orchestrates a seamless integration ensuring efficiency and innovation.", "operationId": "postWorkflowsFromCompanion", "tags": [ "Workflow", "Companion" ], "x-code-hash": "3ee5d64f2c25724a", "x-generated-at": "2026-04-26T23:22:01.954Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "suggested_intent": { "type": "string", "description": "AI suggested intent for the workflow." }, "intent_brief_id": { "type": "string", "description": "Optional ID of an existing intent brief." } } }, "examples": { "ai_suggested_workflow": { "summary": "AI Suggested Workflow", "description": "An example where a new workflow is suggested by the AI companion.", "value": { "suggested_intent": "Automate invoice processing", "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "responses": { "200": { "description": "The workflow creation was successful, returning the workflow manifest and associated IDs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "manifest": { "type": "object", "description": "The manifest of the created workflow.", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "publisher": { "type": "string" }, "description": { "type": "string" }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "capture_intents": { "type": "array", "items": { "type": "string" } } } } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "muscle_id": { "type": "string" }, "label": { "type": "string" } } } } } }, "intent_brief_id": { "type": "string" }, "resolution_plan_id": { "type": "string" }, "source": { "type": "string" } } }, "examples": { "successful_workflow_manifest": { "summary": "Successful Workflow Manifest", "description": "A successful response with a new workflow manifest and IDs.", "value": { "manifest": { "kind": "humanos.workflow.v1", "id": "workflow-6789", "name": "Automate Invoice Processing", "version": "1.0.0", "publisher": "human", "description": "Automated workflow from Companion pattern", "triggers": [ { "kind": "manual_capture", "capture_intents": [ "companion.handoff" ] } ], "steps": [ { "id": "ingest", "kind": "muscle", "muscle_id": "classify", "label": "Classify Companion pattern" } ] }, "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000", "resolution_plan_id": "plan-9876", "source": "intent_scaffold" } } } } } }, "400": { "description": "Bad Request due to missing organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The intent brief could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error when creating workflow.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/builder/workflows/:id": { "get": { "summary": "Retrieve a specific workflow by ID", "description": "Discover the intricate details of a workflow by retrieving it using its unique identifier. This endpoint is a gateway to understanding how your organization's workflows are orchestrated, ensuring seamless task execution.", "operationId": "getWorkflowById", "tags": [ "Workflows", "Builder" ], "x-code-hash": "b7d9fcbff1d23455", "x-generated-at": "2026-04-01T23:23:57.330Z", "responses": { "200": { "description": "Successfully retrieved the workflow details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the workflow" }, "name": { "type": "string", "description": "The name of the workflow" }, "status": { "type": "string", "description": "The current status of the workflow" }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the workflow was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp of the last update to the workflow" } } }, "examples": { "successful_workflow_retrieval": { "summary": "Successful Workflow Retrieval", "description": "An example showing successful retrieval of a workflow", "value": { "id": "wf1234", "name": "Invoice Processing", "status": "active", "created_at": "2023-09-15T12:34:56Z", "updated_at": "2023-10-01T08:45:23Z" } } } } } }, "400": { "description": "Bad Request - Organization context missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "Occurs when organization information is not provided in the request", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_authentication": { "summary": "Invalid Authentication", "description": "Occurs when the authentication credentials are incorrect or missing", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are invalid or not provided" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Occurs when the user does not have the necessary permissions to access the workflow", "value": { "type": "https://haio.run/errors/permissions", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this workflow" } } } } } }, "404": { "description": "Not Found - Workflow does not exist", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "Occurs when the specified workflow ID does not exist", "value": { "type": "https://haio.run/errors/not-found", "title": "Workflow not found", "status": 404, "detail": "No workflow found with ID wf1234" } } } } } }, "500": { "description": "Internal Server Error - Unexpected error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Occurs when an unexpected error happens on the server", "value": { "type": "https://haio.run/errors/internal-server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "put": { "summary": "Update an existing workflow definition", "description": "In the world of dynamic task orchestration, workflows are the heart of managing complex processes. This endpoint empowers organizations to update these workflows, ensuring they adapt to evolving business requirements while maintaining the integrity of their lifecycle states.", "operationId": "updateWorkflowDefinition", "tags": [ "Workflows", "Builder" ], "x-code-hash": "4c719ab399257d4f", "x-generated-at": "2026-04-01T23:24:14.363Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name for the workflow" }, "manifest": { "type": "object", "description": "JSON object representing the workflow's structure and logic" }, "lifecycle_state": { "type": "string", "enum": [ "draft", "active", "archived" ], "description": "Current state of the workflow in its lifecycle" }, "builder_flags": { "type": "object", "description": "Additional flags for workflow builder settings" } }, "required": [ "name" ] }, "examples": { "updating_workflow_name_and_state": { "summary": "Updating Workflow Name and State", "description": "This example demonstrates updating the name and state of a workflow", "value": { "name": "Invoice Processing Workflow", "lifecycle_state": "active", "manifest": { "steps": [ { "action": "validate", "input": "invoice" }, { "action": "approve", "input": "manager" } ] }, "builder_flags": { "allowParallelExecution": true } } } } } } }, "responses": { "200": { "description": "The workflow was updated successfully, reflecting new details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the workflow" }, "name": { "type": "string", "description": "Updated name of the workflow" }, "manifest": { "type": "object", "description": "Updated manifest of the workflow" }, "lifecycle_state": { "type": "string", "description": "Updated lifecycle state" }, "builder_flags": { "type": "object", "description": "Updated builder flags" } } }, "examples": { "default": { "summary": "Example", "value": { "id": "wf-12345", "name": "Invoice Processing Workflow", "manifest": { "steps": [ { "action": "validate", "input": "invoice" }, { "action": "approve", "input": "manager" } ] }, "lifecycle_state": "active", "builder_flags": { "allowParallelExecution": true } } } } } } }, "400": { "description": "Invalid request due to missing or incorrect data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to access this resource." } } } } } }, "403": { "description": "Forbidden request due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/permissions", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this workflow." } } } } } }, "404": { "description": "Workflow not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Workflow not found", "status": 404, "detail": "No workflow found with ID 'wf-12345'." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "summary": "Delete a Builder Workflow by ID", "description": "In the dynamic world of workflow automation, maintaining a clean slate is crucial. This endpoint empowers organizations to remove obsolete or incorrect workflows, ensuring their operational landscape remains efficient and relevant. By providing this ability, we help teams focus on what matters most: innovation and productivity.", "operationId": "deleteBuilderWorkflowById", "tags": [ "Workflow Management", "Builder" ], "x-code-hash": "904bbaa1209598cf", "x-generated-at": "2026-04-01T23:24:27.316Z", "responses": { "204": { "description": "Successfully deleted the workflow. No content is returned.", "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "The request was malformed or missing required parameters, such as the organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "The request didn't provide the necessary organization context.", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "404": { "description": "The specified workflow could not be found under the given organization ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "The workflow with the specified ID does not exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Workflow not found", "status": 404, "detail": "No workflow found with ID 'wfl-12345' in organization 'acme'." } } } } } }, "500": { "description": "An unexpected error occurred on the server while attempting to delete the workflow.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server-side issue occurred during the deletion process.", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/activate": { "post": { "summary": "Activate a Builder Workflow", "description": "Transform your workflow from a dormant state into action by activating it. This endpoint exists to empower organizations to seamlessly transition workflows into an active state, ensuring tasks are ready to be processed. Whether you're launching a new project or reviving an existing one, activating workflows is a critical step in the orchestration process.", "operationId": "activateBuilderWorkflow", "tags": [ "Workflows", "Lifecycle Management" ], "x-code-hash": "fd2f2b12b614155d", "x-generated-at": "2026-04-01T23:24:46.540Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "A note providing context or rationale for activating the workflow" } } }, "examples": { "activate_with_context_note": { "summary": "Activate with context note", "description": "Activating a workflow with a note to explain the reason", "value": { "note": "Activating for Q4 invoice processing cycle" } } } } } }, "responses": { "200": { "description": "The workflow has been successfully activated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique workflow identifier" }, "org_id": { "type": "string", "description": "Organization ID" }, "owner_did": { "type": "string", "description": "DID of the workflow owner" }, "name": { "type": "string", "description": "Name of the workflow" }, "scope": { "type": "string", "description": "Scope of the workflow" }, "lifecycle_state": { "type": "string", "description": "Current lifecycle state" }, "manifest": { "type": "object", "description": "Workflow manifest details" }, "version": { "type": "string", "description": "Version of the workflow" }, "builder_flags": { "type": "object", "description": "Flags related to workflow builder" }, "timestamps": { "type": "object", "description": "Timestamps related to the workflow" } } }, "examples": { "invoice_processing": { "summary": "Invoice Processing" } } } } }, "400": { "description": "Bad Request when the organization context is missing or invalid lifecycle transition", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid lifecycle transition", "status": 400, "detail": "Transition from 'completed' to 'active' is not allowed" } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Missing or invalid API key" } } } } } }, "403": { "description": "Forbidden request when the user lacks permission to activate the workflow", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to activate this workflow" } } } } } }, "404": { "description": "The workflow was not found for the specified ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Workflow not found", "status": 404, "detail": "No workflow found with ID 'wf-12345'" } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request" } } } } } } } } }, "/v1/builder/workflows/:id/deactivate": { "post": { "summary": "Deactivate a workflow by ID", "description": "In the dynamic world of task management, workflows often need to be paused or revisited. This endpoint allows you to deactivate a workflow, transitioning it to a 'draft' state. By doing so, teams can refine tasks without impacting the live environment, ensuring meticulous quality control before reactivation.", "operationId": "deactivateWorkflowById", "tags": [ "Workflow", "Management" ], "x-code-hash": "203676ba8c259e1d", "x-generated-at": "2026-04-01T23:24:57.522Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "An optional note providing context or reasoning for the deactivation." } }, "additionalProperties": false }, "examples": { "deactivation_with_reason": { "summary": "Deactivation with Reason", "description": "Deactivating a workflow with a note.", "value": { "note": "Pausing workflow for quarterly review." } } } } } }, "responses": { "200": { "description": "Workflow successfully deactivated, returning updated workflow details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "name": { "type": "string" }, "lifecycleState": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example", "value": { "id": "workflow-123", "orgId": "acme-corp", "name": "Invoice Processing", "lifecycleState": "draft", "updatedAt": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "Request is missing required organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Authentication is required and has failed or not been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "The authenticated user does not have permission to deactivate the workflow.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to deactivate this workflow." } } } } } }, "404": { "description": "The specified workflow was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The workflow with ID 'workflow-123' was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/duplicate": { "post": { "summary": "Duplicate an existing workflow", "description": "This endpoint allows you to create a new copy of an existing workflow within your organization, enabling iterative development and experimentation. By duplicating workflows, you can preserve original configurations while exploring new ideas, enhancing collaboration and innovation.", "operationId": "duplicateBuilderWorkflow", "tags": [ "Builder", "Workflows" ], "x-code-hash": "feb91ba7545ef885", "x-generated-at": "2026-04-01T23:25:36.364Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name_suffix": { "type": "string", "description": "Suffix to append to the original workflow name" } }, "example": { "name_suffix": " - draft 2" } }, "examples": { "adding_a_custom_suffix": { "summary": "Adding a custom suffix", "description": "Duplicates a workflow with a custom suffix appended to the name", "value": { "name_suffix": " - new iteration" } } } } } }, "responses": { "201": { "description": "Workflow duplicated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the new workflow" }, "name": { "type": "string", "description": "Name of the duplicated workflow" }, "owner_did": { "type": "string", "description": "DID of the workflow owner" }, "scope": { "type": "string", "description": "Scope of the workflow" }, "lifecycle_state": { "type": "string", "description": "Current state of the workflow" } } }, "examples": { "successful_duplication": { "summary": "Successful duplication", "description": "Response after successfully duplicating a workflow", "value": { "id": "workflow-1234", "name": "Invoice Processing - new iteration", "owner_did": "did:human:123456789abcdef", "scope": "accounting", "lifecycle_state": "draft" } } } } } }, "400": { "description": "Bad Request - Missing or invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing organization context", "description": "The organization ID is required but missing from the request.", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized - Invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid credentials", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Invalid or missing authentication credentials" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission denied", "description": "The user does not have the required permissions to duplicate the workflow.", "value": { "type": "https://haio.run/errors/permissions", "title": "Forbidden", "status": 403, "detail": "You do not have permission to duplicate this workflow" } } } } } }, "404": { "description": "Not Found - Workflow not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow not found", "description": "No workflow exists with the specified ID.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No workflow found with the given ID" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/promote-scope": { "post": { "summary": "Promote workflow scope within an organization", "description": "Elevate the scope of a workflow from a personal level to a broader organizational level, ensuring essential workflows gain the visibility they deserve. This endpoint empowers administrators to streamline operations by adjusting workflow accessibility and visibility across different levels of the organization.", "operationId": "promoteWorkflowScope", "tags": [ "Workflow Management", "Organization" ], "x-code-hash": "8bb54e1a75f7d307", "x-generated-at": "2026-04-01T23:25:53.838Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "personal", "workspace", "org" ], "description": "The target scope to promote the workflow to: personal, workspace, or org" } }, "required": [ "scope" ] }, "examples": { "promoting_to_organizational_scope": { "summary": "Promoting to Organizational Scope", "description": "Illustrates changing a workflow's scope from personal to organizational level.", "value": { "scope": "org" } } } } } }, "responses": { "200": { "description": "Workflow scope successfully promoted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the workflow" }, "scope": { "type": "string", "description": "Updated scope of the workflow" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the update" } } }, "examples": { "successful_promotion_response": { "summary": "Successful Promotion Response", "value": { "id": "wf123", "scope": "org", "updated_at": "2023-10-05T14:48:00Z" } } } } } }, "400": { "description": "Bad Request due to missing or invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_scope_example": { "summary": "Invalid Scope Example", "value": { "type": "https://haio.run/errors/validation", "title": "Bad Request", "status": 400, "detail": "scope must be personal | workspace | org", "errors": [ { "field": "scope", "code": "INVALID", "message": "scope must be personal | workspace | org", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized request due to lack of valid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication required to access this resource" } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions_example": { "summary": "Insufficient Permissions Example", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to promote this workflow" } } } } } }, "404": { "description": "Workflow not found within the specified organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found_example": { "summary": "Workflow Not Found Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified workflow was not found for the organization" } } } } } }, "500": { "description": "Server error indicating an issue processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "value": { "type": "https://haio.run/errors/server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/resolve-capabilities": { "post": { "summary": "Resolve Workflow Capabilities", "description": "This endpoint is the conductor in an orchestra of capabilities, harmonizing the skills required for each step in a workflow. It ensures that only the most suitable connectors are employed, optimizing efficiency and precision in task execution.", "operationId": "resolveCapabilities", "tags": [ "Workflow", "Capabilities" ], "x-code-hash": "1633b322de1d590f", "x-generated-at": "2026-04-01T23:26:08.760Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "include_trace": { "type": "boolean", "description": "Whether to include trace information for debugging." } } }, "examples": { "include_trace_example": { "summary": "Include Trace Example", "description": "An example where trace information is requested.", "value": { "include_trace": true } } } } } }, "responses": { "200": { "description": "Successfully resolved capabilities for each workflow step.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resolutions": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "string", "description": "Identifier for the workflow step." }, "candidates": { "type": "array", "items": { "type": "string" }, "description": "List of candidate connectors capable of executing the step." }, "selected": { "type": "string", "description": "The connector selected for execution." }, "reason": { "type": "string", "description": "Reason for selecting the connector." } } } } } }, "examples": { "successful_resolution": { "summary": "Successful Resolution", "description": "A successful resolution of capabilities for a workflow step.", "value": { "resolutions": [ { "step_id": "step-123", "candidates": [ "connector-456", "connector-789" ], "selected": "connector-456", "reason": "Capability-first cost-informed selection" } ] } } } } } }, "400": { "description": "Invalid request due to missing organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization": { "summary": "Missing Organization", "description": "The organization context is missing in the request.", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Authentication failure due to missing or invalid token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_token": { "summary": "Invalid Token", "description": "The provided token is invalid or expired.", "value": { "type": "https://haio.run/errors/authentication", "title": "Invalid token", "status": 401, "detail": "The access token is invalid or expired. Please authenticate again." } } } } } }, "403": { "description": "Permission denied due to insufficient access rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "User does not have permission to access the resource.", "value": { "type": "https://haio.run/errors/authorization", "title": "Access denied", "status": 403, "detail": "You do not have permission to resolve capabilities for this workflow. Contact your administrator." } } } } } }, "404": { "description": "The requested workflow was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "The specified workflow ID does not correspond to any existing workflow.", "value": { "type": "https://haio.run/errors/not-found", "title": "Workflow not found", "status": 404, "detail": "The workflow with ID 'workflow-123' was not found. Please check the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "A generic server error indicating an internal issue.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred while resolving capabilities. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/test": { "post": { "summary": "Test Workflow Execution", "description": "Initiate a test run of a specific workflow, allowing you to simulate different execution modes to evaluate workflow logic before full deployment. This endpoint empowers organizations to ensure their workflows operate as expected, mitigating risks in live environments.", "operationId": "testWorkflowExecution", "tags": [ "Workflow", "Testing" ], "x-code-hash": "d5b0d09a7991acf4", "x-generated-at": "2026-04-01T23:27:13.486Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dry_run", "sample_data", "live_safe" ], "description": "Execution mode for the workflow test. Defaults to 'dry_run' if not specified." } }, "required": [ "mode" ] }, "examples": { "dry_run_mode": { "summary": "Dry Run Mode", "description": "A test execution in 'dry_run' mode", "value": { "mode": "dry_run" } } } } } }, "responses": { "200": { "description": "Workflow test executed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "description": "The mode in which the workflow was tested." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "string", "description": "Unique identifier of the workflow step." }, "executor": { "type": [ "string", "null" ], "description": "Executor used if not in 'dry_run' mode." }, "confidence": { "type": "number", "description": "Confidence score of step execution." }, "policy": { "type": "string", "description": "Policy applied to the step." }, "escalation_preview": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of escalation action." } } }, "description": "Preview of any escalations triggered." }, "workforce_handoff": { "type": "boolean", "description": "Indicates if the step involves workforce handoff." }, "connector_error": { "type": "boolean", "description": "Indicates if a connector error occurred." }, "notes": { "type": "string", "description": "Additional notes about the step." } }, "required": [ "step_id", "confidence", "policy" ] } }, "duration_ms": { "type": "integer", "description": "Time taken to execute the test in milliseconds." }, "lifecycle_state": { "type": "string", "description": "Updated lifecycle state of the workflow post-test." } } }, "examples": { "default": { "summary": "Example", "value": { "mode": "dry_run", "steps": [ { "step_id": "step1", "executor": null, "confidence": 0.82, "policy": "allow", "escalation_preview": [], "workforce_handoff": false, "connector_error": false, "notes": "mode=dry_run" } ], "duration_ms": 125, "lifecycle_state": "draft" } } } } } }, "400": { "description": "Bad Request due to missing organization context", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized due to invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Workflow not found for the given ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested workflow with ID 'wf-12345' was not found." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/publish": { "post": { "summary": "Publish a workflow for organization", "description": "This endpoint breathes life into a workflow by publishing it within the HUMAN platform. It ensures readiness, transitions the workflow state, and opens the door to new possibilities for organizational or personal use.", "operationId": "publishWorkflow", "tags": [ "Workflows", "Publishing" ], "x-code-hash": "5dae2b6258126558", "x-generated-at": "2026-04-01T23:27:27.474Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "personal", "workspace", "org" ], "description": "Defines the level at which the workflow will be visible upon publishing." } }, "required": [ "scope" ] }, "examples": { "publish_to_workspace": { "summary": "Publish to Workspace", "description": "Publishing a workflow to make it available across the workspace.", "value": { "scope": "workspace" } } } } } }, "responses": { "200": { "description": "Workflow successfully published.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "description": "The published workflow details, including its new state.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scope": { "type": "string" }, "lifecycle_state": { "type": "string" } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Any warnings encountered during the publish process." }, "marketplace_note": { "type": [ "string", "null" ], "description": "Additional information about marketplace linkage, if applicable." } } }, "examples": { "default": { "summary": "Example", "value": { "workflow": { "id": "workflow123", "name": "Invoice Processing", "scope": "workspace", "lifecycle_state": "published" }, "warnings": [], "marketplace_note": null } } } } } }, "400": { "description": "Bad request due to validation errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Readiness checklist failed", "status": 400, "detail": "Required checklist items must pass before publish.", "errors": [ { "field": "checklist_item_1", "code": "READINESS", "message": "Ensure the workflow has a defined endpoint.", "expected": "pass", "received": "fail" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Valid authentication credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to publish workflows in this organization." } } } } } }, "404": { "description": "Workflow not found for the given identifier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The workflow with ID 'workflow123' was not found." } } } } } }, "500": { "description": "Internal server error occurred during publishing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while attempting to publish the workflow. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/runs": { "get": { "summary": "Retrieve Workflow Run History", "description": "Unlock the past of your automation endeavors with this endpoint, allowing organizations to delve into the historical runs of specified workflows. By tracking these runs, you can learn from past outcomes, ensuring continuous improvement and refined orchestration strategies.", "operationId": "getWorkflowRuns", "tags": [ "Workflows", "RunHistory" ], "x-code-hash": "25ff577f6f68cfb2", "x-generated-at": "2026-04-01T23:27:47.845Z", "responses": { "200": { "description": "Returns a paginated list of workflow runs for the specified workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the run." }, "workflow_id": { "type": "string", "description": "Identifier of the workflow." }, "trigger": { "type": "string", "description": "Triggering condition for the run." }, "lifecycle_state_at_run": { "type": "string", "description": "State of the workflow lifecycle during the run." }, "outcome": { "type": "string", "description": "Outcome of the workflow execution." }, "step_results": { "type": "array", "items": { "type": "object" }, "description": "Detailed results of each step in the workflow." }, "started_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run started." }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the run completed, if applicable." }, "duration_ms": { "type": "integer", "description": "Duration of the workflow run in milliseconds." } } } }, "limit": { "type": "integer", "description": "The limit of results per page." }, "cursorField": { "type": "string", "description": "Field used for pagination cursor." }, "hasMore": { "type": "boolean", "description": "Indicates if more results are available." } } }, "examples": { "successful_retrieval_example": { "summary": "Successful Retrieval Example", "description": "An example of a successful response listing workflow runs.", "value": { "data": [ { "id": "run-001", "workflow_id": "workflow-123", "trigger": "manual", "lifecycle_state_at_run": "completed", "outcome": "success", "step_results": [], "started_at": "2023-10-01T12:00:00Z", "completed_at": "2023-10-01T12:10:00Z", "duration_ms": 600000 } ], "limit": 10, "cursorField": "started_at", "hasMore": false } } } } } }, "400": { "description": "Bad Request due to missing organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "Occurs when the organization ID isn't provided in the request.", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "description": "Occurs when the provided credentials are invalid.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "Occurs when the user lacks the necessary permissions to view workflow runs.", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not Found when the specified workflow does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "Occurs when the specified workflow ID does not correspond to any existing workflow.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Workflow with id 'workflow-123' not found." } } } } } }, "500": { "description": "Internal Server Error due to unexpected issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Occurs when an unexpected condition was encountered.", "value": { "type": "https://haio.run/errors/server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/analytics": { "get": { "summary": "Retrieve Workflow Analytics by ID", "description": "Delve into the analytics of your workflows with precision and clarity. This endpoint reveals insightful metrics, allowing organizations to optimize Human-AI orchestration. Discover performance trends and identify areas for improvement to enhance operational efficacy.", "operationId": "getWorkflowAnalytics", "tags": [ "Workflows", "Analytics" ], "x-code-hash": "750c23de4fcc48d2", "x-generated-at": "2026-04-01T23:28:07.155Z", "responses": { "200": { "description": "Successfully retrieved analytics data for the specified workflow, offering a wealth of metrics to analyze performance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_counts": { "type": "object", "properties": { "total": { "type": "integer" }, "by_outcome": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "success_rate": { "type": "number", "format": "float" }, "fallback_rate": { "type": "number", "format": "float" }, "approval_frequency": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "workforce_handoff_rate": { "type": "number", "format": "float" }, "avg_completion_ms": { "type": [ "number", "null" ], "format": "float" }, "connector_failure_rate": { "type": "number", "format": "float" }, "step_failure_breakdown": { "type": "object", "additionalProperties": { "type": "integer" } }, "improvement_suggestions": { "type": "array", "items": { "type": "string" } } } }, "examples": { "acme's_workflow_analytics": { "summary": "Acme's Workflow Analytics", "description": "Analytics for Acme Corp's invoice processing workflow showing success rates and improvement suggestions.", "value": { "run_counts": { "total": 100, "by_outcome": { "success": 80, "fallback": 10, "approval_required": 5, "escalated": 5 } }, "success_rate": 0.8, "fallback_rate": 0.1, "approval_frequency": 0.05, "escalation_rate": 0.05, "workforce_handoff_rate": 0.2, "avg_completion_ms": 1500, "connector_failure_rate": 0.02, "step_failure_breakdown": { "step1": 2, "step2": 1 }, "improvement_suggestions": [ "Review failed runs in Run History and add approval gates where confidence is low." ] } } } } } }, "400": { "description": "Bad Request due to missing organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "The request was missing the required organization context.", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "description": "The user attempted to access the endpoint without valid authentication.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Invalid authentication credentials provided." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "The user lacks the necessary permissions to view workflow analytics.", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Workflow not found due to invalid workflow ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "The specified workflow ID does not exist within the organization.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No workflow found with ID 'abc123'." } } } } } }, "500": { "description": "Internal server error due to unexpected failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/marketplace/templates": { "get": { "summary": "Retrieve Marketplace Asset Templates", "description": "Explore the HUMAN Marketplace catalog, a vibrant selection of templates, connectors, muscles, and policy packs. This endpoint empowers developers by providing a curated list of available assets, enabling seamless integration of HUMAN capabilities into your projects.", "operationId": "getMarketplaceTemplates_1", "tags": [ "Marketplace", "Assets" ], "x-code-hash": "d6a822c5606477b2", "x-generated-at": "2026-04-01T23:28:27.436Z", "responses": { "200": { "description": "Successfully retrieved a paginated list of marketplace asset templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "preview": { "type": "object" } }, "required": [ "id", "slug", "name", "version", "preview" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorField", "hasMore" ] }, "examples": { "acme's_template_fetch": { "summary": "Acme's Template Fetch", "description": "Acme Corp retrieves the latest templates for their AI project, ensuring they have the most up-to-date resources.", "value": { "data": [ { "id": "template-123", "slug": "workflow-invoice-processing", "name": "Invoice Processing Workflow", "version": "1.2.3", "preview": { "description": "Automates invoice processing using AI." } }, { "id": "template-124", "slug": "agent-data-analysis", "name": "Data Analysis Agent", "version": "2.0.0", "preview": { "description": "Analyzes data patterns and generates reports." } } ], "limit": 2, "cursorField": "id", "hasMore": true } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "description": "The client provided an invalid limit parameter.", "value": { "type": "https://humanprotocol.org/docs/errors/invalid-request", "title": "Invalid Request Parameters", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ "limit must be a positive integer" ] } } } } } }, "401": { "description": "Authentication failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization": { "summary": "Missing Authorization", "description": "The request lacked proper authentication headers.", "value": { "type": "https://humanprotocol.org/docs/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be logged in to access this resource." } } } } } }, "403": { "description": "Access forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user attempted to access a restricted resource.", "value": { "type": "https://humanprotocol.org/docs/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to view this resource." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "template_not_found": { "summary": "Template Not Found", "description": "The requested template ID does not exist.", "value": { "type": "https://humanprotocol.org/docs/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested template was not found." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_timeout": { "summary": "Database Timeout", "description": "An unexpected error occurred while retrieving data.", "value": { "type": "https://humanprotocol.org/docs/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/builder/marketplace/templates/:tid": { "get": { "summary": "Retrieve marketplace template details", "description": "Explore the intricate details of a specific template from our marketplace. This endpoint serves as your gateway to understanding the capabilities and assets encapsulated within each template, bringing clarity and depth to your selection process.", "operationId": "getMarketplaceTemplateDetails", "tags": [ "Marketplace", "Templates" ], "x-code-hash": "fb99aab212df817a", "x-generated-at": "2026-04-01T23:28:40.583Z", "responses": { "200": { "description": "Successfully retrieved the template details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the template." }, "slug": { "type": "string", "description": "A URL-friendly identifier for the template." }, "name": { "type": "string", "description": "The name of the template." }, "description": { "type": "string", "description": "A detailed description of the template's purpose and functionality." }, "manifest_json": { "type": "object", "description": "JSON object containing the manifest of the template.", "additionalProperties": true }, "version": { "type": "string", "description": "Version number of the template." }, "asset_type": { "type": "string", "description": "Type of asset the template is categorized under." } } }, "examples": { "acme_invoice_template": { "summary": "Acme Invoice Template", "description": "A comprehensive template used by Acme Corp for processing invoices.", "value": { "id": "t123", "slug": "acme-invoice-template", "name": "Acme Invoice", "description": "A template for automating invoice processing at Acme Corp.", "manifest_json": { "workflow": "invoice-processing", "components": [ "OCR", "Data Extraction", "Verification" ] }, "version": "1.2.0", "asset_type": "financial" } } } } } }, "404": { "description": "Template not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "nonexistent_template": { "summary": "Nonexistent Template", "description": "Attempting to retrieve a template that doesn't exist.", "value": { "type": "/errors/template-not-found", "title": "Template Not Found", "status": 404, "detail": "The template with ID 't123' does not exist." } } } } } }, "500": { "description": "Internal server error while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_error_example": { "summary": "Internal Error Example", "description": "An error occurred due to server misconfiguration.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the template." } } } } } } } } }, "/v1/builder/marketplace/templates/:tid/install": { "post": { "summary": "Install a Marketplace Template", "description": "Install a chosen template from the marketplace into your organization's workspace. This endpoint empowers organizations to rapidly deploy pre-configured workflows or agents, streamlining operations and enhancing productivity.", "operationId": "installMarketplaceTemplate", "tags": [ "Marketplace", "Templates" ], "x-code-hash": "741573ccba327296", "x-generated-at": "2026-04-01T23:29:09.712Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name_override": { "type": "string", "description": "A new name for the template within your organization." } } }, "examples": { "simple_name_override": { "summary": "Simple Name Override", "description": "Install a template with a custom name.", "value": { "name_override": "Custom Workflow for Acme Inc." } } } } } }, "responses": { "201": { "description": "Template successfully installed within the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the installed workflow." }, "name": { "type": "string", "description": "The name of the installed workflow." }, "orgId": { "type": "string", "description": "The organization ID where the workflow is installed." } } }, "examples": { "successful_installation": { "summary": "Successful Installation", "description": "A workflow template named 'Custom Workflow for Acme Inc.' was installed successfully.", "value": { "id": "workflow-12345", "name": "Custom Workflow for Acme Inc.", "orgId": "org-acme" } } } } } }, "400": { "description": "The request is invalid due to missing organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "Attempt to install a template without specifying an organization.", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "404": { "description": "The specified template could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "template_not_found": { "summary": "Template Not Found", "description": "Attempt to install a non-existent template.", "value": { "type": "https://haio.run/errors/not-found", "title": "Template not found", "status": 404, "detail": "No template found with the given ID" } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "A server error occurred during template installation.", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/marketplace/connectors": { "get": { "summary": "Retrieve list of marketplace connectors", "description": "Explore the vast ecosystem of connectors available on the HUMAN Marketplace. This endpoint provides a curated list of connectors, enabling seamless integration and enhancing the capability graph of your organization. Whether you're looking to expand your toolkit or ensure compatibility, this list is your gateway to innovation.", "operationId": "getMarketplaceConnectors_1", "tags": [ "Marketplace", "Connectors" ], "x-code-hash": "f505951b04d127ac", "x-generated-at": "2026-04-01T23:29:30.017Z", "responses": { "200": { "description": "A list of marketplace connectors, sorted alphabetically by name, showcasing available integrations for organizational capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the connector." }, "slug": { "type": "string", "description": "A URL-friendly slug for the connector." }, "name": { "type": "string", "description": "The human-readable name of the connector." }, "description": { "type": "string", "description": "A brief description of what the connector does." }, "version": { "type": "string", "description": "The current version of the connector." } }, "required": [ "id", "slug", "name", "description", "version" ] } } }, "required": [ "data" ] }, "examples": { "successful_connectors_retrieval": { "summary": "Successful connectors retrieval", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "slug": "invoice-processor", "name": "Invoice Processor", "description": "Automates invoice processing for financial departments.", "version": "1.2.4" }, { "id": "123e4567-e89b-12d3-a456-426614174001", "slug": "crm-sync", "name": "CRM Synchronizer", "description": "Keeps your CRM in sync with external data sources.", "version": "2.0.0" } ] } } } } } }, "400": { "description": "Bad Request - The request could not be understood by the server due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request": { "summary": "Malformed Request", "value": { "type": "https://example.com/probs/bad-request", "title": "Bad Request", "status": 400, "detail": "The query parameter 'filter' is invalid. Ensure it is properly formatted." } } } } } }, "401": { "description": "Unauthorized - The request requires user authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided. Please include your authentication token in the request headers." } } } } } }, "403": { "description": "Forbidden - The server understood the request, but refuses to authorize it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "Not Found - The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The connector you're looking for does not exist. Please check the connector ID and try again." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/builder/marketplace/muscles": { "get": { "summary": "Retrieve active muscles for organization", "description": "Explore the vibrant ecosystem of skills, known as 'muscles', installed in your organization’s HUMAN platform. This endpoint is your gateway to discovering the active tools your team has harnessed, ensuring seamless task orchestration and AI collaboration.", "operationId": "getMarketplaceMuscles", "tags": [ "Marketplace", "Organization" ], "x-code-hash": "04002ed719ac083c", "x-generated-at": "2026-04-01T23:29:46.297Z", "responses": { "200": { "description": "List of active muscles for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "muscle_id": { "type": "string", "description": "The unique identifier for the muscle." }, "asset_id": { "type": "string", "description": "The identifier of the associated marketplace asset." }, "name": { "type": "string", "description": "The name of the marketplace asset." }, "slug": { "type": "string", "description": "A URL-friendly identifier for the asset." } }, "required": [ "muscle_id", "asset_id", "name", "slug" ] } } } }, "examples": { "acme_corp_muscle_retrieval": { "summary": "Acme Corp Muscle Retrieval", "description": "Acme Corp retrieves a list of their active marketplace muscles.", "value": { "data": [ { "muscle_id": "muscle-001", "asset_id": "asset-101", "name": "Invoice Processor", "slug": "invoice-processor" }, { "muscle_id": "muscle-002", "asset_id": "asset-202", "name": "Data Anonymizer", "slug": "data-anonymizer" } ] } } } } } }, "400": { "description": "The request could not be understood by the server due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request": { "summary": "Malformed Request", "description": "A request with incorrect syntax leading to a 400 error.", "value": { "type": "https://humanprotocol.org/errors/400", "title": "Bad Request", "status": 400, "detail": "Invalid request syntax." } } } } } }, "401": { "description": "User is not authenticated.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "A request made without authentication.", "value": { "type": "https://humanprotocol.org/errors/401", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "User does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "A request made with insufficient permissions.", "value": { "type": "https://humanprotocol.org/errors/403", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "A request for a resource that does not exist.", "value": { "type": "https://humanprotocol.org/errors/404", "title": "Not Found", "status": 404, "detail": "The specified resource was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An example of a server-side error.", "value": { "type": "https://humanprotocol.org/errors/500", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/builder/marketplace/policy-packs": { "get": { "summary": "Retrieve available policy packs", "description": "Explore the curated collection of policy packs designed to enhance your Human-AI orchestration with standardized governance and compliance measures. This endpoint is your gateway to understanding the safeguards in place for secure and auditable AI operations.", "operationId": "getMarketplacePolicyPacks", "tags": [ "Marketplace", "Policy" ], "x-code-hash": "137571112889544f", "x-generated-at": "2026-04-01T23:30:00.417Z", "responses": { "200": { "description": "A list of policy packs successfully retrieved from the marketplace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the policy pack." }, "name": { "type": "string", "description": "The name of the policy pack." }, "description": { "type": "string", "description": "A brief description of the policy pack's purpose and features." } }, "required": [ "id", "name", "description" ] } } }, "required": [ "data" ] }, "examples": { "default_policy_pack_example": { "summary": "Default policy pack example", "description": "An example of a policy pack with governance features.", "value": { "data": [ { "id": "policy-pack-governed-default", "name": "Governed default", "description": "Requires audit logging and approval on external delivery." } ] } } } } } }, "400": { "description": "Bad Request - The request was malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/bad-request", "title": "Invalid request parameters", "status": 400, "detail": "The request contained invalid parameters. Please verify the parameters and try again.", "errors": [ "Missing required parameter: XYZ" ] } } } } } }, "401": { "description": "Unauthorized - Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/unauthorized", "title": "Unauthorized access", "status": 401, "detail": "Authentication is required. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden - You do not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/forbidden", "title": "Access denied", "status": 403, "detail": "You do not have permission to view this resource. Contact your administrator for access." } } } } } }, "404": { "description": "Not Found - The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/not-found", "title": "Resource not found", "status": 404, "detail": "The policy pack you are looking for does not exist. Please check the ID and try again." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/internal-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/builder/marketplace/policy-packs/:pid/apply": { "post": { "summary": "Apply a Policy Pack to Marketplace", "description": "This endpoint allows you to apply a specified policy pack to a marketplace, ensuring the seamless integration of compliance and security measures. By orchestrating policy applications, HUMAN facilitates a streamlined approach to managing marketplace operations with confidence.", "operationId": "applyPolicyPack", "tags": [ "Marketplace", "Policy Management" ], "x-code-hash": "413d2fc1bcfd626b", "x-generated-at": "2026-04-01T23:30:15.760Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean", "description": "If true, the policy pack will not actually be applied, allowing you to preview any changes." } }, "required": [] }, "examples": { "simulate_policy_application": { "summary": "Simulate Policy Application", "description": "Demonstrating a dry run to preview policy effects without applying them.", "value": { "dry_run": true } } } } } }, "responses": { "200": { "description": "The policy pack was successfully applied to the marketplace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "applied": { "type": "boolean", "description": "Indicates whether the policy pack was applied." }, "pack_id": { "type": "string", "description": "The unique identifier of the applied policy pack." } } }, "examples": { "successful_application": { "summary": "Successful Application", "description": "The policy pack was applied to the marketplace with ID `pid-12345`.", "value": { "applied": true, "pack_id": "pid-12345" } } } } } }, "400": { "description": "Bad Request due to invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_json_format": { "summary": "Invalid JSON Format", "description": "The request payload was not in valid JSON format.", "value": { "type": "/errors/bad-request", "title": "Invalid Request", "status": 400, "detail": "The request payload is not valid JSON." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request lacked valid authentication credentials.", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have permission to apply the policy pack.", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to apply this policy pack." } } } } } }, "404": { "description": "Policy pack or marketplace not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "policy_pack_not_found": { "summary": "Policy Pack Not Found", "description": "The specified policy pack ID does not exist.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified policy pack or marketplace could not be found." } } } } } }, "500": { "description": "Internal server error due to unexpected issues", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An unexpected server error occurred during the request.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while applying the policy pack." } } } } } } } } }, "/v1/builder/connectors": { "get": { "summary": "Retrieve organization connector credentials", "description": "Dive into the heart of connectivity! This endpoint fetches a curated list of connector credentials tied to your organization. Designed for seamless integration, it ensures that your connectors are up-to-date and ready to handle your organization's demands, showcasing their status and health.", "operationId": "getBuilderConnectors", "tags": [ "Connectors", "Integration" ], "x-code-hash": "d510f71f0ede9716", "x-generated-at": "2026-04-01T23:30:30.073Z", "responses": { "200": { "description": "A list of connector credentials with their status and health for the specified organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connector_id": { "type": "string" }, "scope": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health": { "type": "string" } }, "required": [ "id", "connector_id", "status", "created_at", "updated_at", "health" ] } } } }, "examples": { "acme_corp_connector_credentials": { "summary": "Acme Corp Connector Credentials", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "connector_id": "slack", "scope": "chat:write", "status": "active", "created_at": "2023-01-15T08:00:00Z", "updated_at": "2023-10-10T08:00:00Z", "health": "ok" }, { "id": "123e4567-e89b-12d3-a456-426614174001", "connector_id": "github", "scope": "repo:status", "status": "inactive", "created_at": "2022-05-05T10:00:00Z", "updated_at": "2023-09-25T10:00:00Z", "health": "unknown" } ] } } } } } }, "400": { "description": "Bad Request due to missing organization context", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized access error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Invalid or missing authentication token. Please provide a valid token to access this resource." } } } } } }, "403": { "description": "Forbidden error due to lack of permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Contact your administrator for access." } } } } } }, "404": { "description": "Resource not found error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested connector credentials could not be found for the specified organization." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/builder/connectors/:cid/connect": { "post": { "summary": "Initiate OAuth Flow for Connector", "description": "This endpoint empowers organizations to seamlessly start an OAuth authentication process for a specified connector, ensuring secure connectivity and identity delegation. It exists to facilitate secure integrations while maintaining human oversight in AI orchestration.", "operationId": "initiateConnectorOAuthFlow", "tags": [ "Connectors", "Authentication" ], "x-code-hash": "3cd7d3034ca24ba9", "x-generated-at": "2026-04-01T23:31:07.091Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "type": "string", "description": "URL to redirect after authorization" } }, "required": [] }, "examples": { "oauth_initiation_with_return_url": { "summary": "OAuth Initiation with Return URL", "description": "Starts the OAuth process and specifies where to redirect upon completion.", "value": { "return_url": "https://acme.com/oauth/callback" } } } } } }, "responses": { "200": { "description": "OAuth flow successfully initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization_url": { "type": "string", "description": "URL to proceed with OAuth authorization" }, "oauth_state": { "type": "string", "description": "State parameter for OAuth session" }, "redirect_uri": { "type": "string", "description": "The URI to redirect after OAuth" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration time of the OAuth session" }, "installation_id": { "type": "string", "description": "Identifier for the installation process" }, "return_url": { "type": [ "string", "null" ], "description": "Original return URL if provided" } }, "required": [ "authorization_url", "oauth_state", "redirect_uri", "expires_at", "installation_id" ] }, "examples": { "successful_oauth_flow_initiation": { "summary": "Successful OAuth Flow Initiation", "description": "The OAuth process is started, providing URLs for user redirection.", "value": { "authorization_url": "https://oauth.provider.com/auth", "oauth_state": "randomlyGeneratedState", "redirect_uri": "https://acme.com/oauth/callback", "expires_at": "2023-11-01T12:30:00Z", "installation_id": "install-12345", "return_url": "https://acme.com/oauth/callback" } } } } } }, "400": { "description": "Bad Request: Organization context missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "The request lacks the necessary organization context, leading to a failure in initiating the OAuth process.", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized: Delegation token required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "description": "A delegation token is needed to authenticate the request.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Delegation token required" } } } } } }, "404": { "description": "Not Found: Connector not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "connector_id_not_found": { "summary": "Connector ID Not Found", "description": "The specified connector ID does not exist within the organization.", "value": { "type": "https://haio.run/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "connector not found" } } } } } }, "422": { "description": "Unprocessable Entity: OAuth not configured", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "oauth_configuration_missing": { "summary": "OAuth Configuration Missing", "description": "The connector's manifest lacks OAuth configuration, preventing the flow initiation.", "value": { "type": "https://haio.run/errors/validation", "title": "OAuth not configured for this connector", "status": 422, "detail": "This connector does not declare OAuth in its manifest. Use API key storage or install via Marketplace with the required auth method." } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An unknown issue occurred while processing the request.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/builder/connectors/:cid/test": { "post": { "summary": "Test connectivity for a specific connector", "description": "In the ever-evolving landscape of Human-AI orchestration, ensuring smooth communication channels is key. This endpoint lets you verify the live connectivity of a specified connector, using a quick probe, to ensure seamless task routing and skill tracking within the HUMAN ecosystem.", "operationId": "testConnectorConnectivity", "tags": [ "Connectors", "Diagnostics" ], "x-code-hash": "1d5b8a70f5f9e9d1", "x-generated-at": "2026-04-01T23:31:22.235Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "probe": { "type": "string", "description": "A test string sent to the connector to evaluate its responsiveness." } } }, "examples": { "basic_probe_example": { "summary": "Basic Probe Example", "description": "Sending a simple probe to test connectivity.", "value": { "probe": "ping" } } } } } }, "responses": { "200": { "description": "The connector responded successfully, indicating live connectivity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Indicates the success of the connectivity test." }, "connector_id": { "type": "string", "description": "The unique identifier of the connector tested." }, "latency_ms": { "type": "integer", "description": "The time in milliseconds it took to get a response from the connector." } } }, "examples": { "successful_connectivity_test": { "summary": "Successful Connectivity Test", "value": { "ok": true, "connector_id": "acme123", "latency_ms": 15 } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The probe must be a string. Ensure your JSON body is correctly formatted." } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided. Ensure you have included a valid Passport token." } } } } } }, "403": { "description": "Forbidden request as the user lacks necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to test this connector. Check your access rights." } } } } } }, "404": { "description": "Connector not found with the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The connector with the specified ID does not exist. Verify the connector ID and try again." } } } } } }, "500": { "description": "Internal server error while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while testing the connector. Please try again later." } } } } } } } } }, "/v1/builder/connectors/:cid/disconnect": { "post": { "summary": "Disconnect a connector for an organization", "description": "In the HUMAN ecosystem, managing your connector's lifecycle is crucial for maintaining operational integrity. This endpoint allows organizations to disconnect a specific connector, ensuring security by revoking access and updating the connector's status. It's a vital tool for organizations aiming to maintain a secure and up-to-date environment.", "operationId": "disconnectConnector", "tags": [ "Connectors", "Organization" ], "x-code-hash": "d582c3f0a9d51570", "x-generated-at": "2026-04-01T23:31:34.945Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revoke_tokens": { "type": "boolean", "description": "Indicate if tokens should be revoked during the disconnect process" } }, "required": [] }, "examples": { "revoke_tokens_example": { "summary": "Revoke tokens example", "description": "Demonstrates disconnecting a connector and revoking its tokens", "value": { "revoke_tokens": true } } } } } }, "responses": { "200": { "description": "Successfully disconnected the connector for the specified organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "disconnected": { "type": "boolean", "description": "Indicates the connector was successfully disconnected" } } }, "examples": { "default": { "summary": "Example", "value": { "disconnected": true } } } } } }, "400": { "description": "Bad request due to missing organization context", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden request when the user lacks permission to disconnect the connector", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Connector not found for the provided ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error during connector disconnection", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/academy/skill-events": { "post": { "summary": "Capture Skill Event with Builder Completion", "description": "This endpoint allows the HUMAN platform to record the completion of an AcademyMoment by a user, along with any associated skill signals. It enhances the platform's knowledge about a user's capabilities and progress, ensuring a more personalized and effective task routing experience.", "operationId": "postSkillEvent", "tags": [ "Academy", "SkillTracking" ], "x-code-hash": "5129fea602026724", "x-generated-at": "2026-04-01T22:11:11.787Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_did": { "type": "string", "description": "The decentralized identifier (DID) of the user. Optional if delegation is provided." }, "skill_id": { "type": "string", "description": "The identifier for the skill being logged." }, "event_type": { "type": "string", "description": "The type of event being recorded, such as 'completion' or 'initiation'." }, "context": { "type": "object", "description": "Additional context about the event, provided as a key-value map." } }, "required": [ "skill_id", "event_type" ] }, "examples": { "skill_completion_by_user": { "summary": "Skill Completion by User", "description": "Logs a skill completion event for a user with a corresponding skill and context.", "value": { "user_did": "did:example:123456789abcdefghi", "skill_id": "skill:acme:invoice-processing", "event_type": "completion", "context": { "location": "online", "timestamp": "2023-10-15T14:48:00.000Z" } } } } } } }, "responses": { "200": { "description": "The skill event was successfully logged, returning the event ID and timestamp.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the logged skill event." }, "occurred_at": { "type": "string", "format": "date-time", "description": "The timestamp when the event was recorded." } } }, "examples": { "default": { "summary": "Example", "value": { "id": "evt_01F8ZK9Z4TJ1T9Y3V7Q4GV8G5D", "occurred_at": "2023-10-15T14:50:00.000Z" } } } } } }, "400": { "description": "The request was malformed, such as missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "user_did (or authenticated delegation), skill_id, and event_type are required.", "errors": [ { "field": "user_did", "code": "REQUIRED_FIELD_MISSING", "message": "user_did is required when no delegation is provided." } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Permission error due to insufficient access rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The skill ID 'skill:acme:nonexistent-skill' does not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/builder/import": { "post": { "summary": "Import and draft external workflow", "description": "Breathe life into your workflow library by importing external agent or workflow definitions. This endpoint empowers organizations to craft an initial draft of a builder workflow, ensuring seamless integration with existing processes. Whether you're migrating with capability overrides or specifying platform hints, this operation is your gateway to a refined orchestration setup.", "operationId": "builderImportWorkflow", "tags": [ "Workflow", "Import" ], "x-code-hash": "6af396aeededb15a", "x-generated-at": "2026-04-01T23:39:29.994Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "string", "description": "Base64 encoded agent or workflow definition." }, "platform_hint": { "type": "string", "description": "Optional hint about the target platform." }, "capability_overrides": { "type": "object", "description": "Optional per-step capability overrides.", "additionalProperties": { "type": "string" } }, "name": { "type": "string", "description": "Optional workflow name. Defaults to 'Imported workflow'." } }, "required": [ "payload" ] }, "examples": { "simple_import": { "summary": "Simple Import", "description": "Import a basic workflow with no platform hint or overrides.", "value": { "payload": "c29tZS1iYXNlNjQtcGF5bG9hZA==", "name": "Invoice Processor" } } } } } }, "responses": { "201": { "description": "The workflow was successfully imported and a draft was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string", "description": "Unique identifier for the created workflow." }, "builder_url": { "type": "string", "description": "URL to view the workflow in the builder." }, "rung": { "type": "integer", "description": "Migration rung achieved during import." }, "step_summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of steps in the workflow." }, "mapped_native": { "type": "integer", "description": "Number of steps mapped natively." }, "wrapper": { "type": "integer", "description": "Number of steps using wrappers." }, "approval_gates": { "type": "integer", "description": "Number of steps requiring approval." } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "suggested_connectors": { "type": "array", "items": { "type": "string" } } } }, "examples": { "default": { "summary": "Example", "value": { "workflow_id": "wf_12345", "builder_url": "https://console.haio.run/builder/wf_12345", "rung": 2, "step_summary": { "total": 10, "mapped_native": 8, "wrapper": 1, "approval_gates": 1 }, "warnings": [ "Step 5 uses deprecated API" ], "suggested_connectors": [ "capability://email/send" ] } } } } } }, "400": { "description": "Bad request due to missing or invalid organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Invalid API key or token." } } } } } }, "403": { "description": "Forbidden due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "Insufficient permissions to import workflows." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested workflow template does not exist." } } } } } }, "500": { "description": "Internal server error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/migration-status": { "get": { "summary": "Retrieve workflow migration status", "description": "Delve into the lifecycle of your workflow as it transitions through updates. This endpoint provides insights into the current migration status, ensuring that your operations remain seamless and informed.", "operationId": "getWorkflowMigrationStatus", "tags": [ "Workflows", "Migration" ], "x-code-hash": "07e34e6f901c137c", "x-generated-at": "2026-04-01T23:22:22.547Z", "responses": { "200": { "description": "Returns the current migration status of the specified workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The current migration status", "enum": [ "pending", "in-progress", "completed", "failed" ] }, "details": { "type": "string", "description": "Additional information about the migration status" } } }, "examples": { "workflow_migration_status_example": { "summary": "Workflow Migration Status Example", "description": "An example showing a completed migration status for a workflow.", "value": { "status": "completed", "details": "The workflow migration completed successfully without any issues." } } } } } }, "400": { "description": "The organization context is missing in the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "Occurs when the organization ID is not present in the request.", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Authentication required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "Occurs when the request lacks valid authentication credentials.", "value": { "type": "https://haio.run/errors/authentication", "title": "Authentication required", "status": 401, "detail": "Valid authentication credentials are required." } } } } } }, "403": { "description": "Permission denied to access this workflow's migration status.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "Occurs when the user lacks sufficient permissions to access the resource.", "value": { "type": "https://haio.run/errors/authorization", "title": "Permission denied", "status": 403, "detail": "You do not have permission to view this workflow's migration status." } } } } } }, "404": { "description": "The specified workflow could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "workflow_not_found": { "summary": "Workflow Not Found", "description": "Occurs when the specified workflow ID does not exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "The workflow with the specified ID was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A generic error indicating something went wrong on the server.", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/workflows/:id/steps/:stepId/upgrade-to-capability": { "patch": { "summary": "Upgrade Workflow Step to Capability", "description": "Elevate your workflow step by enhancing its capabilities. This endpoint allows an organization to upgrade a specific step in a workflow, ensuring it meets new requirements and capabilities essential for advanced processing. By harnessing the power of the Capability Graph, organizations can track and adapt skill requirements dynamically.", "operationId": "upgradeWorkflowStepToCapability", "tags": [ "Workflows", "Capabilities" ], "x-code-hash": "bd67b7c9815c7555", "x-generated-at": "2026-04-01T23:22:37.095Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "required_capabilities": { "type": "array", "items": { "type": "string" } }, "required_connectors": { "type": "array", "items": { "type": "string" } } }, "required": [ "required_capabilities" ] }, "examples": { "upgrade_with_new_capabilities": { "summary": "Upgrade with New Capabilities", "description": "Upgrade the workflow step to include 'capability://ai.ocr' and 'capability://data.validation'.", "value": { "required_capabilities": [ "capability://ai.ocr", "capability://data.validation" ], "required_connectors": [ "connector://storage.s3" ] } } } } } }, "responses": { "200": { "description": "The workflow step was successfully upgraded with the new capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "description": "The updated workflow object." }, "rung_before": { "type": "integer", "description": "The previous capability rung level." }, "rung_after": { "type": "integer", "description": "The new capability rung level." } } }, "examples": { "default": { "summary": "Example", "value": { "workflow": { "id": "workflow-123", "org_id": "org-acme", "manifest": { "steps": [ { "id": "step-456", "name": "Process Invoice" } ] }, "version": 2 }, "rung_before": 2, "rung_after": 3 } } } } } }, "400": { "description": "Invalid input was provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid request body", "status": 400, "detail": "required_capabilities must be a non-empty string array", "errors": [ { "field": "required_capabilities", "code": "REQUIRED_FIELD_MISSING", "message": "required_capabilities must be a non-empty string array", "expected": "string[]", "received": "null" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/permissions", "title": "Forbidden", "status": 403, "detail": "You do not have permission to upgrade this workflow step." } } } } } }, "404": { "description": "The specified workflow or step was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The workflow or step with the given ID does not exist." } } } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/builder/analyze": { "post": { "summary": "Preview migration of workflows and agents", "description": "Embark on a journey to modernize your workflows effortlessly with this endpoint. By analyzing the structure and components of your intended migration, it offers insights into potential steps, prompts, and warnings, all while ensuring no data is prematurely committed. This vital preview phase helps you make informed decisions before taking the plunge with POST /import.", "operationId": "builderAnalyzeMigration", "tags": [ "Migration", "Analysis" ], "x-code-hash": "4563a46e6d1c9ef5", "x-generated-at": "2026-04-01T23:38:53.889Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "description": "The target platform for migration." }, "workflow": { "type": "object", "description": "Details of the workflow to be migrated.", "properties": { "name": { "type": "string", "description": "The name of the workflow." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "description": "Unique identifier for the step." }, "action": { "type": "string", "description": "The action to be performed at this step." } } } } } } }, "required": [ "platform", "workflow" ] }, "examples": { "basic_workflow_migration": { "summary": "Basic Workflow Migration", "description": "A simple workflow migration to the 'acme' platform.", "value": { "platform": "acme", "workflow": { "name": "Invoice Processing", "steps": [ { "stepId": "step1", "action": "Validate Invoice" }, { "stepId": "step2", "action": "Approve Payment" } ] } } } } } } }, "responses": { "200": { "description": "The analysis was successful, providing a comprehensive overview of the migration steps, potential prompts, and warnings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "description": "Statistical summary of the migration analysis.", "properties": { "totalSteps": { "type": "integer", "description": "Total number of steps in the workflow." }, "warnings": { "type": "integer", "description": "Number of warnings identified during analysis." } } }, "steps": { "type": "array", "description": "Detailed list of steps identified in the migration.", "items": { "type": "string" } }, "prompts": { "type": "array", "description": "Suggested prompts for user interaction during the migration.", "items": { "type": "string" } }, "warnings": { "type": "array", "description": "List of warnings to consider before proceeding with the migration.", "items": { "type": "string" } } } }, "examples": { "default": { "summary": "Example", "value": { "stats": { "totalSteps": 2, "warnings": 1 }, "steps": [ "Validate Invoice", "Approve Payment" ], "prompts": [ "Ensure invoice is not duplicated." ], "warnings": [ "Step 'Approve Payment' requires additional permissions." ] } } } } } }, "400": { "description": "The request was invalid due to missing or malformed data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Organization required", "status": 400, "detail": "org context missing" } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested workflow details could not be found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/workforce/work-items/:work_item_id/stream": { "get": { "summary": "Stream Workforce Work Item Updates", "description": "Dive into the heart of your operations by streaming real-time updates for a specific work item. This endpoint ensures you're always in sync, providing live status changes and actions performed on your work items, crucial for time-sensitive tasks and responsive workflows.", "operationId": "getWorkItemStream", "tags": [ "Workforce", "Real-Time Updates" ], "x-code-hash": "dd34964fbb0a898d", "x-generated-at": "2026-04-02T20:09:17.400Z", "responses": { "200": { "description": "Stream of events related to the work item, including status updates and terminal state notifications.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "description": "Type of the event, such as 'connected', 'work_item', or 'terminal'." }, "data": { "type": "object", "description": "Data related to the event. Varies by event type.", "properties": { "work_item_id": { "type": "string", "description": "Identifier for the work item." }, "org_did": { "type": "string", "description": "Decentralized identifier for the organization." }, "poll_ms": { "type": "integer", "description": "Polling interval in milliseconds." }, "status": { "type": "string", "description": "Current status of the work item." } } } } }, "examples": { "connected_event": { "summary": "Connected Event", "value": { "event": "connected", "data": { "work_item_id": "123e4567-e89b-12d3-a456-426614174000", "org_did": "did:example:acme", "poll_ms": 1500 } } } } } } }, "400": { "description": "Client error due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_work_item_id": { "summary": "Missing work_item_id", "value": { "type": "https://example.com/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "One or more fields have validation errors", "errors": [ { "field": "work_item_id", "code": "REQUIRED_FIELD", "message": "work_item_id path parameter is required", "expected": "string", "received": "empty" } ] } } } } } }, "401": { "description": "Authentication error due to missing delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Authorization error due to mismatched organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_mismatch": { "summary": "Organization Mismatch", "value": { "type": "https://example.com/probs/authorization-error", "title": "Authorization Error", "status": 403, "detail": "Delegation org does not match requested organization" } } } } } }, "404": { "description": "Error when the specified work item is not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "work_item_not_found": { "summary": "Work Item Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Work item not found" } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "stream_error": { "summary": "Stream Error", "value": { "type": "https://example.com/probs/stream-error", "title": "Stream Error", "status": 500, "detail": "An unexpected error occurred in the stream" } } } } } } } } }, "/v1/passports/:id/api-signing-keys": { "post": { "summary": "Create a new API signing key", "description": "This endpoint allows you to create a named Human API signing key linked to a specific passport. API signing keys are essential for securing session-based operations, ensuring that all interactions are traceable to a verified identity. This feature provides an additional layer of security and traceability within the HUMAN ecosystem.", "operationId": "createApiSigningKey", "tags": [ "Identity", "Security" ], "x-code-hash": "c8b41cfd8254ac7e", "x-generated-at": "2026-04-11T02:02:44.092Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "A human-readable label for the API signing key. Maximum 128 characters." } }, "required": [ "label" ] }, "examples": { "create_api_signing_key": { "summary": "Create API Signing Key", "description": "Creating a signing key for the 'acme-invoice-processing' application.", "value": { "label": "acme-invoice-processing-key" } } } } } }, "responses": { "201": { "description": "API signing key successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The unique identifier of the created API signing key." }, "public_key": { "type": "string", "description": "The public key component of the API signing key." }, "fingerprint": { "type": "string", "description": "The fingerprint of the public key for quick identification." }, "label": { "type": "string", "description": "The label of the created API signing key." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API signing key was created." } } }, "examples": { "successful_creation_response": { "summary": "Successful creation response", "description": "Response after successfully creating a signing key for 'acme-invoice-processing'.", "value": { "key_id": "hask_123456789", "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAn...", "fingerprint": "3F:9F:6B:2D:EE:4A:08:3B:4B:54:C6:03:9C:2D:7C:1D", "label": "acme-invoice-processing-key", "created_at": "2023-10-21T14:32:28Z" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing/invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "The request body is invalid.", "errors": [ { "field": "label", "code": "REQUIRED_FIELD_MISSING", "message": "label is required", "expected": "non-empty string", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid session.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Session passport does not match path id." } } } } } }, "403": { "description": "Forbidden access due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create an API signing key for this passport." } } } } } }, "404": { "description": "Passport not found or inactive.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Passport with ID 'did:example:1234' not found or inactive." } } } } } }, "500": { "description": "Internal server error during key creation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while creating the API signing key. Please contact support with incident ID inc_1697891234567." } } } } } } } }, "get": { "summary": "Retrieve active API signing keys", "description": "Discover the active cryptographic keys that secure communications with HUMAN API. This endpoint is vital for ensuring the integrity and authenticity of interactions by listing the valid keys tied to a Passport, empowering trusted integration.", "operationId": "getPassportApiSigningKeys", "tags": [ "Identity", "Security" ], "x-code-hash": "e466f62370a1c201", "x-generated-at": "2026-04-11T02:02:58.824Z", "responses": { "200": { "description": "A list of active API signing keys for the specified Passport, with pagination support.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": "string" }, "label": { "type": "string" }, "fingerprint": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "example_of_active_keys": { "summary": "Example of active keys", "description": "Shows a Passport with multiple active API signing keys and pagination.", "value": { "data": [ { "key_id": "key_123", "label": "Primary Key", "fingerprint": "SHA256:abcd1234...", "created_at": "2023-10-01T12:34:56Z", "last_used_at": "2023-10-10T09:30:00Z" }, { "key_id": "key_456", "label": "Backup Key", "fingerprint": "SHA256:efgh5678...", "created_at": "2023-09-15T08:20:00Z", "last_used_at": null } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Bad request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid limit parameter", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid Query Parameters", "status": 400, "detail": "The 'limit' parameter must be a positive integer." } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_valid_authentication": { "summary": "No valid authentication", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must provide valid authentication credentials." } } } } } }, "403": { "description": "Forbidden access when Passport does not match the session.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "session_mismatch": { "summary": "Session mismatch", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Session passport does not match path id." } } } } } }, "404": { "description": "Passport not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "nonexistent_passport": { "summary": "Nonexistent passport", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No Passport found with the specified id." } } } } } }, "500": { "description": "Server error occurred while retrieving API signing keys.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/api-signing-keys/:keyId": { "get": { "summary": "Retrieve specific API signing key metadata", "description": "Explore the cryptographic essence of your identity with the Passport's API signing key metadata. This endpoint unveils the details of a specific active key, enabling secure and traceable interactions within the HUMAN network. Discover when it was created, its fingerprint, and more, as you navigate the digital realm with confidence.", "operationId": "getApiSigningKeyMetadata", "tags": [ "Identity", "Security" ], "x-code-hash": "e06dfdb58f9dbcb7", "x-generated-at": "2026-04-11T02:03:13.042Z", "responses": { "200": { "description": "Returns metadata for the specified API signing key", "content": { "application/json": { "schema": { "type": "object", "properties": { "key_id": { "type": "string", "description": "Unique identifier for the API signing key" }, "label": { "type": "string", "description": "Human-readable label for the key" }, "fingerprint": { "type": "string", "description": "Base64-encoded fingerprint of the public key" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of key creation" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of last key usage, if applicable" } } }, "examples": { "successful_retrieval_of_key_metadata": { "summary": "Successful retrieval of key metadata", "value": { "key_id": "key_12345", "label": "Invoice Processing Key", "fingerprint": "abc123base64encodedfingerprint==", "created_at": "2023-10-01T14:30:00Z", "last_used_at": "2023-10-15T09:00:00Z" } } } } } }, "400": { "description": "Bad request due to invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_key_id_format": { "summary": "Invalid key ID format", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-parameter", "title": "Invalid Parameter", "status": 400, "detail": "The keyId provided is not in a valid format. Please ensure it follows the correct structure.", "errors": [ "keyId must be a valid UUID" ] } } } } } }, "401": { "description": "Unauthorized access due to invalid session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_session_token": { "summary": "Invalid session token", "value": { "type": "https://docs.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "The session token is invalid or expired. Please log in again to obtain a new session." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "session_passport_mismatch": { "summary": "Session passport mismatch", "value": { "type": "https://docs.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "The session passport does not match the path ID. Ensure you are using the correct account." } } } } } }, "404": { "description": "The requested API signing key could not be found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "non-existent_key_id": { "summary": "Non-existent key ID", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "No active API signing key found with the specified ID. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected failure", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_query_failure": { "summary": "Database query failure", "value": { "type": "https://docs.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the API signing key metadata. If the problem persists, contact support with the incident ID: inc_1697059200000." } } } } } } } }, "delete": { "summary": "Revoke a Human API Signing Key", "description": "This endpoint allows you to revoke an API signing key associated with a Human Passport. By invalidating the specified key, you ensure that it can no longer be used to authenticate requests, enhancing security and control over your API access. This is particularly useful when a key is compromised or no longer needed.", "operationId": "revokeApiSigningKey", "tags": [ "Access Control", "Security" ], "x-code-hash": "43bad943c5a6621a", "x-generated-at": "2026-04-11T02:03:23.648Z", "responses": { "204": { "description": "The API signing key was successfully revoked.", "content": { "application/json": {} } }, "400": { "description": "Bad request due to malformed parameters or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_keyid_format": { "summary": "Invalid KeyId Format", "description": "Occurs when the keyId format does not match the expected pattern.", "value": { "type": "https://humanprotocol.org/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The provided keyId format is invalid." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "Occurs when the request does not include valid authentication tokens.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Occurs when the user does not have the necessary rights to revoke the key.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to revoke this key." } } } } } }, "404": { "description": "Not found error when the specified key does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "nonexistent_key": { "summary": "Nonexistent Key", "description": "Occurs when attempting to revoke a key that does not exist.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The API signing key with the specified ID was not found." } } } } } }, "500": { "description": "Internal server error due to unexpected failures.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Occurs when there is a failure in processing the request due to server-side issues.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/passports/:id/delegate": { "post": { "summary": "Delegate Capabilities with JWT", "description": "This endpoint allows the creation of a delegation JWT from an issuer's passport, enabling secure sharing of capabilities. By delegating specific roles and permissions, organizations and agents can orchestrate tasks efficiently while maintaining control over access and expiry.", "operationId": "createDelegationJwt", "tags": [ "Identity", "Delegation" ], "x-code-hash": "cf661e94734e1da7", "x-generated-at": "2026-04-11T02:04:13.454Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toPassportId": { "type": "string", "description": "The DID of the passport receiving the delegation." }, "scope": { "type": "array", "items": { "type": "string" }, "description": "Array of capability IDs to be delegated." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional expiration date for the delegation." }, "resources": { "type": "array", "items": { "type": "string" }, "description": "Optional list of resource identifiers." }, "conditions": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "dev", "staging", "production" ] }, "riskLevel": { "type": "string", "enum": [ "low", "standard", "high" ] }, "maxUses": { "type": "integer" }, "regions": { "type": "array", "items": { "type": "string" } } }, "description": "Optional constraints for the delegation." }, "signing_key_id": { "type": "string", "description": "Optional ID for Human API signing key, required for human issuers." } }, "required": [ "toPassportId", "scope" ] }, "examples": { "delegating_invoice_processing": { "summary": "Delegating Invoice Processing", "description": "Delegating invoice processing capabilities to an agent in the 'acme' organization.", "value": { "toPassportId": "did:human:1234abc", "scope": [ "capability://finance/invoice.process" ], "expiresAt": "2024-12-31T23:59:59Z", "resources": [ "resource://acme/invoices" ], "conditions": { "environment": "production", "riskLevel": "standard", "maxUses": 10, "regions": [ "us-east-1", "eu-west-1" ] } } } } } } }, "responses": { "201": { "description": "Delegation successfully created and JWT returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_id": { "type": "string" }, "from_passport_id": { "type": "string" }, "to_passport_id": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string" } }, "resources": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "conditions": { "type": "object", "properties": { "environment": { "type": "string" }, "riskLevel": { "type": "string" }, "maxUses": { "type": "integer" }, "regions": { "type": "array", "items": { "type": "string" } } } }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "delegation_token": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "delegation_id": "dtok_5678def", "from_passport_id": "did:human:5678def", "to_passport_id": "did:human:1234abc", "scope": [ "capability://finance/invoice.process" ], "resources": [ "resource://acme/invoices" ], "status": "active", "conditions": { "environment": "production", "riskLevel": "standard", "maxUses": 10, "regions": [ "us-east-1", "eu-west-1" ] }, "expires_at": "2024-12-31T23:59:59Z", "created_at": "2023-10-01T12:00:00Z", "delegation_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } }, "400": { "description": "Invalid input data, such as missing required fields or incorrect formats.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "One or more validation errors occurred.", "errors": [ { "field": "scope", "code": "VALUE_OUT_OF_RANGE", "message": "Scope must include at least one capability", "expected": "array with at least one capability ID", "received": "empty or invalid array" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid Bearer token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/authentication-failed", "title": "Authentication Failed", "status": 401, "detail": "Bearer token is missing or invalid. Ensure you provide a valid token." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to delegate these capabilities. Check your access rights." } } } } } }, "404": { "description": "The specified passport or resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested passport ID was not found. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error due to unforeseen issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with the incident ID." } } } } } } } } }, "/v1/passports/:id/recovery/guardian/:requestId/approve": { "post": { "summary": "Approve recovery request as guardian", "description": "This endpoint empowers guardians to affirm their role in the recovery process, crucial for securing cryptographic identities within the HUMAN platform. By approving a recovery request, guardians help ensure that only authorized users can reclaim their digital identities, safeguarding against unauthorized access or loss.", "operationId": "approveGuardianRecovery", "tags": [ "Passport", "Recovery" ], "x-code-hash": "e2bf34427ecfad51", "x-generated-at": "2026-04-12T15:57:50.433Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shard_b64": { "type": "string", "description": "Plaintext shard in base64url encoding, required in SSS mode." }, "signature": { "type": "string", "description": "Optional signature for audit trail in attestation mode." } }, "additionalProperties": false }, "examples": { "sss_mode_approval": { "summary": "SSS Mode Approval", "description": "Guardian approving with a plaintext shard in SSS mode.", "value": { "shard_b64": "c2hhcmRTYW1wbGU" } }, "attestation_mode_approval": { "summary": "Attestation Mode Approval", "description": "Guardian approving in attestation mode with a signature.", "value": { "signature": "0xabc123signatureExample" } } } } } }, "responses": { "200": { "description": "Guardian approval successfully registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifier of the recovery request." }, "approvals_received": { "type": "integer", "description": "Number of approvals received so far." }, "approvals_required": { "type": "integer", "description": "Total approvals required to proceed." }, "threshold_met": { "type": "boolean", "description": "Indicates if the threshold of approvals has been met." }, "lock_until": { "type": "string", "format": "date-time", "description": "The ISO 8601 timestamp until which the recovery is locked." }, "ready_to_complete": { "type": "boolean", "description": "True if the recovery request is ready for completion." } }, "required": [ "request_id", "approvals_received", "approvals_required", "threshold_met", "lock_until", "ready_to_complete" ] }, "examples": { "successful_approval": { "summary": "Successful Approval", "description": "A guardian's approval has been successfully processed.", "value": { "request_id": "req_12345", "approvals_received": 3, "approvals_required": 5, "threshold_met": false, "lock_until": "2023-12-31T12:00:00Z", "ready_to_complete": false } } } } } }, "400": { "description": "Invalid request data or format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_shard_format": { "summary": "Invalid Shard Format", "description": "The provided shard is not in the correct base64url format.", "value": { "type": "https://humanlayer.io/errors/invalid-format", "title": "Invalid Shard Format", "status": 400, "detail": "The shard must be provided in base64url encoding.", "errors": [ "shard_b64 must be base64url" ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_guardian": { "summary": "Unauthenticated Guardian", "description": "The guardian is not logged in, so approval cannot be processed.", "value": { "type": "https://humanlayer.io/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Guardian must be authenticated to approve recovery." } } } } } }, "403": { "description": "The guardian is authenticated but lacks permission to approve this recovery request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_a_guardian": { "summary": "Not a Guardian", "description": "The user attempting to approve is not a guardian for this passport.", "value": { "type": "https://humanlayer.io/errors/not-a-guardian", "title": "Not a Guardian", "status": 403, "detail": "You are not a guardian for this passport." } } } } } }, "404": { "description": "The specified recovery request could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "recovery_request_not_found": { "summary": "Recovery Request Not Found", "description": "The recovery request ID provided does not exist.", "value": { "type": "https://humanlayer.io/errors/request-not-found", "title": "Recovery Request Not Found", "status": 404, "detail": "Recovery request with ID req_12345 was not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred.", "value": { "type": "https://humanlayer.io/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/webauthn/options": { "post": { "summary": "Initiate WebAuthn registration for human passports", "description": "This endpoint orchestrates the creation of WebAuthn options, a critical step in human passport registration. It ensures a secure and verified identity by leveraging advanced cryptographic techniques, making sure only human entities can proceed. This process stands as a gatekeeper, safeguarding the integrity of the HUMAN platform's ecosystem.", "operationId": "generateWebAuthnRegistrationOptions", "tags": [ "Passport", "Authentication" ], "x-code-hash": "ab0db0ca70eb03c0", "x-generated-at": "2026-04-11T02:00:46.628Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "display_name": { "type": "string", "description": "User's display name for the WebAuthn registration process" }, "person_type": { "type": "string", "enum": [ "Human" ], "description": "Type of person, must be 'Human' for this registration" } }, "required": [ "display_name", "person_type" ] }, { "properties": { "displayName": { "type": "string", "description": "User's display name for the WebAuthn registration process" }, "personType": { "type": "string", "enum": [ "Human" ], "description": "Type of person, must be 'Human' for this registration" } }, "required": [ "displayName", "personType" ] }, { "properties": { "name": { "type": "string", "description": "User's display name for the WebAuthn registration process" }, "type": { "type": "string", "enum": [ "Human" ], "description": "Type of person, must be 'Human' for this registration" } }, "required": [ "name", "type" ] } ] }, "examples": { "human_registration": { "summary": "Human Registration", "description": "A typical registration request for a human passport", "value": { "display_name": "Alice Doe", "person_type": "Human" } } } } } }, "responses": { "200": { "description": "WebAuthn options successfully generated for human passport registration", "content": { "application/json": { "schema": { "type": "object", "properties": { "registration_id": { "type": "string", "description": "Unique identifier for the registration process" }, "options": { "type": "object", "description": "Generated WebAuthn options for the client" } } }, "examples": { "default": { "summary": "Example", "value": { "registration_id": "reg_12345678", "options": { "challenge": "sXJj7...", "rp": { "name": "Acme Corp" }, "user": { "id": "user_123", "name": "Alice Doe" } } } } } } } }, "400": { "description": "Invalid input, such as missing fields or incorrect values", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/validation", "title": "Invalid input", "status": 400, "detail": "Display name and person type are required", "errors": [ { "field": "display_name", "message": "Display name is required" }, { "field": "person_type", "message": "WebAuthn registration is only for human passports" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Valid authentication credentials required" } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action" } } } } } }, "404": { "description": "Requested resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found" } } } } } }, "500": { "description": "Internal server error occurred during the process", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/webauthn/login/options": { "post": { "summary": "Initiate WebAuthn login challenge", "description": "Embark on a secure journey of authentication with WebAuthn. This endpoint crafts a unique challenge for users aiming to log in via public-key credentials, ensuring a robust identity verification process. It's the first step in fortifying your digital space with cryptographic assurance.", "operationId": "generateWebAuthnLoginOptions", "tags": [ "Authentication", "WebAuthn" ], "x-code-hash": "06eb490e084bb46e", "x-generated-at": "2026-04-11T02:00:58.255Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "passport_hint": { "type": "string", "description": "A hint for the passport, such as an email." } }, "required": [ "passport_hint" ] }, { "properties": { "passportHint": { "type": "string", "description": "A hint for the passport, such as an email, in camelCase." } }, "required": [ "passportHint" ] } ] }, "examples": { "using_passport_hint": { "summary": "Using passport_hint", "description": "An example showcasing the use of snake_case passport_hint.", "value": { "passport_hint": "user@example.com" } }, "using_passporthint": { "summary": "Using passportHint", "description": "An example showcasing the use of camelCase passportHint.", "value": { "passportHint": "did:human:123456789abcdef" } } } } } }, "responses": { "200": { "description": "Returns a unique challenge and associated options for WebAuthn login.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "The unique identifier for the generated challenge." }, "options": { "type": "object", "description": "WebAuthn options including public key challenge details." } } }, "examples": { "successful_webauthn_challenge_generation": { "summary": "Successful WebAuthn challenge generation", "description": "A typical response showing the generated challenge and options for a user attempting login.", "value": { "challenge_id": "challenge_1234567890abcdef", "options": { "rpId": "example.com", "timeout": 60000, "allowCredentials": [] } } } } } } }, "400": { "description": "The request payload was malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_passport_hint_format": { "summary": "Invalid passport_hint format", "description": "Occurs when the passport_hint is not a string.", "value": { "type": "https://example.com/probs/malformed-request", "title": "Malformed Request", "status": 400, "detail": "The provided 'passport_hint' is not a valid string." } } } } } }, "500": { "description": "Internal server error occurred while generating login options.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "An example of a server error encountered during the request processing.", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/webauthn/login": { "post": { "summary": "Authenticate using WebAuthn and issue JWT", "description": "Seamlessly authenticate users by verifying a WebAuthn assertion and issuing a short-lived JWT session token. This endpoint safeguards digital identities using cryptographic validation, ensuring only verified users can access sensitive delegation exchanges.", "operationId": "postWebauthnLogin", "tags": [ "Authentication", "WebAuthn" ], "x-code-hash": "748f83b37d2a4e1d", "x-generated-at": "2026-04-11T02:01:13.257Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "Unique identifier for the WebAuthn challenge" }, "credential": { "type": "object", "description": "WebAuthn credential assertion object" } }, "required": [ "challenge_id", "credential" ] }, "examples": { "valid_webauthn_login": { "summary": "Valid WebAuthn Login", "description": "A typical request using a WebAuthn credential to authenticate.", "value": { "challenge_id": "ch_1234567890abcdef", "credential": { "id": "cred_abcdefghij123456", "response": { "clientDataJSON": "...", "authenticatorData": "...", "signature": "...", "userHandle": "..." }, "type": "public-key" } } } } } } }, "responses": { "200": { "description": "Successful authentication with JWT session token", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_token": { "type": "string", "description": "JWT session token valid for approximately one hour" }, "passport_id": { "type": "string", "description": "DID of the authenticated passport" }, "did": { "type": "string", "description": "Decentralized identifier of the authenticated user" }, "display_name": { "type": "string", "description": "User's display name associated with this passport" }, "verification_tier": { "type": "string", "description": "Verification tier of the passport" }, "identity_tier": { "type": "string", "description": "Identity verification tier" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration time of the session token" } } }, "examples": { "successful_authentication_response": { "summary": "Successful Authentication Response", "description": "The response returned after a successful authentication.", "value": { "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "passport_id": "did:human:123456789abcdef", "did": "did:human:123456789abcdef", "display_name": "Alice Doe", "verification_tier": "verified", "identity_tier": "silver", "expires_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Bad Request due to validation errors", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_challenge_id": { "summary": "Missing Challenge ID", "description": "Error when the challenge_id is not provided.", "value": { "type": "https://example.com/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "Invalid input parameters", "errors": [ { "field": "challenge_id", "code": "REQUIRED_FIELD_MISSING", "message": "Challenge ID is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized due to failed authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credential": { "summary": "Invalid Credential", "description": "Error when the WebAuthn credential cannot be verified.", "value": { "type": "https://example.com/probs/authentication-failed", "title": "Authentication Failed", "status": 401, "detail": "WebAuthn authentication failed. The credential could not be verified." } } } } } }, "403": { "description": "Forbidden when no active passport is found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_active_passport": { "summary": "No Active Passport", "description": "Error when no active passport is associated with the credential.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "No active passport found for this credential." } } } } } }, "404": { "description": "Not Found when a resource is missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "challenge_not_found": { "summary": "Challenge Not Found", "description": "Error when the challenge ID does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Server error during authentication process", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Error when an unexpected server issue arises.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/recovery/webauthn/options": { "post": { "summary": "Generate WebAuthn Recovery Options", "description": "In the labyrinth of digital identity, recovery is paramount. This endpoint crafts WebAuthn recovery options for a Human passport, ensuring you never lose access to what's rightfully yours. Designed for only the most human of identities, it locks out the non-human pretenders.", "operationId": "generateRecoveryWebAuthnOptions", "tags": [ "Identity", "Security" ], "x-code-hash": "68719a48ccbf052f", "x-generated-at": "2026-04-11T02:01:34.218Z", "responses": { "200": { "description": "Successfully generated recovery WebAuthn options for a valid Human passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "A unique identifier for the WebAuthn challenge." }, "options": { "type": "object", "description": "WebAuthn options necessary for recovery.", "additionalProperties": true } } }, "examples": { "successful_recovery_options_generation": { "summary": "Successful recovery options generation", "description": "A Human passport successfully retrieves WebAuthn recovery options.", "value": { "challenge_id": "abc123xyz", "options": { "rp": { "name": "Acme Corp" }, "user": { "name": "johndoe", "displayName": "John Doe", "id": "user-123" }, "challenge": "random-challenge-123", "pubKeyCredParams": [ { "type": "public-key", "alg": -7 } ] } } } } } } }, "400": { "description": "Bad request due to invalid parameters or state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "non-human_passport_attempt": { "summary": "Non-human passport attempt", "description": "A non-human passport tries to generate recovery options.", "value": { "type": "https://api.human.com/problems/invalid-person-type", "title": "Invalid person type for recovery", "status": 400, "detail": "Recovery WebAuthn options are only for human passports", "errors": [ { "field": "personType", "code": "INVALID_VALUE", "message": "Recovery WebAuthn options are only for human passports", "expected": "Human", "received": "Machine" } ] } } } } } }, "401": { "description": "Unauthorized access to the passport recovery process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_request": { "summary": "Unauthorized request", "description": "An attempt to access the endpoint without valid authentication.", "value": { "type": "https://api.human.com/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_request": { "summary": "Forbidden request", "description": "An attempt by a user lacking necessary permissions.", "value": { "type": "https://api.human.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The specified passport could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport not found", "description": "A non-existent passport ID was provided.", "value": { "type": "https://api.human.com/problems/passport-not-found", "title": "Passport not found", "status": 404, "detail": "No active passport found with the provided ID." } } } } } }, "500": { "description": "Internal server error while generating recovery options.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://api.human.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/keys/rotate/webauthn/options": { "post": { "summary": "Rotate WebAuthn Keys for Passport", "description": "Securely rotate WebAuthn keys for a human passport, ensuring cryptographic integrity. This endpoint facilitates the transition to new keys by generating necessary WebAuthn options, enhancing the security and trust in identity management.", "operationId": "rotateWebAuthnKeys", "tags": [ "Identity", "Security" ], "x-code-hash": "11cb9135435e5082", "x-generated-at": "2026-04-11T02:01:47.469Z", "responses": { "200": { "description": "Successfully generated WebAuthn registration options for key rotation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "registration_id": { "type": "string", "description": "Unique identifier for the registration process." }, "options": { "type": "object", "description": "WebAuthn registration options for key rotation.", "properties": { "challenge": { "type": "string", "description": "Random challenge to be signed by the authenticator." }, "rp": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the relying party." } } }, "user": { "type": "object", "properties": { "name": { "type": "string", "description": "User's display name." }, "id": { "type": "string", "description": "User's identifier." } } } } } } }, "examples": { "successful_registration_options": { "summary": "Successful Registration Options", "description": "Example of a successful response with WebAuthn registration options.", "value": { "registration_id": "reg_123456789", "options": { "challenge": "XYZ12345", "rp": { "name": "Acme Corp" }, "user": { "name": "John Doe", "id": "usr_987654321" } } } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid Parameters", "description": "Example showing a malformed request with invalid parameters.", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "The provided parameters did not match the expected format.", "errors": [ { "field": "passportId", "code": "INVALID_FORMAT", "message": "Passport ID must be a valid DID format." } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Example of a response when the user is not authenticated.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to perform this action." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden": { "summary": "Forbidden", "description": "Example showing lack of permissions to rotate keys.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to rotate keys for this passport." } } } } } }, "404": { "description": "Passport not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "Example when the specified passport ID does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Passport Not Found", "status": 404, "detail": "No active passport found with the given ID." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Example of a response when the server encounters an error.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports": { "post": { "summary": "Register a Human Passport for Discovery", "description": "Embark on the journey of identity verification by registering your cryptographic Passport with HUMAN. This endpoint ensures the integrity of the self-signed proof from your device-rooted Passport, making it discoverable within the HUMAN ecosystem.", "operationId": "registerPassport", "tags": [ "Identity", "Registration" ], "x-code-hash": "8bb7bbb720f1eaed", "x-generated-at": "2026-04-11T02:01:59.019Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passportData": { "type": "string", "description": "Base64-encoded passport data containing the cryptographic proof." } }, "required": [ "passportData" ] }, "examples": { "register_acme_passport": { "summary": "Register Acme Passport", "description": "Registering a new passport for the Acme organization.", "value": { "passportData": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } }, "responses": { "201": { "description": "Passport successfully registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message of successful registration." }, "passportId": { "type": "string", "description": "The unique identifier for the registered passport." } } }, "examples": { "default": { "summary": "Example", "value": { "message": "Passport registered successfully.", "passportId": "acme-passport-12345" } } } } } }, "400": { "description": "Invalid request due to malformed data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Bad Request", "status": 400, "detail": "The 'passportData' field is required and must be a valid Base64 string.", "errors": [ "passportData: Missing or invalid format." ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Ensure your cryptographic proof is correct and try again." } } } } } }, "403": { "description": "Forbidden action due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Check your permissions and try again with appropriate access." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Ensure the resource endpoint is correct and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Please try again later or contact support if the issue persists." } } } } } } } }, "get": { "summary": "Retrieve Visible Organization Passports", "description": "Explore the world of cryptographic identities with the HUMAN platform's Passport retrieval. This endpoint unveils the passports of organizations where you are a recognized founder or where your organization is a delegation grantor, providing a window into the interconnected web of legal entities. Experience seamless navigation through the Capability Graph as you harness the power of AI to track skills and ensure task safety with HumanOS.", "operationId": "listPassportsByType", "tags": [ "Identity", "Organizations" ], "x-code-hash": "9a3f71f464e90a9f", "x-generated-at": "2026-04-11T02:02:12.216Z", "responses": { "200": { "description": "Successfully retrieved a list of organization passports visible to the caller.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string", "description": "The decentralized identifier of the organization." }, "name": { "type": "string", "description": "The display name of the organization." }, "display_name": { "type": "string", "description": "The display name of the organization." }, "status": { "type": "string", "description": "Current status of the passport." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the passport was created." } } } }, "limit": { "type": "integer", "description": "The maximum number of passports returned in the response." }, "cursorFields": { "type": "array", "items": { "type": "string" }, "description": "Fields used for pagination." }, "hasMore": { "type": "boolean", "description": "Indicates if there are more passports to retrieve." } } }, "examples": { "successful_passport_retrieval": { "summary": "Successful Passport Retrieval", "value": { "data": [ { "did": "did:org:acme", "name": "Acme Corporation", "display_name": "Acme Corporation", "status": "active", "created_at": "2023-10-01T12:00:00Z" } ], "limit": 10, "cursorFields": [ "created_at", "did" ], "hasMore": false } } } } } }, "400": { "description": "Invalid request parameters were provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_type_parameter": { "summary": "Missing Type Parameter", "value": { "type": "https://humanprotocol.org/probs/invalid-value", "title": "Invalid Query Parameter", "status": 400, "detail": "Query parameter type=LegalEntity is required for this list.", "errors": [ { "field": "type", "code": "INVALID_VALUE", "message": "Query parameter type=LegalEntity is required for this list.", "expected": "LegalEntity", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication failed due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://humanprotocol.org/probs/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Authentication required. Please provide valid credentials." } } } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://humanprotocol.org/probs/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have permission to view these passports." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://humanprotocol.org/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested passports could not be found." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanprotocol.org/probs/internal-server-error", "title": "Internal Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id": { "get": { "summary": "Retrieve detailed passport information", "description": "This endpoint unveils the cryptographic identity encapsulated within a passport, serving the dual purpose of identity verification and skill tracking in the HUMAN ecosystem. It caters to diverse identities, from humans to organizations and agents, each with its own unique narrative, ensuring a seamless interplay between identity and capability.", "operationId": "getPassportDetails", "tags": [ "Identity", "Passport" ], "x-code-hash": "2da7af96b2da1791", "x-generated-at": "2026-04-11T02:02:28.415Z", "responses": { "200": { "description": "Passport details retrieved successfully, showcasing identity and capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_id": { "type": "string", "description": "The unique DID of the passport." }, "did": { "type": "string", "description": "Decentralized Identifier associated with the passport." }, "type": { "type": "string", "description": "Type of the entity (e.g., Human, LegalEntity, AgentFuture)." }, "name": { "type": "string", "description": "Display name of the entity." }, "public_key": { "type": "string", "description": "Public cryptographic key linked to the identity." }, "did_document": { "type": "object", "description": "Resolved DID document containing identity proofs." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of passport creation." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of last update." }, "vault_endpoint": { "type": "string", "nullable": true, "description": "Endpoint for accessing secure vault, if applicable." }, "vault_kdf_salt": { "type": "string", "nullable": true, "description": "Salt used for key derivation, returned only if the requester is the owner." }, "avatar_url": { "type": "string", "nullable": true, "description": "URL to the avatar image, if available." }, "preferred_language": { "type": "string", "nullable": true, "description": "Preferred language of the entity." } }, "required": [ "passport_id", "did", "type", "name", "public_key", "did_document", "created_at", "updated_at" ] }, "examples": { "successful_retrieval_of_a_human_passport": { "summary": "Successful retrieval of a human passport", "description": "Retrieving a human's passport with detailed identity verification.", "value": { "passport_id": "did:human:123456789abcdefghi", "did": "did:human:123456789abcdefghi", "type": "Human", "name": "Jane Doe", "public_key": "abcdef1234567890", "did_document": { "id": "did:human:123456789abcdefghi", "verificationMethod": [] }, "created_at": "2023-10-05T12:34:56Z", "updated_at": "2023-10-10T15:00:00Z", "vault_endpoint": "https://vault.human-protocol.org/v1/jane", "vault_kdf_salt": "s0m3s4lt", "avatar_url": "https://avatars.human-protocol.org/jane.jpg", "preferred_language": "en" } } } } } }, "400": { "description": "Invalid request format or parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_did_error": { "summary": "Malformed DID error", "description": "The provided DID was malformed.", "value": { "type": "https://example.org/probs/malformed-did", "title": "Invalid DID format", "status": 400, "detail": "The DID provided is not valid. Ensure it follows the correct format: did:scheme:identifier." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_request": { "summary": "Unauthenticated request", "description": "Request made without proper authentication.", "value": { "type": "https://example.org/probs/unauthorized", "title": "Unauthorized Access", "status": 401, "detail": "Authentication credentials were not provided. Please ensure you are logged in and try again." } } } } } }, "403": { "description": "Forbidden access when the user does not have permission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission denied", "description": "User attempting to access another's vault_kdf_salt.", "value": { "type": "https://example.org/probs/forbidden", "title": "Access Denied", "status": 403, "detail": "You do not have permission to access this resource. Ensure you are authorized to view it." } } } } } }, "404": { "description": "Passport not found for the given DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport not found", "description": "The DID does not correspond to any active passport.", "value": { "type": "https://example.org/probs/not-found", "title": "Passport Not Found", "status": 404, "detail": "No active passport found for DID: did:human:unknown. Verify the DID and try again." } } } } } }, "500": { "description": "Unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "A server error occurred while processing the request.", "value": { "type": "https://example.org/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Incident ID: inc_1696594290." } } } } } } } }, "patch": { "summary": "Modify User Passport Information", "description": "Empower users to customize their digital identity by updating fields like avatar and display name. This fosters a personalized experience while maintaining strict security protocols, ensuring only the rightful owner can make changes.", "operationId": "updatePassportDetails", "tags": [ "Identity", "User Management" ], "x-code-hash": "5983b23c7c6c367d", "x-generated-at": "2026-04-11T02:03:37.630Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "avatar_url": { "type": [ "string", "null" ], "format": "uri", "description": "URL of the user's avatar image" }, "display_name": { "type": "string", "description": "The name displayed on the user's profile" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "User's contact email" }, "preferred_language": { "type": [ "string", "null" ], "pattern": "^[a-z]{2,3}(-[A-Z]{2,4})?$", "description": "Preferred language in BCP-47 format" } } }, "examples": { "update_avatar_and_display_name": { "summary": "Update Avatar and Display Name", "description": "An update where the user changes their avatar and display name", "value": { "avatar_url": "https://example.com/images/avatar.png", "display_name": "Jane Doe" } } } } } }, "responses": { "200": { "description": "Returns the updated passport information upon successful modification", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_id": { "type": "string", "description": "The unique identifier of the passport" }, "display_name": { "type": "string", "description": "The updated display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "The updated avatar URL" }, "email": { "type": [ "string", "null" ], "description": "The updated email address" }, "preferred_language": { "type": [ "string", "null" ], "description": "The updated preferred language" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last update" } } }, "examples": { "default": { "summary": "Example", "value": { "passport_id": "did:human:abc123", "display_name": "Jane Doe", "avatar_url": "https://example.com/images/avatar.png", "email": "jane.doe@example.com", "preferred_language": "en", "updated_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "Occurs when the request body is invalid or required fields are missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON" } ] } } } } } }, "401": { "description": "Occurs when the requester is not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to update the passport" } } } } } }, "403": { "description": "Occurs when the requester lacks necessary permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "identity:write or passports:write scope required" } } } } } }, "404": { "description": "Occurs when the requested passport is not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "Passport with DID not found" } } } } } }, "500": { "description": "Occurs when there is an internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/verification-status": { "get": { "summary": "Retrieve Passport's Verification Status", "description": "Explore the journey of a passport as it climbs the Validity Ladder, unlocking new capabilities at each tier. This endpoint reveals the layers of verification and identity tiers achieved by a passport, enabling clients to guide users through potential upgrades.", "operationId": "getPassportVerificationStatus", "tags": [ "Passports", "Verification" ], "x-code-hash": "1fbaae281b37551b", "x-generated-at": "2026-04-11T02:03:54.820Z", "responses": { "200": { "description": "Successfully retrieved verification and identity status for the passport.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportVerificationStatusResponse" }, "examples": { "acme_corp_passport_status": { "summary": "Acme Corp Passport Status", "description": "The verification and identity status for Acme Corp's passport, highlighting unlocked and gated capabilities.", "value": { "did": "did:human:acme12345", "verification_tier": 2, "identity_tier": 1, "layers": { "device_attestation": { "status": "complete", "completed_at": "2023-10-01T12:34:56Z", "provider": "webauthn" }, "biometric_binding": { "status": "available", "action_url": "/v1/passports/did:human:acme12345/verify/biometric" }, "social_attestation": { "status": "not_available", "eta": "v0.3" }, "proof_of_personhood": { "status": "complete", "completed_at": "2023-09-15T08:00:00Z", "provider": "zk_pop" } }, "identity_tiers": { "pseudonymous": { "status": "active" }, "org_verified": { "status": "active" }, "kyc_verified": { "status": "available", "action_url": "/v1/passports/did:human:acme12345/verify/biometric" }, "credential_verified": { "status": "available", "action_url": "/v1/passports/did:human:acme12345/verify/credential" } }, "capabilities_unlocked": [ "companion.basic", "dev.sandbox", "kb.public", "companion.full", "marketplace.publish" ], "capabilities_gated": [ { "capability": "workforce.join", "requires": { "layer": 2 }, "message": "Biometric verification required to join Workforce Cloud" }, { "capability": "payments.receive", "requires": { "identity_tier": 2 }, "message": "KYC verification required for receiving payments" }, { "capability": "governance.participate", "requires": { "layer": 3 }, "message": "Social attestation required for governance participation" } ] } } } } } }, "400": { "description": "Invalid request. The DID format may be incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided DID 'did:human:invalid-format' is not valid. Please check the format and try again." } } } } } }, "401": { "description": "Unauthorized request. Authentication is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to access this resource." } } } } } }, "403": { "description": "Forbidden request. Insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The passport was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The passport with DID 'did:human:acme12345' was not found." } } } } } }, "500": { "description": "Internal server error. Something went wrong.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/keys/jwks": { "get": { "summary": "Retrieve active passport cryptographic keys", "description": "Unlock the potential of secure identity verification by retrieving the active cryptographic keys associated with a specific passport. This endpoint ensures the integrity and authenticity of communications on the HUMAN platform, empowering both humans and AI to interact with confidence.", "operationId": "getPassportKeysJwks", "tags": [ "Identity", "Security" ], "x-code-hash": "13248f8633efbc66", "x-generated-at": "2026-04-11T02:04:24.573Z", "responses": { "200": { "description": "Successfully retrieved the active and retiring public keys associated with the specified passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string" }, "use": { "type": "string" }, "kid": { "type": "string" }, "alg": { "type": "string" }, "n": { "type": "string" }, "e": { "type": "string" } }, "required": [ "kty", "use", "kid", "alg", "n", "e" ] } } } }, "examples": { "acme_passport_keys": { "summary": "Acme Passport Keys", "description": "An example response showing keys for Acme Corporation's cryptographic passport.", "value": { "keys": [ { "kty": "RSA", "use": "sig", "kid": "key1", "alg": "RS256", "n": "0vx7agoebGcQSuuPiLJXZptN3c...s5f6V-Z5D5s", "e": "AQAB" }, { "kty": "RSA", "use": "sig", "kid": "key2", "alg": "RS256", "n": "1abcdEfghijklMnopqrstUvWx...Z0y1z2a3b4c", "e": "AQAB" } ] } } } } } }, "400": { "description": "Invalid request format or parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_passport_id": { "summary": "Invalid Passport ID", "description": "Example where the passport ID format is invalid.", "value": { "type": "https://example.com/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The passport ID provided is not valid. Please ensure it is properly formatted and try again." } } } } } }, "404": { "description": "No active or retiring keys found for the specified passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_keys_not_found": { "summary": "Passport Keys Not Found", "description": "Example where no keys are found for the provided passport ID.", "value": { "type": "https://example.com/problems/not-found", "title": "Resource Not Found", "status": 404, "detail": "No active or retiring keys were found for passport ID 'acme-passport'. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Example where a server-side issue prevents the request from completing.", "value": { "type": "https://example.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later. Incident ID: inc_1697042942" } } } } } } } } }, "/v1/passports/:id/keys/rotate": { "post": { "summary": "Rotate Passport Cryptographic Keys", "description": "In the HUMAN ecosystem, maintaining the security of your cryptographic identity is paramount. This endpoint allows passport holders to rotate their keys, ensuring that their digital identity remains secure and up-to-date. By rotating keys, users can refresh their cryptographic credentials, which is essential for maintaining trust and security in their interactions on the platform.", "operationId": "rotatePassportKeys", "tags": [ "Identity", "Security" ], "x-code-hash": "f5361b51240c39f9", "x-generated-at": "2026-04-11T02:04:37.744Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purposes": { "type": "array", "items": { "type": "string", "enum": [ "auth", "attest" ] }, "description": "Purposes for which the keys are rotated. Must include both 'auth' and 'attest'." }, "webauthn": { "type": "object", "properties": { "auth": { "type": "object" }, "attest": { "type": "object" } }, "description": "WebAuthn credentials for Human passport key rotation." } }, "oneOf": [ { "properties": { "webauthn_auth": { "type": "object" }, "webauthn_attest": { "type": "object" } }, "required": [ "webauthn_auth", "webauthn_attest" ] } ] }, "examples": { "human_key_rotation": { "summary": "Human Key Rotation", "description": "Rotating keys for a Human passport with valid WebAuthn credentials.", "value": { "purposes": [ "auth", "attest" ], "webauthn": { "auth": { "credentialData": "base64-encoded-auth-data" }, "attest": { "credentialData": "base64-encoded-attest-data" } } } } } } } }, "responses": { "200": { "description": "Keys successfully rotated, returning the new key IDs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_id": { "type": "string", "description": "The ID of the passport that had its keys rotated." }, "status": { "type": "string", "enum": [ "rotated" ], "description": "Status of the key rotation." }, "auth_key_id": { "type": "string", "description": "New key ID for authentication." }, "attest_key_id": { "type": "string", "description": "New key ID for attestation." }, "retired_at": { "type": "string", "format": "date-time", "description": "Timestamp when the old keys were retired." } } }, "examples": { "default": { "summary": "Example", "value": { "passport_id": "did:human:123456789abcdef", "status": "rotated", "auth_key_id": "key_abcdef123456", "attest_key_id": "key_123456abcdef", "retired_at": "2023-10-15T08:55:30Z" } } } } } }, "400": { "description": "Invalid request, such as missing or incorrect purposes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Rotation currently requires auth + attest together", "errors": [ { "field": "purposes", "code": "INVALID_PURPOSE_COMBINATION", "message": "Rotation currently requires auth + attest together", "expected": "['auth', 'attest']", "received": "['auth']" } ] } } } } } }, "401": { "description": "Unauthorized access due to improper delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Key rotation requires passport owner" } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to rotate keys for this passport" } } } } } }, "404": { "description": "Passport not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "Passport with ID did:human:123456789abcdef not found" } } } } } }, "500": { "description": "Internal server error during key rotation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passports/:id/keys/:keyId/revoke": { "post": { "summary": "Revoke a Passport Key", "description": "Securely revoke a cryptographic key associated with a Passport, ensuring it can no longer be used for authentication. This endpoint is vital for maintaining security and control over access, especially in dynamic environments where keys must be invalidated promptly.", "operationId": "revokePassportKey", "tags": [ "Security", "Passport Management" ], "x-code-hash": "a8e4343fe2f648a8", "x-generated-at": "2026-04-11T02:04:50.545Z", "responses": { "200": { "description": "The passport key has been successfully revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_id": { "type": "string", "description": "The unique identifier of the Passport whose key was revoked." }, "key_id": { "type": "string", "description": "The unique identifier of the revoked key." }, "status": { "type": "string", "enum": [ "revoked" ], "description": "The status of the key indicating it has been revoked." }, "revoked_at": { "type": "string", "format": "date-time", "description": "The timestamp when the key was revoked." } }, "required": [ "passport_id", "key_id", "status", "revoked_at" ] }, "examples": { "successful_key_revocation": { "summary": "Successful Key Revocation", "value": { "passport_id": "passport_12345", "key_id": "key_67890", "status": "revoked", "revoked_at": "2023-11-05T14:48:00.000Z" } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid Parameters", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Parameters", "status": 400, "detail": "The key ID provided is not valid. Please check the key ID and try again." } } } } } }, "401": { "description": "Unauthorized access attempt.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be the owner of the Passport to revoke its keys." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to revoke keys for this Passport." } } } } } }, "404": { "description": "The specified key was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "key_not_found": { "summary": "Key Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The passport key with ID key_67890 was not found. Please verify the key ID." } } } } } }, "500": { "description": "Internal Server Error due to unexpected issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while revoking the key. Please try again later or contact support with incident ID inc_1698533761000." } } } } } } } } }, "/v1/passports/:id/recovery/enroll": { "post": { "summary": "Enroll Guardian Recovery for Human Passport", "description": "Secure your digital identity with the power of community. This endpoint allows a human passport owner to establish a guardian-based recovery policy. By enlisting trusted guardians, you ensure a safety net for identity recovery, harnessing the strength of social verification.", "operationId": "enrollGuardianRecovery", "tags": [ "Identity", "Security" ], "x-code-hash": "e6fe32a1206bcb70", "x-generated-at": "2026-04-11T02:05:10.208Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "guardians": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier of the guardian." }, "role": { "type": "string", "description": "Optional role of the guardian." }, "encryption_public_key": { "type": "string", "description": "Base64url-encoded 32-byte X25519 public key for secure shard storage." } }, "required": [ "did" ] }, "minItems": 3, "maxItems": 5, "description": "An array of 3 to 5 guardian objects." }, "threshold": { "type": "integer", "description": "Number of guardians required to approve a recovery.", "minimum": 2 } }, "required": [ "guardians" ] }, "examples": { "standard_enrollment": { "summary": "Standard Enrollment", "description": "Enrolls three guardians with a threshold of two for recovery.", "value": { "guardians": [ { "did": "did:human:alice", "role": "friend" }, { "did": "did:human:bob" }, { "did": "did:human:carol", "encryption_public_key": "aGVsbG93b3JsZA==" } ], "threshold": 2 } } } } } }, "responses": { "200": { "description": "Successfully enrolled the recovery policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "type": "string", "description": "Unique identifier for the recovery policy." }, "type": { "type": "string", "description": "Type of the recovery policy." }, "threshold": { "type": "integer", "description": "Number of guardians required for recovery." }, "guardians": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier of the guardian." }, "role": { "type": "string", "description": "Role of the guardian." } } } }, "sss_enabled": { "type": "boolean", "description": "Whether Secret Sharing Scheme is enabled." }, "sss_guardian_count": { "type": "integer", "description": "Number of guardians with encryption keys." } } }, "examples": { "default": { "summary": "Example", "value": { "policy_id": "policy_12345", "type": "guardian", "threshold": 2, "guardians": [ { "did": "did:human:alice", "role": "friend" }, { "did": "did:human:bob" }, { "did": "did:human:carol" } ], "sss_enabled": true, "sss_guardian_count": 3 } } } } } }, "400": { "description": "Validation error due to incorrect input data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/v1/errors/validation", "title": "Validation Error", "status": 400, "detail": "Guardians must include 3 to 5 human DIDs.", "errors": [ { "field": "guardians", "code": "INVALID_GUARDIAN_COUNT", "message": "Guardians must include 3 to 5 human DIDs", "expected": "3-5 guardians", "received": "2 guardians" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/v1/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Recovery enrollment requires passport owner authorization." } } } } } }, "403": { "description": "Forbidden due to lack of proper permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/v1/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Permission denied to enroll recovery policy." } } } } } }, "404": { "description": "Passport not found or is not a human passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/v1/errors/not-found", "title": "Not Found", "status": 404, "detail": "No human passport found with ID 'passport_67890'." } } } } } }, "500": { "description": "Internal server error due to unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/v1/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later.", "incidentId": "inc_1698345234567" } } } } } } } } }, "/v1/passports/:id/recovery/requests": { "get": { "summary": "Retrieve Passport Recovery Requests", "description": "In the world of digital identity, recovery is paramount. This endpoint lets you peek into the requests for recovering a passport, ensuring your digital identity's safety. Dive into a list of recovery attempts to audit and maintain control over your cryptographic identity.", "operationId": "getPassportRecoveryRequests", "tags": [ "Identity", "Security" ], "x-code-hash": "3814479c685dd06a", "x-generated-at": "2026-04-11T02:05:24.432Z", "responses": { "200": { "description": "A paginated list of recovery requests for a specified passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "request_id": { "type": "string" }, "passport_did": { "type": "string" }, "policy_id": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "request_id", "passport_did", "policy_id", "status", "created_at" ] } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": { "type": "string" }, "hasMore": { "type": "boolean" } } } }, "required": [ "data", "pagination" ] }, "examples": { "successful_recovery_request_list": { "summary": "Successful Recovery Request List", "description": "An example response showcasing a typical list of recovery requests.", "value": { "data": [ { "request_id": "req_001", "passport_did": "did:human:acme123", "policy_id": "policy_01", "status": "pending", "reason": "Lost device", "created_at": "2023-07-21T14:32:00Z", "expires_at": "2023-08-21T14:32:00Z", "resolved_at": null } ], "pagination": { "limit": 10, "cursor": "cursor_001", "hasMore": false } } } } } } }, "400": { "description": "Invalid request parameters, such as malformed cursor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_cursor_error": { "summary": "Malformed Cursor Error", "description": "An example of an error when the cursor parameter is invalid.", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid cursor", "status": 400, "detail": "The cursor parameter is invalid or malformed." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "An example where the user is not authenticated.", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Permission denied when the requesting entity is not the passport owner.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "An example where the user does not have permission to access the recovery requests.", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "Recovery requests list requires passport owner." } } } } } }, "404": { "description": "Passport not found with the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "An example where the specified passport ID does not exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified passport ID does not exist." } } } } } }, "500": { "description": "Internal server error when fetching recovery requests.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An example of a server-side error when processing the request.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request. Please try again later." } } } } } } } }, "post": { "summary": "Initiate Passport Recovery Process", "description": "Create a recovery request to regain access to a cryptographic passport, ensuring identity continuity in secure environments. This endpoint is the first step in safeguarding and restoring access when a passport is compromised or lost, leveraging HUMAN's robust identity framework.", "operationId": "createRecoveryRequest", "tags": [ "Passport Management", "Security" ], "x-code-hash": "76f0ee6dac70c615", "x-generated-at": "2026-04-11T02:05:37.298Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time", "description": "The expiration date and time of the recovery request. If not provided, defaults to a predefined TTL." }, "reason": { "type": "string", "description": "The reason for initiating this recovery request, providing context for auditing." } }, "required": [ "reason" ] }, "examples": { "standard_recovery_request": { "summary": "Standard Recovery Request", "description": "An example where the recovery request is created for a lost passport.", "value": { "expiresAt": "2023-12-31T23:59:59Z", "reason": "Lost access to my cryptographic key" } } } } } }, "responses": { "200": { "description": "The recovery request was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique identifier for the recovery request." }, "status": { "type": "string", "description": "Current status of the recovery request." }, "policy_id": { "type": "string", "description": "Identifier of the policy governing this recovery request." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration date and time of the recovery request." } } }, "examples": { "default": { "summary": "Example", "value": { "request_id": "req_1234567890", "status": "pending", "policy_id": "pol_0987654321", "expires_at": "2023-12-31T23:59:59Z" } } } } } }, "400": { "description": "The request is malformed or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The reason field is required.", "errors": [ { "field": "reason", "message": "This field is required." } ] } } } } } }, "401": { "description": "Unauthorized access to the recovery request creation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be the passport owner to initiate a recovery request." } } } } } }, "403": { "description": "Forbidden action due to policy restrictions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Recovery request requires passport owner authorization." } } } } } }, "404": { "description": "The specified passport or policy was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The passport ID provided does not correspond to an existing record." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/recovery/requests/:requestId/approve": { "post": { "summary": "Approve a Passport Recovery Request", "description": "This endpoint allows a guardian or delegating entity to approve a recovery request for a Passport. By validating the integrity and authority of the actor, it ensures that the process of regaining access is securely handled and protected against unauthorized actions.", "operationId": "approveRecoveryRequest", "tags": [ "Passports", "Recovery" ], "x-code-hash": "23a4e996f9bcc43e", "x-generated-at": "2026-04-11T02:05:53.357Z", "responses": { "200": { "description": "Successfully approved the recovery request", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifier of the recovery request" }, "approvals": { "type": "integer", "description": "Number of approvals received" }, "required": { "type": "integer", "description": "Number of approvals required to complete the process" }, "status": { "type": "string", "enum": [ "approved", "pending" ], "description": "Current status of the recovery request" } } }, "examples": { "successful_approval": { "summary": "Successful Approval", "description": "The recovery request has been approved by the guardian.", "value": { "request_id": "req-12345", "approvals": 3, "required": 3, "status": "approved" } } } } } }, "400": { "description": "Validation error, such as expired request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "expired_request": { "summary": "Expired Request", "description": "The recovery request was not approved because it is expired.", "value": { "type": "https://api.humanprotocol.org/errors/validation", "title": "Validation Error", "status": 400, "detail": "The recovery request has expired.", "errors": [ { "field": "expires_at", "code": "REQUEST_EXPIRED", "message": "Recovery request expired", "expected": "non-expired request", "received": "2023-10-01T12:00:00Z" } ] } } } } } }, "401": { "description": "Authentication failure due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_approval": { "summary": "Missing Passport Approval", "description": "The request failed because the approver's Passport was not provided.", "value": { "type": "https://api.humanprotocol.org/errors/authentication", "title": "Authentication Error", "status": 401, "detail": "Missing approving passport" } } } } } }, "403": { "description": "Authorization failure due to lack of permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "non-guardian_approver": { "summary": "Non-Guardian Approver", "description": "The request failed because the approver is not listed as a guardian in the policy.", "value": { "type": "https://api.humanprotocol.org/errors/authorization", "title": "Authorization Error", "status": 403, "detail": "Approver is not a guardian" } } } } } }, "404": { "description": "The specified recovery request or Passport could not be found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "request_not_found": { "summary": "Request Not Found", "description": "The recovery request specified does not exist in the system.", "value": { "type": "https://api.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Recovery request not found" } } } } } }, "500": { "description": "Internal server error indicating a failure within the system", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_system_error": { "summary": "Unexpected System Error", "description": "The system encountered an unexpected error during approval processing.", "value": { "type": "https://api.humanprotocol.org/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred, please try again later." } } } } } } } } }, "/v1/passports/:id/recovery/requests/:requestId/execute": { "post": { "summary": "Execute a Passport Recovery Request", "description": "When human and AI collide, passports need recovery. Execute an approved recovery request to breathe life back into your digital identity. This endpoint ensures seamless recovery, verifying security at each step, and offers a second chance for your cryptographic identity.", "operationId": "executePassportRecoveryRequest", "tags": [ "Passport", "Recovery" ], "x-code-hash": "f38a041b53caa49c", "x-generated-at": "2026-04-11T02:06:10.109Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webauthn": { "type": "object", "properties": { "auth": { "type": "object" }, "attest": { "type": "object" } }, "additionalProperties": false } }, "required": [ "webauthn" ] }, "examples": { "webauthn_credentials_example": { "summary": "WebAuthn Credentials Example", "description": "An example WebAuthn payload for human recovery", "value": { "webauthn": { "auth": { "credentialId": "auth-credential-id", "aaguid": "auth-aaguid", "registrationId": "auth-registration-id" }, "attest": { "credentialId": "attest-credential-id", "aaguid": "attest-aaguid", "registrationId": "attest-registration-id" } } } } } } } }, "responses": { "200": { "description": "The recovery request was successfully executed, and the passport is now restored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_id": { "type": "string" }, "status": { "type": "string", "enum": [ "executed" ] }, "next_step": { "type": "string", "enum": [ "recovery_complete" ] }, "auth_key_id": { "type": "string" }, "attest_key_id": { "type": "string" }, "retired_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example", "value": { "passport_id": "did:example:123456789abcdefghi", "status": "executed", "next_step": "recovery_complete", "auth_key_id": "key-12345", "attest_key_id": "key-67890", "retired_at": "2023-10-15T14:48:00.000Z" } } } } } }, "400": { "description": "The request body was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "WebAuthn auth and attest payloads are required for recovery", "errors": [ { "field": "webauthn_auth", "code": "REQUIRED_FIELD_MISSING", "message": "WebAuthn auth payload is missing." } ] } } } } } }, "401": { "description": "Unauthorized access to the recovery endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden: The request was understood but refused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to execute this recovery request." } } } } } }, "404": { "description": "The specified recovery request or passport was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The recovery request with ID 'req-12345' was not found." } } } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while executing the recovery request. Please try again later." } } } } } } } } }, "/v1/passports/recovery/keys": { "post": { "summary": "Generate Single-Use Recovery Keys", "description": "In the labyrinth of identity, sometimes you need a lifeline. This endpoint crafts a new set of 10 single-use recovery keys for your passport, ensuring you can always find your way back. These keys are your safety net, providing a secure way to regain access when all else fails. The keys are delivered just once, like a message in a bottle, so keep them safe.", "operationId": "generateRecoveryKeys", "tags": [ "Identity", "Security" ], "x-code-hash": "587861cac8213196", "x-generated-at": "2026-04-11T02:06:23.470Z", "responses": { "200": { "description": "Successfully generated a new set of recovery keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recovery_keys": { "type": "array", "items": { "type": "string", "description": "A single-use recovery key." } }, "count": { "type": "integer", "description": "Number of recovery keys generated." }, "warning": { "type": "string", "description": "Additional information or warnings." } }, "required": [ "recovery_keys", "count" ] }, "examples": { "successful_recovery_key_generation": { "summary": "Successful Recovery Key Generation", "description": "An example of a successful recovery key generation for a user's passport.", "value": { "recovery_keys": [ "k1bc7df2-8f3b-4b7a-9f6c-a3e9f40f8e2c", "k2bc7df2-8f3b-4b7a-9f6c-a3e9f40f8e2d", "k3bc7df2-8f3b-4b7a-9f6c-a3e9f40f8e2e" ], "count": 10, "warning": "These keys are displayed only once. Store them securely." } } } } } }, "400": { "description": "Bad Request due to invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request_example": { "summary": "Invalid Request Example", "description": "An example where the request was malformed.", "value": { "type": "https://developer.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters were invalid. Please verify your request and try again.", "errors": [ "Missing required headers." ] } } } } } }, "401": { "description": "Authentication failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "An example of an unauthorized access attempt.", "value": { "type": "https://developer.humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to access this endpoint. Ensure your session token is valid." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "An example where the user lacks the necessary permissions.", "value": { "type": "https://developer.humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to generate recovery keys. Contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "Passport not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found_example": { "summary": "Passport Not Found Example", "description": "An example of a request where the passport was not found.", "value": { "type": "https://developer.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The passport associated with the session could not be found. Verify your credentials and try again." } } } } } }, "500": { "description": "Internal server error during key generation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "An example of a server error during the key generation process.", "value": { "type": "https://developer.humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while generating recovery keys. Please try again later. Reference incident ID: inc_1696782345678." } } } } } } } } }, "/v1/passports/recovery/keys/regenerate": { "post": { "summary": "Regenerate Passport Recovery Keys", "description": "In the ever-evolving landscape of digital identities, keeping your recovery keys secure is paramount. This endpoint gives you the power to regenerate your recovery keys, seamlessly revoking the old set and ensuring your digital identity remains protected. It's about safeguarding your credentials with a simple request.", "operationId": "regenerateRecoveryKeys", "tags": [ "Identity", "Security" ], "x-code-hash": "1561e9f56243ee29", "x-generated-at": "2026-04-11T02:06:35.058Z", "responses": { "200": { "description": "Upon successful regeneration, the response provides the new set of recovery keys along with their count and any relevant warnings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recovery_keys": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" }, "warning": { "type": "string", "nullable": true } }, "required": [ "recovery_keys", "count" ] }, "examples": { "successful_regeneration": { "summary": "Successful Regeneration", "description": "A user from the 'acme' organization successfully regenerates their recovery keys.", "value": { "recovery_keys": [ "key1", "key2", "key3" ], "count": 3, "warning": null } } } } } }, "400": { "description": "Bad Request due to invalid input or missing parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request_example": { "summary": "Invalid Request Example", "description": "The request was malformed; the user must correct the format.", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request was malformed. Please ensure all required fields are correctly formatted.", "errors": [ "Missing 'passportDid' parameter" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_example": { "summary": "Unauthorized Example", "description": "The request lacks valid authentication credentials.", "value": { "type": "/errors/authentication-required", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource. Please log in and try again." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_example": { "summary": "Forbidden Example", "description": "The user does not have permission to regenerate keys.", "value": { "type": "/errors/permission-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to regenerate recovery keys. Contact your administrator for access." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not Found Example", "description": "The specified resource could not be located.", "value": { "type": "/errors/resource-not-found", "title": "Not Found", "status": 404, "detail": "The resource you are looking for does not exist. Verify the resource identifier and try again." } } } } } }, "500": { "description": "Internal Server Error indicating an unexpected condition was encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "Server encountered an unexpected condition.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later. If the problem persists, contact support with incident ID inc_1697040023456." } } } } } } } } }, "/v1/passports/recovery/keys/status": { "get": { "summary": "Retrieve Remaining Recovery Keys", "description": "In the realm of digital identity, safeguarding access is paramount. This endpoint empowers users to check the status of their recovery keys without revealing sensitive details, ensuring they maintain a robust security posture. By understanding the balance of used, remaining, and total keys, users can navigate their recovery strategy with confidence.", "operationId": "getRecoveryKeysStatus", "tags": [ "Identity", "Security" ], "x-code-hash": "9baa27e52b835f51", "x-generated-at": "2026-04-11T02:06:47.071Z", "responses": { "200": { "description": "Returns the current status of recovery keys for a user's Passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of recovery keys allocated." }, "remaining": { "type": "integer", "description": "Number of recovery keys that remain unused." }, "used": { "type": "integer", "description": "Number of recovery keys that have been used." }, "generated": { "type": "string", "description": "ISO 8601 timestamp indicating when the status was generated." } } }, "examples": { "standard_response": { "summary": "Standard Response", "description": "A response indicating the user has used some of their recovery keys.", "value": { "total": 5, "remaining": 3, "used": 2, "generated": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "Bad Request. The request is malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_example": { "summary": "Malformed Request Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Bad Request", "status": 400, "detail": "The request parameters are invalid. Please review your input." } } } } } }, "401": { "description": "Unauthorized access. Authentication is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_example": { "summary": "Missing Authentication Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access token is missing or invalid. Please authenticate and try again." } } } } } }, "403": { "description": "Forbidden. The user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions_example": { "summary": "Insufficient Permissions Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to perform this action." } } } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The passport associated with the provided DID was not found." } } } } } }, "500": { "description": "Internal Server Error. An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_failure_example": { "summary": "Server Failure Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Incident ID: inc_1696523400000" } } } } } } } } }, "/v1/passports/recovery/execute": { "post": { "summary": "Execute Passport Recovery Process", "description": "Unlock access to your digital identity with a secure, two-step recovery process. Using a single-use recovery key, this endpoint enables users to regain control of their Passport when their primary passkey is lost. Experience peace of mind with aggressive security measures protecting against unauthorized access.", "operationId": "executePassportRecovery", "tags": [ "Identity", "Security" ], "x-code-hash": "ff61d1476a0399f7", "x-generated-at": "2026-04-11T02:07:07.235Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "step": { "type": "string", "enum": [ "initiate" ] }, "passport_hint": { "type": "string", "description": "Hint for the passport identity, typically an email or DID" }, "recovery_key": { "type": "string", "description": "Single-use recovery key provided during initial setup" } }, "required": [ "step", "passport_hint", "recovery_key" ] }, { "type": "object", "properties": { "step": { "type": "string", "enum": [ "complete" ] }, "recovery_token": { "type": "string", "description": "Token issued during the initiation step" }, "registration_id": { "type": "string", "description": "ID for the WebAuthn registration process" }, "credential": { "type": "object", "description": "New WebAuthn credential for device registration" } }, "required": [ "step", "recovery_token", "registration_id", "credential" ] } ] }, "examples": { "initiate_recovery": { "summary": "Initiate Recovery", "description": "Example of the initial recovery request with recovery key and passport hint.", "value": { "step": "initiate", "passport_hint": "user@example.com", "recovery_key": "recovery-key-1234" } }, "complete_recovery": { "summary": "Complete Recovery", "description": "Example of completing the recovery with a token and a new credential.", "value": { "step": "complete", "recovery_token": "token-5678", "registration_id": "reg-9876", "credential": { "id": "cred-abc123", "type": "public-key", "rawId": "raw-id-xyz", "response": { "clientDataJSON": "base64-encoded-client-data", "attestationObject": "base64-encoded-attestation-object" } } } } } } } }, "responses": { "200": { "description": "Successfully executed the passport recovery process", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "registration_id": { "type": "string", "description": "Registration ID for WebAuthn process" }, "options": { "type": "object", "description": "WebAuthn registration options for the new device" }, "recovery_token": { "type": "string", "description": "Token to be used in the completion step" } } }, { "type": "object", "properties": { "session_token": { "type": "string", "description": "Session token for the newly authenticated session" }, "passport_id": { "type": "string", "description": "The ID of the recovered passport" }, "did": { "type": "string", "description": "Decentralized identifier associated with the passport" }, "display_name": { "type": "string", "description": "User's display name" }, "verification_tier": { "type": "string", "description": "Level of verification achieved" }, "identity_tier": { "type": "string", "description": "Identity tier level" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration time of the session token" }, "remaining_recovery_keys": { "type": "integer", "description": "Count of remaining recovery keys for future use" } } } ] }, "examples": { "initiate_response": { "summary": "Initiate Response", "value": { "registration_id": "reg-9876", "options": { "challenge": "random-challenge", "rp": { "name": "Acme Corp" }, "user": { "id": "user-id", "name": "user@example.com", "displayName": "John Doe" } }, "recovery_token": "token-5678" } }, "complete_response": { "summary": "Complete Response", "value": { "session_token": "session-token-12345", "passport_id": "passport-12345", "did": "did:example:123456789abcdefghi", "display_name": "John Doe", "verification_tier": "basic", "identity_tier": "tier-1", "expires_at": "2023-12-31T23:59:59Z", "remaining_recovery_keys": 3 } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_parameters": { "summary": "Missing Parameters", "value": { "type": "https://example.com/probs/invalid-params", "title": "Invalid request parameters", "status": 400, "detail": "passport_hint and recovery_key are required.", "errors": [ { "field": "passport_hint", "code": "REQUIRED_FIELD_MISSING", "message": "passport_hint and recovery_key are required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized due to invalid recovery key or token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_recovery_key": { "summary": "Invalid Recovery Key", "value": { "type": "https://example.com/probs/unauthorized", "title": "Authentication failed", "status": 401, "detail": "Invalid recovery key or passport hint. Check your recovery key and try again." } } } } } }, "403": { "description": "Forbidden due to rate limiting or invalid permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "rate_limited": { "summary": "Rate Limited", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden operation", "status": 403, "detail": "This operation is not allowed due to aggressive rate limiting." } } } } } }, "404": { "description": "Not Found if resources are not located", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Resource not found", "status": 404, "detail": "The requested resource was not found." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/consent-log": { "post": { "summary": "Log consent events with provenance tracking", "description": "In the HUMAN ecosystem, consent is more than agreement—it's a critical piece of provenance. This endpoint logs consent events, optionally registering them as capability evidence if they grant a specific capability. By doing so, it not only ensures compliance but also empowers participants by securely documenting their consent footprint.", "operationId": "logConsentEvent", "tags": [ "Passports", "Consent" ], "x-code-hash": "576d0f3b7e8b6eac", "x-generated-at": "2026-04-11T02:07:22.036Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action associated with the consent, if any." }, "capabilityGranted": { "type": "string", "description": "The capability ID granted by this consent, if applicable." }, "consentEntry": { "type": "object", "properties": { "accessorDid": { "type": "string", "description": "DID of the entity accessing the resource." }, "resourceType": { "type": "string", "description": "Type of resource the consent pertains to." }, "granted": { "type": "boolean", "description": "Indicates if the consent was granted." } }, "required": [ "accessorDid", "resourceType", "granted" ] } }, "required": [ "consentEntry" ] }, "examples": { "grant_consent_to_access_profile": { "summary": "Grant consent to access profile", "description": "Logging consent for an organization to access a user's profile data.", "value": { "action": "access_profile", "capabilityGranted": "capability://acme/profile_access", "consentEntry": { "accessorDid": "did:example:org:acme", "resourceType": "profile", "granted": true } } } } } } }, "responses": { "200": { "description": "Consent logged successfully with capability evidence registration status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_id": { "type": "string", "description": "Unique identifier for the recorded consent." }, "provenance_id": { "type": "string", "description": "Identifier for the provenance record associated with this consent." }, "capability_evidence_registered": { "type": "boolean", "description": "Indicates whether capability evidence was successfully registered." }, "status": { "type": "string", "description": "Status of the consent logging operation." } } }, "examples": { "default": { "summary": "Example", "value": { "consent_id": "consent-12345", "provenance_id": "prov-67890", "capability_evidence_registered": true, "status": "recorded" } } } } } }, "400": { "description": "Bad Request due to missing or invalid consent entry fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/validation", "title": "Invalid Consent Entry", "status": 400, "detail": "Missing consent entry fields", "errors": [ { "field": "consent_entry", "code": "MISSING_REQUIRED_FIELDS", "message": "Missing consent entry fields", "expected": "valid consent entry object", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized error when consent logging requires passport owner authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Consent logging requires passport owner" } } } } } }, "403": { "description": "Forbidden error indicating the user does not have permission to log consent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Access to log consent is forbidden" } } } } } }, "404": { "description": "Not Found error when the specified passport cannot be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/not-found", "title": "Passport Not Found", "status": 404, "detail": "The specified passport ID does not exist." } } } } } }, "500": { "description": "Internal Server Error when the system encounters an unexpected problem while logging consent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while logging consent." } } } } } } } }, "get": { "summary": "Retrieve Passport Consent Events", "description": "Explore the consent history of a cryptographic identity with precision and insight. This endpoint unveils the trail of consent events linked to a passport, showcasing how various resources have been accessed and utilized with explicit permissions. It empowers users to audit and understand the access patterns associated with their digital identity.", "operationId": "getPassportConsentLog", "tags": [ "Identity", "Audit" ], "x-code-hash": "7c1a07bd6ff78592", "x-generated-at": "2026-04-11T02:07:34.974Z", "responses": { "200": { "description": "A list of consent events associated with the specified passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accessor_did": { "type": "string" }, "resource_type": { "type": "string" }, "granted": { "type": "boolean" }, "consented_at": { "type": "string", "format": "date-time" }, "provenance_id": { "type": "string", "nullable": true } } } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } } }, "examples": { "successful_consent_log_retrieval": { "summary": "Successful Consent Log Retrieval", "description": "Retrieve a paginated list of consent events for a digital passport.", "value": { "data": [ { "id": "event123", "accessor_did": "did:human:example123", "resource_type": "capability://invoice-processing", "granted": true, "consented_at": "2023-10-01T12:34:56Z", "provenance_id": "prov456" } ], "limit": 10, "cursorFields": [ "consented_at", "id" ], "hasMore": false } } } } } }, "400": { "description": "Invalid request parameters, such as malformed cursor values.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor": { "summary": "Invalid Cursor", "description": "The cursor value provided is not valid.", "value": { "type": "https://humanprotocol.org/errors/invalid-cursor", "title": "Invalid Cursor Parameter", "status": 400, "detail": "The cursor parameter is malformed or contains invalid data. Ensure the cursor is correctly encoded and try again.", "errors": [ "Cursor value 'abc123' is not in the correct format." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access the consent log. Provide valid credentials and try again." } } } } } }, "403": { "description": "Forbidden access due to lack of permission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The requester does not own the passport and cannot access its consent log.", "value": { "type": "https://humanprotocol.org/errors/access-denied", "title": "Forbidden", "status": 403, "detail": "Consent log access requires the passport owner's authorization. Ensure you are accessing your own passport consent log." } } } } } }, "404": { "description": "The passport or consent log could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "The specified passport ID does not exist.", "value": { "type": "https://humanprotocol.org/errors/passport-not-found", "title": "Not Found", "status": 404, "detail": "The passport with ID 'pass123' does not exist. Verify the ID and try again." } } } } } }, "500": { "description": "An error occurred on the server while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the consent log. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passports/:passportId/link-to-org": { "post": { "summary": "Link Passport to Organization", "description": "In the world of HUMAN, identities are not just cryptographic tokens; they are passports to new opportunities. This endpoint links a user's cryptographic identity to their organizational role, ensuring that the right skills and capabilities are attributed to the right person. It's a vital step in creating a seamless Human-AI collaboration environment.", "operationId": "linkPassportToOrg", "tags": [ "Identity", "Organization" ], "x-code-hash": "3dd5ed81934e3e66", "x-generated-at": "2026-04-11T02:07:46.975Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "linkingCode": { "type": "string", "description": "A unique code provided by the organization to link the passport." }, "email": { "type": "string", "format": "email", "description": "The email address associated with the passport holder's organizational role." } }, "required": [ "linkingCode", "email" ] }, "examples": { "successful_link_request": { "summary": "Successful Link Request", "description": "A request to link a passport with a valid linking code and email.", "value": { "linkingCode": "abc123-orglink", "email": "john.doe@acme.org" } } } } } }, "responses": { "200": { "description": "A verification code has been sent to the user's email, completing the first step of linking.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "examples": { "default": { "summary": "Example", "value": { "message": "Verification code sent to email", "email": "john.doe@acme.org" } } } } } }, "400": { "description": "The request was malformed, such as missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/validation", "title": "Validation Error", "status": 400, "detail": "One or more fields are invalid.", "errors": [ { "field": "linking_code", "code": "REQUIRED_FIELD_MISSING", "message": "Linking code is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "The request was not authorized because the passport ID did not match the requester.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/authorization", "title": "Authorization Error", "status": 401, "detail": "Org linking requires passport owner." } } } } } }, "403": { "description": "The operation is forbidden, possibly due to a used or revoked linking code.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Linking code already used or revoked. Use a new linking code." } } } } } }, "404": { "description": "The linking code could not be found, indicating it may be incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/not-found", "title": "Not Found", "status": 404, "detail": "Invalid linking code. Please check and try again." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.protocol/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:passportId/verify-email": { "post": { "summary": "Verify email and complete passport link", "description": "This endpoint breathes life into the digital identity by verifying an email using a 6-digit code. It completes the vital connection between a passport and an organization, triggering an attestation that signals a trustworthy relationship. No additional authentication is needed beyond the code, making the process seamless and efficient.", "operationId": "verifyEmailForPassport", "tags": [ "Identity", "Verification" ], "x-code-hash": "082cf44deb081104", "x-generated-at": "2026-04-11T02:08:00.162Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "A 6-digit verification code sent to the user's email." } }, "required": [ "code" ] }, "examples": { "verification_code_submission": { "summary": "Verification Code Submission", "description": "Submits a 6-digit code to verify and link the email.", "value": { "code": "123456" } } } } } }, "responses": { "200": { "description": "The email address has been successfully verified and linked to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Email verified" }, "linked": { "type": "boolean", "example": true } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was invalid due to a missing or incorrect verification code.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Unauthorized access due to invalid authentication. However, this endpoint does not require authentication, so this error is unlikely unless the system is misconfigured.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Forbidden access due to permissions. Not applicable in this context as the verification code acts as sufficient proof.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "The specified passport ID does not exist or has no pending verification.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "An internal server error occurred during the verification process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/passports/:passportId/attestations": { "get": { "summary": "Retrieve passport's attestations", "description": "Unearth the verified skills and credentials linked to a passport within the HUMAN platform. This endpoint empowers users to view the attestations tied to a cryptographic identity, revealing the journey and trustworthiness of the passport holder.", "operationId": "getPassportAttestations", "tags": [ "Passport", "Attestation" ], "x-code-hash": "b2bb3f7186ce43db", "x-generated-at": "2026-04-11T02:08:18.986Z", "responses": { "200": { "description": "Successfully retrieved attestations for the given passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "credential_id": { "type": "string" }, "type": { "type": "string" }, "issuer": { "type": "string" }, "subject": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "claims": { "type": "object" }, "signature": { "type": "string" } }, "required": [ "id", "credential_id", "type", "issuer", "subject", "issued_at", "claims", "signature" ] } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorFields", "hasMore" ] }, "examples": { "successful_retrieval_of_attestations": { "summary": "Successful retrieval of attestations", "description": "Retrieve a list of active attestations for a specific passport, demonstrating the credentials issued by various entities.", "value": { "data": [ { "id": "attestation-123", "credential_id": "credential-abc", "type": "skill", "issuer": "did:human:issuer-456", "subject": "did:human:passport-123", "issued_at": "2023-10-01T12:34:56Z", "expires_at": null, "revoked_at": null, "claims": { "skill": "data-analysis" }, "signature": "signature-789" } ], "limit": 10, "cursorFields": [ "issued_at", "id" ], "hasMore": false } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passportid_parameter": { "summary": "Missing passportId parameter", "description": "An attempt to retrieve attestations without providing the required passportId.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request is missing required fields.", "errors": [ { "field": "passportId", "code": "REQUIRED_FIELD_MISSING", "message": "passportId path parameter is required", "expected": "did:human:…", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "Attempt to access attestations without proper authentication.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "description": "Attempt to read attestations when the requester's delegation does not match the passportId.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Reading attestations requires the passport owner (delegation.from must match passportId)." } } } } } }, "404": { "description": "Passport or resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport not found", "description": "The specified passportId does not exist.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The passport with the specified ID does not exist." } } } } } }, "500": { "description": "Internal server error due to unforeseen issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred while fetching attestations.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/org/:did/founders": { "get": { "summary": "Retrieve founders of an organization passport", "description": "Behind every successful organization is a team of founders whose vision shapes its identity. This endpoint allows you to explore the individuals who established a given organization, identified by its decentralized identifier (DID). By understanding who these founders are, you gain insight into the organization's origin story and governance structure.", "operationId": "getOrgPassportFounders", "tags": [ "Passport Management", "Organization" ], "x-code-hash": "0b7f66fe0c457fd0", "x-generated-at": "2026-04-11T02:08:30.836Z", "responses": { "200": { "description": "Founders of the organization passport retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The organization's decentralized identifier" }, "legal_name": { "type": "string", "description": "The legal name of the organization" }, "status": { "type": "string", "description": "Current status of the organization's passport" }, "founders": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string", "description": "Founder's decentralized identifier" }, "role": { "type": "string", "description": "Role of the founder within the organization" }, "signed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the founder signed the passport" } } } }, "founder_count": { "type": "integer", "description": "Total number of founders" } } }, "examples": { "successful_retrieval_of_founders": { "summary": "Successful retrieval of founders", "description": "Example showing the retrieval of founders for the organization 'acme'", "value": { "org_did": "did:org:acme", "legal_name": "Acme Corp", "status": "active", "founders": [ { "did": "did:human:alice", "role": "CEO", "signed_at": "2021-01-01T12:00:00Z" }, { "did": "did:human:bob", "role": "CTO", "signed_at": "2021-01-02T14:30:00Z" } ], "founder_count": 2 } } } } } }, "400": { "description": "Bad Request due to missing or invalid DID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_did": { "summary": "Missing DID", "description": "Example showing an error when DID is not provided", "value": { "type": "https://human.protocol/errors#required-field-missing", "title": "Required Field Missing", "status": 400, "detail": "Org DID is required", "errors": [ { "field": "did", "code": "REQUIRED_FIELD_MISSING", "message": "Org DID is required", "expected": "did:org:*", "received": "undefined" } ] } } } } } }, "404": { "description": "Not Found when the organization passport does not exist", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization not found", "description": "Example showing an error when the specified organization does not exist", "value": { "type": "https://human.protocol/errors#not-found", "title": "Not Found", "status": 404, "detail": "The organization passport with DID did:org:acme was not found" } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "generic_server_error": { "summary": "Generic server error", "description": "Example showing an unexpected server error", "value": { "type": "https://human.protocol/errors#internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } }, "post": { "summary": "Change founders synchronously with signatures", "description": "Join forces in a ceremonial moment to alter the fabric of your organization's leadership. This endpoint allows for immediate founder adjustments when all necessary signatures are provided, ensuring trust and authenticity in high-stakes decisions.", "operationId": "postOrgFounders", "tags": [ "Identity", "Governance" ], "x-code-hash": "4a98ad12aad28ce6", "x-generated-at": "2026-04-11T02:08:49.251Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add", "remove" ], "description": "Action to perform: 'add' to include a new founder, 'remove' to exclude an existing one." }, "founder_did": { "type": "string", "description": "DID of the founder to be added or removed.", "pattern": "^did:human:.*$" }, "requested_by": { "type": "string", "description": "DID of the founder proposing the change.", "pattern": "^did:human:.*$" }, "signatures": { "type": "array", "items": { "type": "object", "properties": { "approver_did": { "type": "string", "description": "DID of the approver providing the signature.", "pattern": "^did:human:.*$" }, "signature": { "type": "string", "description": "Cryptographic signature of the approver." } }, "required": [ "approver_did", "signature" ] }, "description": "Array of signatures from current founders verifying the change." } }, "required": [ "action", "founder_did", "requested_by", "signatures" ] }, "examples": { "adding_a_new_founder": { "summary": "Adding a new founder", "description": "Example of adding a new founder to the organization with all required signatures.", "value": { "action": "add", "founder_did": "did:human:12345", "requested_by": "did:human:67890", "signatures": [ { "approver_did": "did:human:99999", "signature": "signature_base64_here" } ] } } } } } }, "responses": { "201": { "description": "Founder change was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "DID of the organization." }, "action": { "type": "string", "description": "Action performed (add/remove)." }, "founder": { "type": "object", "properties": { "did": { "type": "string", "description": "DID of the founder added or removed." }, "role": { "type": "string", "description": "Role of the founder if added." } } }, "founder_count": { "type": "integer", "description": "New count of founders." }, "threshold_required": { "type": "integer", "description": "Signatures threshold required for change." }, "verified_approvers": { "type": "array", "items": { "type": "string" }, "description": "List of DIDs of verified approvers." }, "provenance_id": { "type": "string", "description": "ID of the provenance log entry." } }, "required": [ "org_did", "action", "founder", "founder_count", "threshold_required", "verified_approvers", "provenance_id" ] }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:human:org:abcdef", "action": "add", "founder": { "did": "did:human:12345", "role": "founder" }, "founder_count": 4, "threshold_required": 3, "verified_approvers": [ "did:human:99999" ], "provenance_id": "prov_123456789" } } } } } }, "400": { "description": "Invalid input data or signature verification failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-input", "title": "Invalid Request", "status": 400, "detail": "Invalid value for action: expected 'add' or 'remove'.", "errors": [ { "field": "action", "code": "INVALID_VALUE", "message": "Action must be 'add' or 'remove'.", "expected": "'add' | 'remove'", "received": "none" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Missing or invalid authentication token." } } } } } }, "403": { "description": "Permission error due to action by non-founder.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "The requester is not a current founder." } } } } } }, "404": { "description": "Entity not found: organization or founder.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified organization or founder was not found." } } } } } }, "500": { "description": "Internal server error during founder change process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/org/verify-domain": { "post": { "summary": "Initiate domain verification for an organization", "description": "Verify an organization's domain as part of its cryptographic identity within the HUMAN Protocol. This process ensures the authenticity of the domain ownership, enhancing trust and security in AI-human task orchestration.", "operationId": "postOrgVerifyDomain", "tags": [ "Identity", "Verification" ], "x-code-hash": "9e317fe1b0874d3d", "x-generated-at": "2026-04-11T02:09:01.581Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "org_did": { "type": "string", "description": "The Decentralized Identifier (DID) of the organization", "pattern": "^did:org:.*$" }, "domain": { "type": "string", "description": "The domain name to be verified" } }, "required": [ "org_did", "domain" ] }, { "properties": { "orgDid": { "type": "string", "description": "The Decentralized Identifier (DID) of the organization", "pattern": "^did:org:.*$" }, "domain": { "type": "string", "description": "The domain name to be verified" } }, "required": [ "orgDid", "domain" ] } ] }, "examples": { "acmeorgdomainverification": { "summary": "acmeOrgDomainVerification", "description": "Initiating domain verification for Acme Corp.", "value": { "org_did": "did:org:acme", "domain": "acmecorp.com" } } } } } }, "responses": { "201": { "description": "Domain verification initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The organization's DID" }, "domain": { "type": "string", "description": "The domain being verified" }, "status": { "type": "string", "enum": [ "pending" ], "description": "The verification status" }, "verification": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "dns_txt" ], "description": "Verification method used" }, "txt_record": { "type": "string", "description": "The DNS TXT record to add" }, "txt_value": { "type": "string", "description": "The value for the DNS TXT record" }, "instructions": { "type": "string", "description": "Instructions to complete the DNS challenge" }, "expires_in_hours": { "type": "integer", "description": "Time in hours before the verification challenge expires" } }, "required": [ "method", "txt_record", "txt_value", "instructions", "expires_in_hours" ] } }, "required": [ "org_did", "domain", "status", "verification" ] }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body is missing required fields.", "errors": [ { "field": "org_did", "code": "REQUIRED_FIELD_MISSING", "message": "Org DID is required", "expected": "did:org:*", "received": "undefined" }, { "field": "domain", "code": "REQUIRED_FIELD_MISSING", "message": "Domain is required", "expected": "valid domain (e.g., \"human.inc\")", "received": "undefined" } ] } } } } } }, "500": { "description": "Internal server error during domain verification", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. If the problem persists, contact support with incident ID: inc_1698765432123." } } } } } } } } }, "/v1/passports/org/:did/upgrade-tier": { "post": { "summary": "Upgrade organization governance tier", "description": "Empower your organization to unlock new capabilities by upgrading its governance tier. This endpoint validates your organization’s readiness and executes a tier upgrade, ensuring compliance and integrity through rigorous checks. Elevate your organization's potential while maintaining transparency and security.", "operationId": "upgradeOrgGovernanceTier", "tags": [ "Governance", "Organization" ], "x-code-hash": "86494d76928f5043", "x-generated-at": "2026-04-11T02:09:18.718Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "requested_by": { "type": "string", "description": "DID of the founder requesting the upgrade", "example": "did:human:abc123" }, "target_tier": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "The desired governance tier", "example": 2 } }, "required": [ "requested_by", "target_tier" ] }, { "properties": { "requestedBy": { "type": "string", "description": "DID of the founder requesting the upgrade", "example": "did:human:abc123" }, "targetTier": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "The desired governance tier", "example": 2 } }, "required": [ "requestedBy", "targetTier" ] } ] }, "examples": { "successful_upgrade_request": { "summary": "Successful Upgrade Request", "description": "Upgrade an organization to Tier 2 with valid founder DID", "value": { "requested_by": "did:human:abc123", "target_tier": 2 } } } } } }, "responses": { "200": { "description": "The governance tier was successfully upgraded", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The DID of the organization", "example": "did:human:org456" }, "previous_tier": { "type": "integer", "description": "The previous governance tier before the upgrade", "example": 1 }, "governance_tier": { "type": "integer", "description": "The new governance tier after the upgrade", "example": 2 }, "founder_count": { "type": "integer", "description": "The number of founders in the organization", "example": 3 }, "provenance_id": { "type": "string", "description": "The ID of the provenance record for this operation", "example": "prov_789" } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:human:org456", "previous_tier": 1, "governance_tier": 2, "founder_count": 3, "provenance_id": "prov_789" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "target_tier must be 1, 2, or 3", "errors": [ { "field": "target_tier", "code": "INVALID_VALUE", "message": "target_tier must be 1, 2, or 3", "expected": "1 | 2 | 3", "received": "5" } ] } } } } } }, "401": { "description": "Missing or invalid authorization", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization token is missing or invalid" } } } } } }, "403": { "description": "Forbidden: the requester is not authorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "did:human:abc123 is not a founder of this organization", "errors": [ { "field": "requested_by", "code": "AUTHORIZATION_ERROR", "message": "did:human:abc123 is not a founder of this organization", "expected": "current founder DID", "received": "did:human:abc123" } ] } } } } } }, "404": { "description": "Organization not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Organization with DID did:human:org456 not found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/org/:did/proposals": { "post": { "summary": "Initiate a Quorum Change Proposal", "description": "Empower organizational founders with the ability to propose pivotal changes in governance. This endpoint facilitates the creation of proposals for adding or removing founders, adjusting quorum thresholds, or even dissolving the organization. It's a crucial mechanism for dynamic and secure decision-making within decentralized environments.", "operationId": "createQuorumChangeProposal", "tags": [ "Governance", "Identity" ], "x-code-hash": "4a890afb64474856", "x-generated-at": "2026-04-11T02:09:33.985Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_type": { "type": "string", "enum": [ "add_founder", "remove_founder", "change_threshold", "dissolve" ], "description": "The type of change being proposed" }, "proposed_by": { "type": "string", "description": "DID of the founder proposing the change" }, "payload": { "type": "object", "properties": { "founder_did": { "type": "string", "description": "DID of the founder to add or remove" }, "new_threshold": { "type": "integer", "description": "New quorum threshold for 'change_threshold' proposals" } } }, "expires_in_hours": { "type": "integer", "description": "Proposal expiration time in hours" }, "signature": { "type": "string", "description": "Valid Ed25519 signature over the proposal payload" } }, "required": [ "change_type", "proposed_by" ] }, "examples": { "add_founder_proposal": { "summary": "Add Founder Proposal", "description": "Proposing the addition of a new founder to the organization", "value": { "change_type": "add_founder", "proposed_by": "did:human:12345", "payload": { "founder_did": "did:human:67890" }, "expires_in_hours": 48, "signature": "base64-encoded-signature" } } } } } }, "responses": { "201": { "description": "Proposal successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "Unique identifier for the proposal" }, "org_did": { "type": "string", "description": "DID of the organization" }, "change_type": { "type": "string", "description": "Type of change being proposed" }, "proposed_by": { "type": "string", "description": "DID of the proposer" }, "status": { "type": "string", "description": "Current status of the proposal" }, "approvals_collected": { "type": "integer", "description": "Number of approvals collected so far" }, "threshold_required": { "type": "integer", "description": "Number of approvals required to execute the proposal" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration date and time of the proposal" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Permission denied", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "Organization not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } }, "get": { "summary": "Retrieve organization's proposal list with pagination", "description": "Explore the dynamic landscape of organizational progress by retrieving a list of proposals associated with a decentralized identifier (DID). This endpoint empowers organizations to track proposed changes, ensuring informed decision-making and transparent governance.", "operationId": "getOrgProposals", "tags": [ "Passport", "Proposals" ], "x-code-hash": "f210bd4c7514447f", "x-generated-at": "2026-04-11T02:09:49.926Z", "responses": { "200": { "description": "Successfully retrieves a paginated list of proposals for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "proposal_id": { "type": "string" }, "org_did": { "type": "string" }, "change_type": { "type": "string" }, "proposed_by": { "type": "string" }, "payload": { "type": "object" }, "status": { "type": "string" }, "approvals_collected": { "type": "integer" }, "threshold_required": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "provenance_id": { "type": [ "string", "null" ] } }, "required": [ "proposal_id", "org_did", "created_at", "expires_at" ] } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": { "type": "string" }, "has_more": { "type": "boolean" } } } } }, "examples": { "retrieving_proposals_for_acme_organization": { "summary": "Retrieving proposals for acme organization", "description": "A paginated response showing the first page of proposals for the 'acme' organization.", "value": { "data": [ { "proposal_id": "12345", "org_did": "did:example:acme", "change_type": "policy_update", "proposed_by": "did:example:john", "payload": { "description": "Update HR policy for remote work" }, "status": "pending", "approvals_collected": 2, "threshold_required": 5, "created_at": "2023-10-01T12:00:00Z", "expires_at": "2023-12-31T12:00:00Z", "executed_at": null, "provenance_id": null } ], "pagination": { "limit": 10, "cursor": "eyJjcmVhdGVkX2F0IjogIjIwMjMtMTAtMDFUMTI6MDA6MDBaIn0=", "has_more": false } } } } } } }, "400": { "description": "Invalid request due to malformed query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_did": { "summary": "Missing DID", "description": "The DID parameter is missing or malformed.", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'did' parameter is required and must be a valid DID.", "errors": [ "Parameter 'did' is missing." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "Access denied due to invalid API token.", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "You must provide a valid API key to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission denied", "description": "The agent does not have the necessary permissions to view proposals.", "value": { "type": "https://example.com/probs/permission", "title": "Forbidden", "status": 403, "detail": "Your current role does not permit access to this organization's proposals." } } } } } }, "404": { "description": "The specified organization or resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization not found", "description": "The DID provided does not correspond to any known organization.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "No organization found with the DID 'did:example:unknown'." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID 'inc_1696067240000'." } } } } } } } } }, "/v1/passports/org/:did/proposals/:proposalId": { "get": { "summary": "Retrieve details of an org proposal", "description": "Explore the intricacies of a specific proposal within an organization's capability graph. By fetching these details, stakeholders can review, approve, or track the status and history of skill changes, ensuring transparency and accountability in decision-making.", "operationId": "getProposalDetails", "tags": [ "Passports", "Proposals" ], "x-code-hash": "228518ebef854dcc", "x-generated-at": "2026-04-11T02:10:02.855Z", "responses": { "200": { "description": "Successfully retrieved proposal details, including its status and approvals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "Unique identifier for the proposal" }, "org_did": { "type": "string", "description": "Decentralized identifier of the organization" }, "change_type": { "type": "string", "description": "Type of change proposed" }, "proposed_by": { "type": "string", "description": "DID of the proposer" }, "payload": { "type": "object", "description": "Detailed content of the proposal" }, "status": { "type": "string", "description": "Current status of the proposal" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "approver_did": { "type": "string", "description": "DID of the approver" }, "signed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the proposal was approved" } } }, "description": "List of approvals collected for the proposal" }, "approvals_collected": { "type": "integer", "description": "Number of approvals collected" }, "threshold_required": { "type": "integer", "description": "Number of approvals required for execution" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the proposal was created" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the proposal expires" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the proposal was executed, if applicable" }, "provenance_id": { "type": [ "string", "null" ], "description": "Identifier for tracking proposal provenance" } }, "required": [ "proposal_id", "org_did", "change_type", "proposed_by", "status", "approvals", "created_at", "expires_at" ] }, "examples": { "default": { "summary": "Example", "value": { "proposal_id": "abc123", "org_did": "did:human:org:acme", "change_type": "skill_upgrade", "proposed_by": "did:human:agent:jdoe", "payload": { "skill": "AI Ethics", "level": "advanced" }, "status": "pending", "approvals": [ { "approver_did": "did:human:agent:jsmith", "signed_at": "2023-10-01T12:34:56Z" } ], "approvals_collected": 1, "threshold_required": 3, "created_at": "2023-09-28T09:45:00Z", "expires_at": "2023-10-05T09:45:00Z", "executed_at": null, "provenance_id": "prov123" } } } } } }, "400": { "description": "Invalid request parameters were provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The proposal ID provided is not valid. Please ensure it is a valid UUID." } } } } } }, "401": { "description": "Authorization is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must provide a valid access token to retrieve proposal details." } } } } } }, "403": { "description": "You do not have permission to view this proposal.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You are not allowed to view proposals for this organization. Please contact an administrator if you believe this is incorrect." } } } } } }, "404": { "description": "The specified proposal could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "No proposal with ID 'abc123' was found for organization DID 'did:human:org:acme'. Please verify the identifiers are correct." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while retrieving the proposal details. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passports/org/:did/proposals/:proposalId/approve": { "post": { "summary": "Approve Organization Proposal", "description": "Navigate the intricate dance of consensus within the HUMAN network by approving proposals that shape the future of your organization. This endpoint not only records an approval but auto-executes the proposal once the required threshold is met, embedding the decision into the immutable ledger of provenance.", "operationId": "approveOrgProposal", "tags": [ "Passport", "Governance" ], "x-code-hash": "ced1c23c3795072d", "x-generated-at": "2026-04-11T02:10:15.694Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approver_did": { "type": "string", "description": "Decentralized Identifier of the approver.", "pattern": "^did:human:.*$" }, "signature": { "type": "string", "description": "Base64 encoded Ed25519 signature over the proposal payload." } }, "oneOf": [ { "required": [ "approver_did", "signature" ] } ] }, "examples": { "approve_proposal": { "summary": "Approve Proposal", "description": "An example of a founder approving a proposal.", "value": { "approver_did": "did:human:founder123", "signature": "dGVzdFNpZ25hdHVyZQ==" } } } } } }, "responses": { "200": { "description": "The approval was successful, and the proposal may be executed if threshold is met.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string" }, "status": { "type": "string" }, "executed": { "type": "boolean" }, "approvals_collected": { "type": "integer" }, "threshold_required": { "type": "integer" }, "provenance_id": { "type": "string" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing or malformed fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Forbidden action due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "The proposal or organization could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "Internal server error due to unforeseen issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/passports/org/:did/proposals/:proposalId/reject": { "post": { "summary": "Reject a proposal within an organization", "description": "In the dynamic interplay of human intellect and AI, proposals drive evolution. This endpoint empowers founders to decisively reject proposals that no longer align with organizational vision, ensuring agility and adherence to core values.", "operationId": "rejectProposal", "tags": [ "Proposals", "Organizations" ], "x-code-hash": "4a52c7ebc7beb8d6", "x-generated-at": "2026-04-11T02:10:29.772Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rejected_by": { "type": "string", "description": "DID of the founder rejecting the proposal", "pattern": "^did:human:.*$" } }, "oneOf": [ { "required": [ "rejected_by" ] } ] }, "examples": { "reject_by_founder": { "summary": "Reject by founder", "description": "Example illustrating rejection by a valid founder DID.", "value": { "rejected_by": "did:human:1234abcd" } } } } } }, "responses": { "200": { "description": "The proposal was successfully rejected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "The unique identifier of the rejected proposal." }, "status": { "type": "string", "description": "The new status of the proposal.", "enum": [ "rejected" ] }, "rejected_by": { "type": "string", "description": "DID of the founder who rejected the proposal." } } }, "examples": { "default": { "summary": "Example", "value": { "proposal_id": "proposal-5678efgh", "status": "rejected", "rejected_by": "did:human:1234abcd" } } } } } }, "400": { "description": "Bad Request due to validation errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "One or more fields have validation errors.", "errors": [ { "field": "rejected_by", "code": "REQUIRED_FIELD_MISSING", "message": "rejected_by (founder DID) is required", "expected": "did:human:*", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Invalid credentials provided. Ensure your API token is correct and has not expired." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authorization-error", "title": "Authorization Error", "status": 403, "detail": "You do not have permission to reject this proposal.", "errors": [ { "field": "rejected_by", "code": "AUTHORIZATION_ERROR", "message": "did:human:1234abcd is not a current founder", "expected": "current founder DID", "received": "did:human:1234abcd" } ] } } } } } }, "404": { "description": "The specified proposal or organization could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The proposal with ID proposal-5678efgh could not be found. Verify the proposal ID and organization DID." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/server-error", "title": "Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passports/org/:did/dissolve": { "post": { "summary": "Dissolve an organizational passport", "description": "This endpoint initiates the irreversible dissolution of an organization's passport, signaling the end of its active status. By doing so, it ensures that all active agent delegations are revoked, safeguarding the integrity of the system. Whether asynchronously proposed for quorum approval or executed synchronously with signatures, this process is critical to maintaining a secure and trustworthy Human-AI orchestration.", "operationId": "dissolveOrgPassport", "tags": [ "Passport", "Organization" ], "x-code-hash": "8e2aa20e0497c862", "x-generated-at": "2026-04-11T02:10:47.836Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proposed_by": { "type": "string", "description": "The DID of the proposing founder.", "pattern": "^did:human:.*$" }, "mode": { "type": "string", "enum": [ "async", "synchronous" ], "default": "async", "description": "Mode of dissolution; defaults to async requiring quorum approval." }, "signatures": { "type": "array", "description": "Required for synchronous mode. An array of cryptographic signatures from founders.", "items": { "type": "object", "properties": { "approverDid": { "type": "string", "description": "DID of the signing founder." }, "signature": { "type": "string", "description": "Cryptographic signature." } }, "required": [ "approverDid", "signature" ] } }, "reason": { "type": "string", "description": "Optional reason for dissolution proposal." }, "signature": { "type": "string", "description": "Optional initial founder signature for async proposal." } }, "required": [ "proposed_by" ] }, "examples": { "async_proposal": { "summary": "Async Proposal", "description": "Creating a dissolution proposal asynchronously with a reason.", "value": { "proposed_by": "did:human:12345", "mode": "async", "reason": "Strategic shift in organizational focus." } }, "synchronous_execution": { "summary": "Synchronous Execution", "description": "Immediate dissolution with required signatures.", "value": { "proposed_by": "did:human:67890", "mode": "synchronous", "signatures": [ { "approverDid": "did:human:11111", "signature": "abc123" }, { "approverDid": "did:human:22222", "signature": "def456" } ] } } } } } }, "responses": { "200": { "description": "The organization was successfully dissolved with all agents revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The DID of the dissolved organization." }, "status": { "type": "string", "enum": [ "dissolved" ], "description": "The new status of the organization." }, "agents_revoked": { "type": "integer", "description": "Number of agent delegations revoked." }, "provenance_id": { "type": "string", "description": "Unique identifier for the provenance record." }, "dissolved_at": { "type": "string", "format": "date-time", "description": "Timestamp of dissolution." } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:human:org123", "status": "dissolved", "agents_revoked": 15, "provenance_id": "prov_abc123", "dissolved_at": "2023-11-01T12:34:56Z" } } } } } }, "201": { "description": "Dissolution proposal created, pending founder approval.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "Identifier for the dissolution proposal." }, "org_did": { "type": "string", "description": "The DID of the organization." }, "status": { "type": "string", "enum": [ "pending" ], "description": "Current status of the proposal." }, "mode": { "type": "string", "enum": [ "async" ], "description": "Mode of the proposal." }, "approvals_collected": { "type": "integer", "description": "Number of approvals collected so far." }, "threshold_required": { "type": "integer", "description": "Number of approvals required for execution." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration date of the proposal." }, "message": { "type": "string", "description": "Additional information regarding the proposal." } } }, "examples": { "default": { "summary": "Example", "value": { "proposal_id": "qprop_456def", "org_did": "did:human:org456", "status": "pending", "mode": "async", "approvals_collected": 1, "threshold_required": 3, "expires_at": "2023-11-04T12:34:56Z", "message": "Dissolution proposal created. Other founders must approve before execution." } } } } } }, "400": { "description": "Invalid request due to missing or incorrect data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "The request body contains invalid fields.", "errors": [ { "field": "proposed_by", "code": "REQUIRED_FIELD_MISSING", "message": "proposed_by (founder DID) is required", "expected": "did:human:*", "received": "null" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/authorization-error", "title": "Authorization Error", "status": 403, "detail": "The proposed_by DID is not a current founder.", "errors": [ { "field": "proposed_by", "code": "AUTHORIZATION_ERROR", "message": "did:human:99999 is not a current founder", "expected": "current founder DID", "received": "did:human:99999" } ] } } } } } }, "404": { "description": "The requested organization passport was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Organization passport with DID did:human:org789 not found." } } } } } }, "500": { "description": "Internal server error encountered during processing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during the dissolution process. Please try again later." } } } } } } } } }, "/v1/passports/authority/verify": { "post": { "summary": "Verify a complete authority chain", "description": "In the intricate dance between human and AI, ensuring trustworthiness is paramount. This endpoint verifies the cryptographic integrity of an authority chain, documenting each step in the provenance ledger. Whether you're verifying an organization or an individual agent, this process guarantees that only legitimate entities hold power.", "operationId": "verifyAuthorityChain", "tags": [ "Identity", "Security" ], "x-code-hash": "5085e3a2c3fe7df1", "x-generated-at": "2026-04-11T02:11:06.560Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_did": { "type": "string", "description": "Decentralized Identifier for the agent." }, "org_did": { "type": "string", "description": "Decentralized Identifier for the organization." }, "mode": { "type": "string", "enum": [ "full", "cached", "delegation-only" ], "description": "Verification mode: full, cached, or delegation-only." } }, "oneOf": [ { "required": [ "agent_did" ] }, { "required": [ "org_did" ] } ] }, "examples": { "agent_verification": { "summary": "Agent Verification", "description": "Verify the authority chain for an individual agent.", "value": { "agent_did": "did:agent:1234abcd", "mode": "full" } }, "organization_verification": { "summary": "Organization Verification", "description": "Verify the authority chain for an organization.", "value": { "org_did": "did:org:5678efgh", "mode": "cached" } } } } } }, "responses": { "200": { "description": "The authority chain was successfully verified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_did": { "type": "string", "description": "The agent DID that was verified." }, "org_did": { "type": "string", "description": "The organization DID that was verified." }, "verification_mode": { "type": "string", "description": "The mode used for verification." }, "valid": { "type": "boolean", "description": "Indicates if the authority chain is valid." }, "chain": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "did": { "type": "string" }, "delegation_valid": { "type": "boolean" }, "delegation_expired": { "type": "boolean" }, "delegation_revoked": { "type": "boolean" }, "error": { "type": "string", "nullable": true } } }, "org": { "type": "object", "properties": { "did": { "type": "string" }, "genesis_valid": { "type": "boolean" }, "status": { "type": "string" }, "error": { "type": "string", "nullable": true } } }, "founders": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string" }, "signature_valid": { "type": "boolean" }, "passport_active": { "type": "boolean" }, "error": { "type": "string", "nullable": true } } } } } }, "errors": { "type": "array", "items": { "type": "string" } }, "verified_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the chain was verified." } } }, "examples": { "successful_agent_verification": { "summary": "Successful Agent Verification", "description": "An agent's authority chain verified with no issues.", "value": { "agent_did": "did:agent:1234abcd", "verification_mode": "full", "valid": true, "chain": { "agent": { "did": "did:agent:1234abcd", "delegation_valid": true, "delegation_expired": false, "delegation_revoked": false, "error": null }, "org": { "did": "did:org:5678efgh", "genesis_valid": true, "status": "active", "error": null }, "founders": [ { "did": "did:founder:abcd1234", "signature_valid": true, "passport_active": true, "error": null } ] }, "errors": [], "verified_at": "2023-10-04T14:48:00.000Z" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_did": { "summary": "Missing DID", "description": "Error when no agent_did or org_did is provided.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Bad Request", "status": 400, "detail": "Either agent_did or org_did is required for authority chain verification", "errors": [ { "field": "agent_did", "code": "REQUIRED_FIELD_MISSING", "message": "Either agent_did or org_did is required for authority chain verification", "expected": "did:agent:* or did:org:*", "received": "undefined" } ] } } } } } }, "404": { "description": "The specified DID does not exist in the system.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "did_not_found": { "summary": "DID Not Found", "description": "Error when the provided org_did is not found.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The organization DID did:org:5678efgh was not found in the system." } } } } } }, "500": { "description": "Internal server error during the verification process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred during verification.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during authority chain verification. Please try again later." } } } } } } } } }, "/v1/passports/:id/verify/biometric": { "post": { "summary": "Initiate Biometric Verification Session", "description": "Unlock the next tier of identity verification by initiating a biometric verification session. This endpoint allows passport holders to securely advance their verification and identity tiers to Level 2, using cutting-edge biometric authentication. Experience seamless identity verification with human intelligence and AI safety protocols.", "operationId": "initiateBiometricVerificationSession", "tags": [ "Identity Verification", "Biometric" ], "x-code-hash": "5f57ea333cd74fd8", "x-generated-at": "2026-04-11T02:11:24.434Z", "responses": { "201": { "description": "Biometric verification session successfully initiated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique identifier for the biometric session." }, "redirect_url": { "type": "string", "description": "URL to redirect the user for biometric capture." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration time for the session." }, "provider": { "type": "string", "description": "Name of the biometric verification provider." } }, "required": [ "session_id", "redirect_url", "expires_at", "provider" ] }, "examples": { "successful_biometric_verification_initiation": { "summary": "Successful Biometric Verification Initiation", "description": "A biometric verification session was successfully initiated for the passport holder.", "value": { "session_id": "session_123456", "redirect_url": "https://biometric.provider.com/capture?session_id=session_123456", "expires_at": "2023-11-01T12:00:00Z", "provider": "BiometricProviderX" } } } } } }, "401": { "description": "Unauthorized access attempt.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_biometric_verification_attempt": { "summary": "Unauthorized Biometric Verification Attempt", "value": { "type": "https://humanlayer.io/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You can only initiate biometric verification for your own passport." } } } } } }, "403": { "description": "Forbidden action: Device attestation required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "device_attestation_required": { "summary": "Device Attestation Required", "value": { "type": "https://humanlayer.io/errors/verification-required", "title": "Device Attestation Required", "status": 422, "detail": "Complete device attestation (Layer 1) before biometric verification (Layer 2).", "remediation": [ { "step": 1, "description": "Register passkey", "link": "/v1/passports/did:example:123/webauthn/options" } ] } } } } } }, "404": { "description": "Passport not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "value": { "type": "https://humanlayer.io/errors/not-found", "title": "Not Found", "status": 404, "detail": "Passport with DID did:example:123 not found." } } } } } }, "409": { "description": "Biometric verification already completed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "already_biometrically_verified": { "summary": "Already Biometrically Verified", "value": { "type": "https://humanlayer.io/errors/already-verified", "title": "Already Biometrically Verified", "status": 409, "detail": "This passport already has biometric verification (Layer 2)." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanlayer.io/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/verify/biometric/webhook": { "post": { "summary": "Verify biometric identity via webhook", "description": "This endpoint is the critical touchpoint where human and machine meet to ensure identity integrity. It enables seamless biometric verification, elevating the user's verification and identity tier while safeguarding against fraud through cryptographic checks.", "operationId": "verifyBiometricWebhook", "tags": [ "Identity", "Verification" ], "x-code-hash": "657f3a4dbe60d753", "x-generated-at": "2026-04-11T02:11:38.007Z", "responses": { "200": { "description": "Biometric verification successful; tiers advanced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "clear", "rejected" ], "example": "clear" } } }, "examples": { "successful_verification": { "summary": "Successful Verification", "description": "The biometric verification was successful, advancing verification and identity tiers.", "value": { "received": true, "status": "clear" } } } } } }, "400": { "description": "Invalid request payload; signature verification failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_payload": { "summary": "Malformed Payload", "description": "The payload was malformed or unsigned, leading to rejection.", "value": { "type": "https://developer.human/probs/invalid-payload", "title": "Invalid Request Payload", "status": 400, "detail": "The request payload could not be processed due to invalid structure or missing signature." } } } } } }, "401": { "description": "Unauthorized; missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request lacked proper authentication headers.", "value": { "type": "https://developer.human/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid." } } } } } }, "403": { "description": "Forbidden; insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user attempted to access a resource they are not permitted to view.", "value": { "type": "https://developer.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not Found; Passport ID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "The specified Passport ID does not exist in the system.", "value": { "type": "https://developer.human/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The specified Passport ID was not found." } } } } } }, "409": { "description": "Conflict; biometric collision detected.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "biometric_collision_detected": { "summary": "Biometric Collision Detected", "description": "The biometric data matched an existing passport, indicating a potential duplicate.", "value": { "type": "https://developer.human/probs/conflict", "title": "Biometric Collision", "status": 409, "detail": "Passport already exists for this biometric. If you lost access to your previous Passport, use recovery." } } } } } }, "500": { "description": "Internal Server Error; unexpected condition encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "An internal error occurred, preventing the completion of the verification process.", "value": { "type": "https://developer.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the biometric verification." } } } } } } } } }, "/v1/passports/:id/vouches": { "post": { "summary": "Submit a signed vouch for identity", "description": "In a digital world, trust is invaluable. This endpoint allows trusted agents to vouch for a cryptographic identity, contributing to its social verification. Achieving a certain number of vouches can elevate the identity's verification tier, enhancing its credibility within the HUMAN ecosystem.", "operationId": "submitVouchForPassport", "tags": [ "Identity", "Verification" ], "x-code-hash": "30b4db26be57b393", "x-generated-at": "2026-04-11T02:12:00.388Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "voucher_did": { "type": "string", "description": "Decentralized Identifier (DID) of the voucher", "example": "did:human:123456789abcdef" }, "statement": { "type": "string", "description": "A statement explaining the reason for the vouch", "example": "I have worked with this person for 5 years." }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Level of confidence in the vouch", "example": "high" }, "relationship": { "type": "string", "enum": [ "colleague", "friend", "family", "other" ], "description": "The type of relationship with the subject", "example": "colleague" }, "met_since": { "type": "string", "format": "date-time", "description": "Date since the voucher knows the subject", "example": "2018-06-01T00:00:00Z" }, "signature": { "type": "string", "description": "Ed25519 signature of the vouch statement", "example": "base64urlencodedstring" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of when the vouch was created", "example": "2023-10-10T14:48:00Z" } }, "required": [ "voucher_did", "statement", "confidence", "relationship", "signature" ] }, "examples": { "colleague_vouch_example": { "summary": "Colleague Vouch Example", "description": "A vouch from a colleague with high confidence.", "value": { "voucher_did": "did:human:987654321abcdef", "statement": "I have collaborated with them on multiple successful projects.", "confidence": "high", "relationship": "colleague", "met_since": "2015-03-15T00:00:00Z", "signature": "base64urlencodedstring", "timestamp": "2023-10-10T14:48:00Z" } } } } } }, "responses": { "201": { "description": "Vouch successfully submitted and processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "vouch_id": { "type": "string", "description": "Unique identifier of the submitted vouch", "example": "pvo1234567890abcdef" }, "active_vouches": { "type": "integer", "description": "Number of active vouches for the subject", "example": 3 }, "tier_3_achieved": { "type": "boolean", "description": "Indicates if the subject's verification tier has been advanced to 3", "example": true } } }, "examples": { "successful_vouch_submission": { "summary": "Successful Vouch Submission", "description": "A successful vouch submission that advanced the subject's verification tier.", "value": { "vouch_id": "pvo1234567890abcdef", "active_vouches": 3, "tier_3_achieved": true } } } } } }, "400": { "description": "Bad Request due to invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_required_fields": { "summary": "Missing Required Fields", "description": "Request with missing required fields.", "value": { "type": "https://humanlayer.io/errors/invalid-request", "title": "Invalid Request Payload", "status": 400, "detail": "One or more fields are invalid or missing.", "errors": [ { "field": "voucher_did", "code": "REQUIRED_FIELD_MISSING", "message": "Voucher DID is required", "expected": "did:human:...", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Request made without valid authentication.", "value": { "type": "https://humanlayer.io/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are required." } } } } } }, "403": { "description": "Forbidden due to permission issues", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Attempt to vouch without proper permissions.", "value": { "type": "https://humanlayer.io/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to vouch for this identity." } } } } } }, "404": { "description": "Passport not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "Vouch attempt for a non-existent passport.", "value": { "type": "https://humanlayer.io/errors/not-found", "title": "Passport Not Found", "status": 404, "detail": "The specified passport does not exist." } } } } } }, "409": { "description": "Conflict due to duplicate vouch", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "duplicate_vouch_conflict": { "summary": "Duplicate Vouch Conflict", "description": "Attempt to submit a vouch that already exists.", "value": { "type": "https://humanlayer.io/errors/duplicate-vouch", "title": "Duplicate Vouch", "status": 409, "detail": "You have already vouched for this passport." } } } } } }, "422": { "description": "Unprocessable Entity for invalid vouch conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_voucher_tier": { "summary": "Insufficient Voucher Tier", "description": "Voucher DID does not meet the required tier.", "value": { "type": "https://humanlayer.io/errors/voucher-tier-insufficient", "title": "Voucher Tier Insufficient", "status": 422, "detail": "Voucher must have verification_tier >= 1 (current: 0)" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An error occurred during the vouch processing.", "value": { "type": "https://humanlayer.io/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve active vouches for a passport", "description": "Explore the trusted network around a passport by listing its active vouches. Discover how others in the HUMAN ecosystem vouch for this identity, building a web of trust that strengthens the protocol's integrity.", "operationId": "getActiveVouchesForPassport", "tags": [ "Identity", "Trust" ], "x-code-hash": "ce74a0181aaf7f73", "x-generated-at": "2026-04-11T02:12:14.035Z", "responses": { "200": { "description": "A list of active vouches for the specified passport, empowering clients to map relational trust.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the vouch" }, "voucher_did": { "type": "string", "description": "Decentralized Identifier of the voucher" }, "confidence": { "type": "string", "description": "Confidence level of the vouch" }, "relationship": { "type": "string", "description": "Nature of the relationship between voucher and subject" }, "met_since": { "type": [ "string", "null" ], "description": "Date when the voucher first met the subject, if applicable" }, "voucher_tier_at_time": { "type": "integer", "description": "Voucher's tier at the time of vouching" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the vouch was created" } }, "required": [ "id", "voucher_did", "confidence", "relationship", "created_at" ] } }, "limit": { "type": "integer", "description": "Page size limit" }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for pagination to fetch the next set of results" } }, "required": [ "data" ] }, "examples": { "successful_vouch_retrieval": { "summary": "Successful Vouch Retrieval", "description": "Retrieve active vouches for the given passport ID", "value": { "data": [ { "id": "vouch_12345", "voucher_did": "did:human:org_acme_agent_john_doe", "confidence": "high", "relationship": "colleague", "met_since": "2022-01-15", "voucher_tier_at_time": 3, "created_at": "2023-09-17T12:34:56Z" } ], "limit": 10, "next_cursor": null } } } } } }, "400": { "description": "Bad Request due to invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/invalid-query-parameters", "title": "Invalid Query Parameters", "status": 400, "detail": "The provided 'limit' parameter is not a valid number. Please ensure it is an integer.", "errors": [ "limit must be a positive integer" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Access token is missing or invalid. Please provide a valid token to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have permission to view vouches for this passport. Please contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "Passport not found or inactive", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/passport-not-found", "title": "Passport Not Found", "status": 404, "detail": "No active passport found with the provided ID. Please check the ID and try again." } } } } } }, "500": { "description": "Internal server error while processing the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving vouches. Please try again later, or contact support if the problem persists." } } } } } } } } }, "/v1/passports/:id/vouches/:vouchId": { "delete": { "summary": "Revoke a self-authored vouch.", "description": "In the intricate dance of identity verification, a vouch represents trust. This endpoint allows a voucher to withdraw their endorsement, recalibrating the trust network if necessary. If the withdrawal dips below a critical threshold, the verification tier is gracefully demoted, ensuring the integrity of the ecosystem.", "operationId": "revokeVouch", "tags": [ "Identity", "Trust" ], "x-code-hash": "508f359a81001631", "x-generated-at": "2026-04-11T02:12:25.864Z", "responses": { "200": { "description": "Successfully revoked the vouch, with a check for active vouches count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "remaining_active_vouches": { "type": "integer" } } }, "examples": { "successful_revocation": { "summary": "Successful Revocation", "description": "A voucher revokes their support for a passport DID, reducing the active vouches.", "value": { "revoked": true, "remaining_active_vouches": 1 } } } } } }, "400": { "description": "Bad request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_parameters": { "summary": "Malformed Parameters", "description": "The client provided an invalid ID format.", "value": { "type": "https://humanlayer.io/errors/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "The provided vouchId or passport ID is not in the correct format." } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The client did not provide valid authentication credentials.", "value": { "type": "https://humanlayer.io/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource." } } } } } }, "403": { "description": "Forbidden action because the caller is not the voucher.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_action": { "summary": "Forbidden Action", "description": "The client attempted to revoke a vouch they did not create.", "value": { "type": "https://humanlayer.io/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Only the voucher can revoke their own vouch." } } } } } }, "404": { "description": "The vouch does not exist or has already been revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "vouch_not_found": { "summary": "Vouch Not Found", "description": "The specified vouch ID does not correspond to an active vouch.", "value": { "type": "https://humanlayer.io/errors/not-found", "title": "Vouch Not Found", "status": 404, "detail": "No active vouch found with the provided ID." } } } } } }, "409": { "description": "Conflict because the vouch is already revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "vouch_already_revoked": { "summary": "Vouch Already Revoked", "description": "The vouch has already been revoked and cannot be revoked again.", "value": { "type": "https://humanlayer.io/errors/already-revoked", "title": "Vouch Already Revoked", "status": 409, "detail": "This vouch is not active." } } } } } }, "500": { "description": "Internal server error during vouch revocation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred while processing the revocation.", "value": { "type": "https://humanlayer.io/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while revoking the vouch. Please try again later." } } } } } } } } }, "/v1/passports/:id/recovery/guardian/initiate": { "post": { "summary": "Initiate guardian-mediated recovery process", "description": "Embark on a journey to reclaim control of your cryptographic identity through the trusted hands of your appointed guardians. This endpoint kicks off a guardian-mediated recovery process, locking the Passport for a 48-hour window, ensuring security and deliberate action.", "operationId": "initiateGuardianRecovery", "tags": [ "Identity Management", "Recovery" ], "x-code-hash": "f3345ff073c75cf4", "x-generated-at": "2026-04-12T15:57:40.147Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "The reason for initiating recovery. Helps guardians understand the context." }, "completion_mode": { "type": "string", "enum": [ "server_assembly", "client_proof" ], "description": "Defines the completion process, either controlled by the server or client." } }, "required": [ "completion_mode" ] }, "examples": { "requesting_recovery_due_to_loss": { "summary": "Requesting recovery due to loss", "description": "Initiate recovery because the user lost access to their Passport.", "value": { "reason": "Lost access to Passport", "completion_mode": "server_assembly" } } } } } }, "responses": { "201": { "description": "Recovery process successfully initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message for successful initiation." }, "lock_period": { "type": "integer", "description": "The lock period in hours before recovery execution." } } }, "examples": { "successful_initiation": { "summary": "Successful initiation", "description": "The request was processed, and the recovery sequence has begun.", "value": { "message": "Guardian recovery process initiated successfully.", "lock_period": 48 } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_completion_mode": { "summary": "Missing completion_mode", "description": "The request did not include the required completion_mode field.", "value": { "type": "https://humanlayer.io/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body is missing required fields.", "errors": [ "The 'completion_mode' field is required." ] } } } } } }, "401": { "description": "Authentication required to initiate recovery", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing authentication", "description": "The request was made without proper authentication headers.", "value": { "type": "https://humanlayer.io/errors/authentication-required", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Permission denied for initiating recovery", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "user_lacks_permission": { "summary": "User lacks permission", "description": "The user attempted to initiate recovery without the necessary permissions.", "value": { "type": "https://humanlayer.io/errors/permission-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to initiate recovery for this Passport." } } } } } }, "404": { "description": "Passport not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_passport_id": { "summary": "Invalid Passport ID", "description": "A request was made for a non-existent Passport ID.", "value": { "type": "https://humanlayer.io/errors/passport-not-found", "title": "Not Found", "status": 404, "detail": "The specified Passport ID does not exist." } } } } } }, "422": { "description": "No active guardian recovery policy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_guardian_policy": { "summary": "Missing guardian policy", "description": "The Passport does not have an active recovery policy.", "value": { "type": "https://humanlayer.io/errors/no-guardian-policy", "title": "No Guardian Recovery Policy", "status": 422, "detail": "No active guardian recovery policy found for this passport. Set up guardians first.", "remediation": [ { "step": 1, "description": "Add guardians", "link": "/v1/passports/{passportId}/recovery/guardians" } ] } } } } } }, "500": { "description": "Internal server error during recovery initiation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "An unforeseen error disrupted the recovery initiation.", "value": { "type": "https://humanlayer.io/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while initiating the recovery process." } } } } } } } } }, "/v1/passports/:id/recovery/guardian/:requestId/shard": { "get": { "summary": "Retrieve Encrypted Shamir Shard for Recovery", "description": "Guardians play a crucial role in the HUMAN network, ensuring the security and recovery of cryptographic identities. This endpoint allows a guardian to access their encrypted Shamir shard, a vital piece for identity recovery. Once decrypted client-side, the shard helps reconstruct the user's identity, safeguarding against data loss.", "operationId": "getGuardianShard", "tags": [ "Identity", "Recovery" ], "x-code-hash": "eb6cbd352d643868", "x-generated-at": "2026-04-11T02:12:47.407Z", "responses": { "200": { "description": "Successfully retrieved the encrypted shard for the guardian.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The unique identifier of the recovery request." }, "shard_index": { "type": "integer", "description": "The index of the shard in the Shamir Secret Sharing scheme." }, "encrypted_shard_b64": { "type": "string", "description": "The base64-encoded encrypted shard." }, "ephemeral_public_key_b64": { "type": "string", "description": "The base64-encoded ephemeral public key used for encryption." }, "iv_b64": { "type": "string", "description": "The base64-encoded initialization vector for the encryption algorithm." } }, "required": [ "request_id", "shard_index", "encrypted_shard_b64", "ephemeral_public_key_b64", "iv_b64" ] }, "examples": { "successful_shard_retrieval": { "summary": "Successful Shard Retrieval", "value": { "request_id": "req_123456", "shard_index": 2, "encrypted_shard_b64": "c2hhcmRfZW5jcnlwdGVkX2RhdGE=", "ephemeral_public_key_b64": "ZXBoZW1lcmFsX3B1YmtleQ==", "iv_b64": "aW5pdGlhbF92ZWN0b3I=" } } } } } }, "401": { "description": "Authentication failed for the guardian.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication Error", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Guardian must be authenticated to retrieve shard." } } } } } }, "404": { "description": "No shard found for the given guardian and request ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "shard_not_found": { "summary": "Shard Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Shard Not Found", "status": 404, "detail": "No encrypted shard found for this guardian and request. The recovery may use attestation mode (no SSS shards) or the guardian DID does not match." } } } } } }, "500": { "description": "An unexpected error occurred while retrieving the shard.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1697041626354." } } } } } } } } }, "/v1/passports/:id/recovery/guardian/:requestId/complete": { "post": { "summary": "Complete Guardian Recovery Process", "description": "Unlock your digital identity by completing the guardian recovery process. This endpoint is the final step in securing your Passport's credentials after meeting the quorum of guardians and waiting for the lock period to expire. It's not just a transaction—it's the rebirth of trust and security in your digital realm.", "operationId": "completeGuardianRecovery", "tags": [ "Identity", "Security" ], "x-code-hash": "1766e162394f190f", "x-generated-at": "2026-04-11T02:13:27.057Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "registration_id": { "type": "string", "description": "Unique identifier for the new device registration." }, "credential": { "type": "object", "description": "Cryptographic credential for the new device.", "additionalProperties": true } }, "required": [ "registration_id", "credential" ] }, "examples": { "guardian_recovery_completion_example": { "summary": "Guardian Recovery Completion Example", "description": "Completing recovery for a user moving credentials to a new device.", "value": { "registration_id": "reg_123456789", "credential": { "type": "public-key", "id": "cred_987654321", "transports": [ "usb" ] } } } } } } }, "responses": { "200": { "description": "Successfully completed guardian recovery. The credentials are now securely rotated to the new device.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Guardian recovery completed successfully." } } }, "examples": { "successful_recovery_response": { "summary": "Successful Recovery Response", "value": { "success": true, "message": "Guardian recovery completed successfully." } } } } } }, "400": { "description": "Bad Request - Invalid data provided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_registration_id": { "summary": "Missing Registration ID", "value": { "type": "https://humanlayer.io/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "registration_id is required", "errors": [ { "field": "registration_id", "message": "registration_id is required" } ] } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://humanlayer.io/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions to complete this action", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_action": { "summary": "Forbidden Action", "value": { "type": "https://humanlayer.io/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to complete this recovery." } } } } } }, "404": { "description": "Not Found - The specified recovery request does not exist", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "recovery_request_not_found": { "summary": "Recovery Request Not Found", "value": { "type": "https://humanlayer.io/errors/not-found", "title": "Not Found", "status": 404, "detail": "The recovery request ID does not match any existing requests." } } } } } }, "422": { "description": "Unprocessable Entity - Recovery conditions not met", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "recovery_not_ready": { "summary": "Recovery Not Ready", "value": { "type": "https://humanlayer.io/errors/recovery-not-ready", "title": "Recovery Not Ready", "status": 422, "detail": "Recovery cannot be completed: threshold not met, lock period not elapsed, or request not found" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "https://humanlayer.io/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/recovery/cloud-backup": { "post": { "summary": "Store Encrypted Recovery Backup", "description": "Preserve your digital identity's resilience by securely storing an encrypted recovery backup for your HUMAN Passport. This ensures you can recover your cryptographic identity even if local credentials are lost, without compromising your passphrase.", "operationId": "storeEncryptedRecoveryBackup", "tags": [ "Identity", "Security" ], "x-code-hash": "463d6caa72031c1d", "x-generated-at": "2026-04-11T02:13:40.218Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "encrypted_blob": { "type": "string", "description": "AES-256-GCM encrypted data blob", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ..." }, "storage_hint": { "type": "string", "description": "Optional storage provider hint", "enum": [ "icloud", "gdrive", "onedrive", "other" ], "example": "gdrive" } }, "required": [ "encrypted_blob" ] }, "examples": { "standard_backup": { "summary": "Standard Backup", "description": "A typical encrypted backup to Google Drive", "value": { "encrypted_blob": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...", "storage_hint": "gdrive" } } } } } }, "responses": { "201": { "description": "Backup stored successfully, indicating that your encrypted identity backup is safe and retrievable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stored": { "type": "boolean", "example": true }, "updated_at": { "type": "string", "format": "date-time", "example": "2023-10-12T07:20:50.52Z" } } }, "examples": { "successful_backup_storage": { "summary": "Successful Backup Storage", "description": "Response indicating successful storage of encrypted backup.", "value": { "stored": true, "updated_at": "2023-10-12T07:20:50.52Z" } } } } } }, "400": { "description": "The request was invalid, typically due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to invalid session or lack of passport ownership.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server, preventing the backup from being stored.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/passports/:id/recovery/cloud-backup/restore": { "post": { "summary": "Restore encrypted cloud backup", "description": "This endpoint allows users to securely restore their encrypted cloud backup for a passport, ensuring data sovereignty and privacy. By leveraging WebAuthn authentication, it verifies device ownership, facilitating client-side decryption and maintaining the integrity of sensitive information.", "operationId": "restoreCloudBackup", "tags": [ "Identity", "Security" ], "x-code-hash": "071726bc1a83b082", "x-generated-at": "2026-04-11T02:13:49.512Z", "responses": { "200": { "description": "Encrypted backup successfully retrieved for client-side decryption.", "content": { "application/json": { "schema": { "type": "object", "properties": { "encrypted_blob": { "type": "string", "description": "The encrypted backup data blob." }, "storage_hint": { "type": [ "string", "null" ], "description": "Optional hint for storage location or method." }, "backed_up_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the backup was last updated." } }, "required": [ "encrypted_blob", "backed_up_at" ] }, "examples": { "successful_backup_retrieval": { "summary": "Successful Backup Retrieval", "description": "A user successfully retrieves their encrypted cloud backup for decryption.", "value": { "encrypted_blob": "U2FsdGVkX1+I5Jql7Q==", "storage_hint": "us-east-1", "backed_up_at": "2023-10-15T14:48:00Z" } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request": { "summary": "Invalid Request", "description": "The request was malformed or had incorrect parameters.", "value": { "type": "https://humanprotocol.org/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The request parameters are invalid. Ensure the passport ID is correct and try again." } } } } } }, "401": { "description": "Unauthorized due to failed WebAuthn authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_failed": { "summary": "Authentication Failed", "description": "The user is not authenticated with WebAuthn.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "WebAuthn authentication failed. Please authenticate with a valid device and try again." } } } } } }, "403": { "description": "Forbidden access due to permission issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "The user attempted to access a backup for a different passport.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You can only restore a backup for your own passport. Check the passport ID and try again." } } } } } }, "404": { "description": "Not found error if the backup does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "backup_not_found": { "summary": "Backup Not Found", "description": "No backup found for the provided passport ID.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "No cloud backup found for the specified passport ID. Verify the ID and ensure a backup exists before retrying." } } } } } }, "500": { "description": "Internal server error during backup restoration.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while restoring the backup. Please try again later. If the issue persists, contact support with the reference ID: inc_1698422800000." } } } } } } } } }, "/v1/passports/:id/verify/credential": { "post": { "summary": "Verify Verifiable Credential for Passport", "description": "Elevate your digital identity by submitting a Verifiable Credential, pushing your identity tier to 3. This endpoint verifies credentials from trusted issuers, ensuring your identity is both secure and recognized. An advanced identity tier opens doors to more opportunities within the HUMAN ecosystem.", "operationId": "verifyCredentialById", "tags": [ "Identity", "Verification" ], "x-code-hash": "9bb5ec62506665a4", "x-generated-at": "2026-04-11T02:14:06.906Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the credential." }, "issuer": { "type": "string", "description": "DID of the issuer." }, "type": { "type": "array", "items": { "type": "string" }, "description": "Types associated with the credential." }, "issuanceDate": { "type": "string", "format": "date-time", "description": "Date when the credential was issued." }, "credentialSubject": { "type": "object", "properties": { "id": { "type": "string", "description": "DID of the subject to whom the credential refers." } } } }, "required": [ "id" ] } } }, "examples": { "valid_credential_submission": { "summary": "Valid Credential Submission", "description": "A credential submission for an identity verification.", "value": { "credential": { "id": "cred-12345", "issuer": "did:example:issuer123", "type": [ "VerifiableCredential", "IdentityCredential" ], "issuanceDate": "2023-10-01T12:00:00Z", "credentialSubject": { "id": "did:example:holder123" } } } } } } } }, "responses": { "201": { "description": "Credential verified successfully, identity tier advanced to 3.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity_tier": { "type": "integer", "example": 3 }, "credential_id": { "type": "string", "example": "cred-12345" } } }, "examples": { "default": { "summary": "Example", "value": { "identity_tier": 3, "credential_id": "cred-12345" } } } } } }, "400": { "description": "Bad Request due to missing or invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/validation", "title": "Validation Error", "status": 400, "detail": "credential.id is required (attestation row ID)", "errors": [ { "field": "credential.id", "code": "REQUIRED_FIELD_MISSING", "message": "credential.id is required (attestation row ID)", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access when attempting to verify a credential for a different passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/authorization", "title": "Unauthorized", "status": 401, "detail": "You can only submit credentials for your own passport" } } } } } }, "403": { "description": "Credential issuer not recognized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/issuer-not-allowed", "title": "Credential Issuer Not Recognized", "status": 403, "detail": "Issuer did:example:issuer123 is not in the recognized credential issuer list" } } } } } }, "404": { "description": "Passport or credential not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested passport or credential was not found." } } } } } }, "422": { "description": "Credential verification failed due to KYC requirements.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/kyc-required", "title": "KYC Verification Required First", "status": 422, "detail": "Identity Tier 2 (KYC-Verified) is required before adding credential verification (Tier 3)", "remediation": [ { "step": 1, "description": "Complete KYC verification", "link": "/v1/passports/did:example:holder123/verify/biometric" } ] } } } } } }, "500": { "description": "Internal server error during credential verification.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/verify/personhood": { "post": { "summary": "Initiate Proof of Personhood verification", "description": "Embark on a journey to establish the authenticity of an individual's identity through the Proof of Personhood process. This operation ensures that the passport in question truly belongs to a human, reinforcing trust in the HUMAN network.", "operationId": "initiateProofOfPersonhood", "tags": [ "Identity", "Verification" ], "x-code-hash": "db2c028cec96432f", "x-generated-at": "2026-04-11T02:14:21.115Z", "responses": { "201": { "description": "Successfully initiated a Proof of Personhood session, providing session details for the user to complete verification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique identifier for the Proof of Personhood session." }, "redirect_url": { "type": "string", "description": "URL where the user can complete the verification process." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the session expires." }, "provider": { "type": "string", "description": "The name of the provider managing the verification process." } } }, "examples": { "successful_initiation": { "summary": "Successful Initiation", "description": "Initiating a session for Proof of Personhood verification.", "value": { "session_id": "pop-1234567890", "redirect_url": "https://verification.provider.com/session/pop-1234567890", "expires_at": "2023-10-30T15:00:00Z", "provider": "VerificationProvider" } } } } } }, "400": { "description": "Bad Request - The request could not be understood by the server due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_parameters": { "summary": "Missing Parameters", "description": "The request did not include all necessary parameters.", "value": { "type": "https://humanlayer.io/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The request is missing required parameters." } } } } } }, "401": { "description": "Unauthorized - Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_token": { "summary": "Invalid Token", "description": "The request was made with an invalid or missing authorization token.", "value": { "type": "https://humanlayer.io/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization token is missing or invalid." } } } } } }, "403": { "description": "Forbidden - The server understood the request, but refuses to authorize it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_passport_access": { "summary": "Unauthorized Passport Access", "description": "Attempting to initiate verification for a passport that is not owned by the requester.", "value": { "type": "https://humanlayer.io/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You can only initiate PoP verification for your own passport." } } } } } }, "404": { "description": "Not Found - The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "The passport DID specified in the request does not correspond to an active passport.", "value": { "type": "https://humanlayer.io/errors/not-found", "title": "Not Found", "status": 404, "detail": "The passport with the given DID does not exist or is inactive." } } } } } }, "409": { "description": "Conflict - The request could not be completed due to a conflict with the current state of the target resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "already_verified": { "summary": "Already Verified", "description": "The passport is already verified at the required level.", "value": { "type": "https://humanlayer.io/errors/already-verified", "title": "Already Proof-of-Personhood Verified", "status": 409, "detail": "This passport already has Proof of Personhood (Layer 4)." } } } } } }, "500": { "description": "Internal Server Error - The server encountered an unexpected condition which prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://humanlayer.io/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1234567890." } } } } } } } } }, "/v1/passports/:id/verify/personhood/webhook": { "post": { "summary": "Verify Proof of Personhood via Webhook", "description": "This endpoint receives and processes the Proof of Personhood (PoP) verification from a provider. By advancing the verification tier to 4, it ensures the cryptographic identity represented by a Passport is uniquely tied to a human, preventing duplicate identities in the HUMAN ecosystem.", "operationId": "verifyPersonhoodWebhook", "tags": [ "Verification", "Identity" ], "x-code-hash": "bf2b872cad3dbc83", "x-generated-at": "2026-04-11T02:14:29.512Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nullifierHash": { "type": "string", "description": "Unique hash representing the verified individual." }, "provider": { "type": "string", "description": "The PoP provider processing the request." }, "signature": { "type": "string", "description": "Signature verifying the authenticity of the webhook call." } }, "required": [ "nullifierHash", "provider" ] }, "examples": { "standard_pop_verification": { "summary": "Standard PoP Verification", "description": "A typical PoP verification result from the provider.", "value": { "nullifierHash": "abc123xyz456", "provider": "trusted_pop_provider", "signature": "signed_payload_hash" } } } } } }, "responses": { "200": { "description": "Successfully verified and advanced to tier 4.", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" }, "status": { "type": "string" }, "verification_tier": { "type": "integer" } } }, "examples": { "default": { "summary": "Example", "value": { "received": true, "status": "verified", "verification_tier": 4 } } } } } }, "409": { "description": "Conflict: Duplicate nullifier hash detected.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/docs/errors/duplicate-passport", "title": "Duplicate Passport Detected", "status": 409, "detail": "Passport already exists for this person. Use recovery if you lost access to your previous Passport." } } } } } }, "500": { "description": "Internal server error during PoP verification.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/docs/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the PoP verification. Please try again later." } } } } } } } } }, "/v1/vault/shared-with-me": { "get": { "summary": "Retrieve documents shared with user", "description": "Uncover the vault documents that others have explicitly shared with you. This endpoint empowers the authenticated user by listing shared documents, ensuring you're always in the know. Ideal for collaboration and transparency, it securely returns metadata, omitting encrypted content, and handles pagination gracefully.", "operationId": "getVaultDocumentsSharedWithMe", "tags": [ "Vault", "SharedDocuments" ], "x-code-hash": "02b7807c589b5f33", "x-generated-at": "2026-04-09T21:35:35.218Z", "responses": { "200": { "description": "Successfully retrieved a list of documents shared with the user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "doc_id": { "type": "string", "description": "Unique identifier for the document." }, "entity_did": { "type": "string", "description": "DID of the entity that owns the document." }, "namespace": { "type": "string", "description": "Namespace categorizing the document." }, "collection": { "type": "string", "description": "Collection name containing the document." }, "metadata": { "type": "object", "description": "Additional metadata related to the document." }, "wrapped_dek": { "type": "string", "description": "Base64 encoded wrapped Data Encryption Key." }, "granted_by": { "type": "string", "description": "DID of the user who granted access to the document." }, "granted_at": { "type": "string", "format": "date-time", "description": "Timestamp when access was granted." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when access expires, null if no expiration." } } } }, "has_more": { "type": "boolean", "description": "Indicates if more documents are available beyond the current page." }, "next_cursor": { "type": "string", "nullable": true, "description": "Cursor for the next set of results, null if no more results." } } }, "examples": { "acme_corp_shared_documents": { "summary": "Acme Corp Shared Documents", "description": "A list of documents shared with a user from the 'acme' organization.", "value": { "data": [ { "doc_id": "abc123", "entity_did": "did:human:acme123", "namespace": "finance", "collection": "invoices", "metadata": { "title": "Q3 Invoice", "amount": "$15,000" }, "wrapped_dek": "base64encodedkey==", "granted_by": "did:human:john.doe", "granted_at": "2023-10-15T10:00:00Z", "expires_at": null } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Invalid request parameters were provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "An invalid cursor was provided, causing a validation error.", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The provided pagination cursor is not valid. Ensure it is a valid cursor token from a previous response.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or not been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "description": "The request is missing a valid delegation token.", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Delegation token is required to access shared documents. Ensure you are authenticated and include a valid delegation token." } } } } } }, "403": { "description": "The user does not have the necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_forbidden": { "summary": "Access Forbidden", "description": "The user does not have permission to view shared documents.", "value": { "type": "https://example.com/probs/permission-error", "title": "Access Forbidden", "status": 403, "detail": "You do not have the required permissions to view documents shared with you. Check your access rights with your administrator." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "The requested document does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The document you are trying to access does not exist or is not shared with you." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected server error occurred.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passports/:did/disclosures/request": { "post": { "summary": "Create a Passport Disclosure Request", "description": "Submit a request for specific attribute disclosures from a HUMAN passport. This endpoint empowers organizations to verify identity claims while respecting user consent and privacy policies, ensuring a secure and transparent process.", "operationId": "createPassportDisclosureRequest", "tags": [ "Identity", "Disclosure" ], "x-code-hash": "5a4a5bbb89d86c10", "x-generated-at": "2026-04-12T20:27:35.968Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requester_did": { "type": "string", "description": "DID of the entity requesting disclosure" }, "requested_claims": { "type": "object", "description": "Attributes being requested for disclosure" }, "purpose": { "type": "string", "description": "Purpose for requesting the disclosure" }, "expires_in_seconds": { "type": "integer", "description": "Time in seconds until the request expires" }, "proof_type": { "type": "string", "description": "Type of proof required for the disclosure" }, "range_proofs": { "type": "object", "description": "Optional range proofs for verifying claims" } }, "required": [ "requester_did", "requested_claims", "purpose", "expires_in_seconds", "proof_type" ] }, "examples": { "basic_disclosure_request": { "summary": "Basic Disclosure Request", "description": "A request for verifying age attribute with a proof type of 'zero-knowledge'.", "value": { "requester_did": "did:human:acme:org", "requested_claims": { "age": true }, "purpose": "Verify age for age-restricted service", "expires_in_seconds": 3600, "proof_type": "zero-knowledge", "range_proofs": { "age": { "min": 18, "max": 120 } } } } } } } }, "responses": { "201": { "description": "The disclosure request was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique identifier for the disclosure request" }, "status": { "type": "string", "enum": [ "pending", "granted", "denied" ], "description": "Current status of the disclosure request" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the request was created" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the request will expire" }, "proof_type": { "type": "string", "description": "Type of proof required for the disclosure" }, "consent_policy_id": { "type": "string", "description": "ID of the matched consent policy" } }, "required": [ "request_id", "status", "created_at", "expires_at", "proof_type" ] }, "examples": { "default": { "summary": "Example", "value": { "request_id": "pdr_12345", "status": "pending", "created_at": "2023-10-01T10:00:00Z", "expires_at": "2023-10-01T11:00:00Z", "proof_type": "zero-knowledge", "consent_policy_id": "policy_6789" } } } } } }, "400": { "description": "Invalid request format or data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Authorization error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Passport not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/passports/:did/disclosures/pending": { "get": { "summary": "Retrieve pending disclosures for a Passport", "description": "Explore the intricacies of managing digital identity by retrieving pending disclosure requests linked to a specific Passport. This endpoint allows users to track and manage requests, ensuring transparency and control over their personal data.", "operationId": "getPendingDisclosures", "tags": [ "Identity", "Data Management" ], "x-code-hash": "8217de304dfb30a6", "x-generated-at": "2026-04-11T02:14:59.307Z", "responses": { "200": { "description": "Successfully retrieved the list of pending disclosure requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "request_id": { "type": "string" }, "requester_did": { "type": "string" }, "requested_claims": { "type": "array", "items": { "type": "string" } }, "purpose": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } } }, "examples": { "successful_retrieval_of_disclosures": { "summary": "Successful retrieval of disclosures", "value": { "data": [ { "request_id": "abc123", "requester_did": "did:human:acme-org", "requested_claims": [ "email", "phone" ], "purpose": "Verification for service access", "created_at": "2023-10-01T10:00:00Z", "expires_at": "2023-11-01T10:00:00Z" } ], "limit": 10, "cursorFields": [ "created_at", "request_id" ], "hasMore": false } } } } } }, "400": { "description": "The request was malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_parameter": { "summary": "Invalid cursor parameter", "value": { "type": "https://example.com/probs/invalid-parameter", "title": "Invalid Request", "status": 400, "detail": "The cursor parameter is invalid. Ensure it follows the expected format." } } } } } }, "401": { "description": "The caller is not authenticated to perform this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication required", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access pending disclosures. Please login and try again." } } } } } }, "403": { "description": "Access to the requested disclosures is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_to_disclosures": { "summary": "Unauthorized access to disclosures", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You are not authorized to view disclosures for this Passport. Access is restricted to the Passport owner." } } } } } }, "404": { "description": "The requested Passport or disclosures were not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport not found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The Passport with DID did:human:unknown was not found. Verify the DID is correct." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred processing your request. Contact support if the problem persists." } } } } } } } } }, "/v1/passports/:did/disclosures/:requestId/grant": { "post": { "summary": "Grant Disclosure on Human Passport", "description": "Enable trusted sharing of verified capabilities by granting disclosure requests on a Human Passport. This endpoint empowers users to selectively share their validated skills, ensuring transparency and trust in Human-AI collaborations.", "operationId": "grantDisclosure", "tags": [ "Passport", "Disclosure" ], "x-code-hash": "6631722659cc6a93", "x-generated-at": "2026-04-12T20:27:46.528Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approved_claims": { "type": "array", "items": { "type": "string" }, "description": "List of claims approved for disclosure." } }, "required": [ "approved_claims" ] }, "examples": { "grant_disclosure_example": { "summary": "Grant Disclosure Example", "description": "A user approves specific claims for an organization.", "value": { "approved_claims": [ "skill:python", "experience:5_years" ] } } } } } }, "responses": { "200": { "description": "Successfully granted disclosure for the approved claims.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Disclosure granted" }, "granted_claims": { "type": "array", "items": { "type": "string" } } } }, "examples": { "default": { "summary": "Example", "value": { "status": "Disclosure granted", "granted_claims": [ "skill:python", "experience:5_years" ] } } } } } }, "400": { "description": "Invalid request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/validation-error", "title": "Bad Request", "status": 400, "detail": "Request body must be JSON", "errors": [ { "field": "body", "message": "Request body must be JSON" } ] } } } } } }, "401": { "description": "Authentication required to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Unauthorized", "status": 401, "detail": "Authentication required" } } } } } }, "403": { "description": "Only the subject of the passport can grant disclosures.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authorization-error", "title": "Forbidden", "status": 403, "detail": "Only the subject passport may grant disclosure" } } } } } }, "404": { "description": "Passport not found for the provided DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Passport not found" } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Internal error, please try again later" } } } } } } } } }, "/v1/passports/:did/disclosures/:requestId/deny": { "post": { "summary": "Deny a disclosure request for a passport", "description": "In the dance of identity and privacy, sometimes a request must be refused. This endpoint allows a passport holder to deny a pending disclosure request, ensuring that only the rightful owner can manage their personal information. It's a safeguard in the HUMAN protocol's commitment to user autonomy and privacy.", "operationId": "denyDisclosureRequest", "tags": [ "Identity", "Privacy" ], "x-code-hash": "468a360f822ec51d", "x-generated-at": "2026-04-11T02:15:25.397Z", "responses": { "200": { "description": "The disclosure request was successfully denied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The unique identifier of the disclosure request." }, "status": { "type": "string", "enum": [ "denied" ], "description": "The new status of the disclosure request." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was malformed, possibly due to an invalid state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/invalid-state", "title": "Invalid State", "status": 400, "detail": "Disclosure request is not pending.", "errors": [ { "field": "request_id", "code": "INVALID_STATE", "message": "Disclosure request is not pending", "expected": "pending", "received": "approved" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required. Please ensure you have the necessary credentials." } } } } } }, "403": { "description": "The user does not have permission to deny this disclosure request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/authorization-error", "title": "Authorization Error", "status": 403, "detail": "Only the subject passport may deny disclosure. Verify your identity and try again." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested passport or disclosure request was not found. Please check the DID and request ID." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Reference: inc_1697032800000." } } } } } } } } }, "/v1/passports/:did/devices/sync/initiate": { "post": { "summary": "Initiate a device sync session for a Passport", "description": "Embarking on a new journey with your Passport's devices, this endpoint initiates a synchronization process. It ensures that only authorized devices can partake in this dance of data, safeguarding your cryptographic identity with precision and trust.", "operationId": "initiateDeviceSync", "tags": [ "Passports", "Devices" ], "x-code-hash": "1871fdc2a5d4be15", "x-generated-at": "2026-04-12T15:45:02.839Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiating_device_id": { "type": "string", "description": "The ID of the device initiating the sync." }, "current_device_signature": { "type": "string", "description": "The JWS signature from the current device." }, "ephemeral_public_key": { "type": "string", "description": "Ephemeral public key for secure communication." }, "p2p_capable": { "type": "boolean", "description": "Flag indicating if the session supports peer-to-peer mode." } }, "required": [ "initiating_device_id", "current_device_signature", "ephemeral_public_key" ] }, "examples": { "standard_device_sync_initiation": { "summary": "Standard Device Sync Initiation", "description": "Initiating a sync session with essential details and optional P2P capability.", "value": { "initiating_device_id": "device123", "current_device_signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...", "ephemeral_public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQ...", "p2p_capable": true } } } } } }, "responses": { "200": { "description": "Successfully initiated the device sync session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The unique session identifier for the sync process." }, "qr_payload": { "type": "object", "description": "Payload containing QR code data for syncing." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session expires." }, "p2p_mode": { "type": "boolean", "description": "Indicates if peer-to-peer mode is enabled." }, "signal_url": { "type": "string", "description": "URL for signaling in peer-to-peer mode.", "nullable": true } } }, "examples": { "successful_sync_initiation": { "summary": "Successful Sync Initiation", "value": { "session_id": "sess-abc123", "qr_payload": { "qr_nonce": "nonce-xyz789", "expires_at": "2023-11-15T15:00:00Z" }, "expires_at": "2023-11-15T15:00:00Z", "p2p_mode": true, "signal_url": "/v1/passports/did%3Ahuman%3A1234/devices/sync/sess-abc123/signal" } } } } } }, "400": { "description": "Validation errors occurred due to missing or invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "You do not have permission to initiate sync for this Passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The device specified could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred during the sync initiation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/passports/:did/devices/sync/approve": { "post": { "summary": "Approve device sync for a HUMAN passport", "description": "In the tapestry of the HUMAN platform, this endpoint acts as a gatekeeper, ensuring only rightful devices can sync with a user's passport. By approving a sync session, users authenticate and authorize their devices, maintaining the integrity and security of their digital identity.", "operationId": "approveDeviceSync", "tags": [ "Passport", "Device Management" ], "x-code-hash": "0da347ad8f53c622", "x-generated-at": "2026-04-12T15:45:14.812Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique identifier for the sync session" }, "current_device_signature": { "type": "string", "description": "JWS signature from the current device" }, "new_device_ephemeral_public_key": { "type": "string", "description": "Ephemeral public key for the new device" }, "encrypted_vault_envelope": { "type": "string", "description": "Encrypted vault envelope required in non-P2P mode", "nullable": true } }, "required": [ "session_id", "current_device_signature", "new_device_ephemeral_public_key" ] }, "examples": { "typical_sync_approval": { "summary": "Typical Sync Approval", "description": "Approving a device sync with all necessary fields", "value": { "session_id": "session12345", "current_device_signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...", "new_device_ephemeral_public_key": "04bfcab3...abc", "encrypted_vault_envelope": "e3d9a1f...f9d" } } } } } }, "responses": { "200": { "description": "Device sync approved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_attestation": { "type": "string", "description": "JWT attestation for the new device" }, "encrypted_vault_envelope": { "type": "string", "description": "The encrypted vault envelope, if applicable", "nullable": true } } }, "examples": { "default": { "summary": "Example", "description": "Successful sync approval in P2P mode", "value": { "device_attestation": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } }, "400": { "description": "Validation error due to missing or invalid fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Example of a validation error", "value": { "type": "https://humanprotocol.org/docs/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "Validation failed on provided input", "errors": [ { "field": "current_device_signature", "code": "INVALID_DEVICE_SIGNATURE", "message": "JWS could not be verified", "expected": "ES256 JWS", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication required to approve a sync session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Example of an authentication error", "value": { "type": "https://humanprotocol.org/docs/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required to approve the sync session" } } } } } }, "403": { "description": "Authorization error when attempting to approve another's sync session", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Example of an authorization error", "value": { "type": "https://humanprotocol.org/docs/errors/authorization-required", "title": "Authorization Required", "status": 403, "detail": "You may only approve sync for your own passport" } } } } } }, "404": { "description": "Sync session or device not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Example of a not found error", "value": { "type": "https://humanprotocol.org/docs/errors/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested sync session or device could not be found" } } } } } }, "500": { "description": "Internal server error during sync approval process", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "description": "Example of a server error", "value": { "type": "https://humanprotocol.org/docs/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during the sync approval process" } } } } } } } } }, "/v1/passports/:did/devices/sync/complete": { "post": { "summary": "Complete Device Sync for Passport", "description": "Securely finalize the synchronization of a new device with your HUMAN Passport, ensuring the integrity of cryptographic identity at every step. This endpoint not only validates the device's credentials but also reinforces trust through stringent attestation checks.", "operationId": "completeDeviceSync", "tags": [ "Identity", "Device Management" ], "x-code-hash": "1ed6dc8ee4b65e81", "x-generated-at": "2026-04-11T02:16:08.591Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Session ID for the sync process." }, "device_attestation": { "type": "string", "description": "JWT for attesting the device's validity." }, "new_device_name": { "type": "string", "maxLength": 100, "description": "A human-readable identifier for the new device." }, "new_device_public_key": { "type": "string", "description": "Public key associated with the new device." } }, "required": [ "session_id", "device_attestation", "new_device_name", "new_device_public_key" ] }, "examples": { "sync_a_new_device": { "summary": "Sync a New Device", "description": "Example of completing device sync for a new device named 'AcmeLaptop'.", "value": { "session_id": "abc123-session", "device_attestation": "eyJhbGciOiJIUzI1NiIsInR...", "new_device_name": "AcmeLaptop", "new_device_public_key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBA..." } } } } } }, "responses": { "200": { "description": "Successfully completed the device sync, returning the device identifier and enrollment time.", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string", "description": "Unique identifier for the newly enrolled device." }, "enrolled_at": { "type": "string", "format": "date-time", "description": "Timestamp when the device was enrolled." } } }, "examples": { "default": { "summary": "Example", "value": { "device_id": "device-12345", "enrolled_at": "2023-10-01T12:45:00Z" } } } } } }, "400": { "description": "Invalid request parameters or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/validation", "title": "Invalid Request", "status": 400, "detail": "session_id, device_attestation, new_device_name, new_device_public_key required", "errors": [ { "field": "body", "code": "REQUIRED_FIELD_MISSING", "message": "session_id, device_attestation, new_device_name, new_device_public_key required" } ] } } } } } }, "401": { "description": "Authentication is required to complete this request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication", "title": "Authentication Required", "status": 401, "detail": "Authentication required" } } } } } }, "403": { "description": "User does not have permission to complete sync for another passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authorization", "title": "Authorization Error", "status": 403, "detail": "You may only complete sync for your own passport" } } } } } }, "404": { "description": "The specified session or DID could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Session or DID not found" } } } } } }, "500": { "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "Attestation verification failed" } } } } } } } } }, "/v1/passports/:did/ledger-anchor": { "get": { "summary": "Retrieve Passport's Latest Ledger Anchor", "description": "Unlock the cryptographic trail of your identity with this endpoint, offering a peek into the most recent ledger anchor of a Human Passport. This ensures trust and transparency as you explore the digital provenance of skills and tasks.", "operationId": "getPassportLedgerAnchor", "tags": [ "Passports", "Ledger" ], "x-code-hash": "cb05ca58b5d900a9", "x-generated-at": "2026-04-11T02:37:00.603Z", "responses": { "200": { "description": "Successfully retrieved the latest ledger anchor for the specified DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" }, "anchor_id": { "type": "string" }, "batch_id": { "type": "string" }, "merkle_root": { "type": "string" }, "merkle_proof": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "left", "right" ] }, "hash": { "type": "string" } } } }, "leaf_index": { "type": "integer" }, "leaf_hash": { "type": "string" }, "transaction_hash": { "type": "string" }, "block_number": { "type": "integer" }, "chain_id": { "type": "integer" }, "chain_name": { "type": "string" }, "anchored_at": { "type": "string", "format": "date-time" } }, "required": [ "did", "anchor_id", "batch_id", "merkle_root", "leaf_index", "leaf_hash", "transaction_hash", "block_number", "chain_id", "chain_name", "anchored_at" ] }, "examples": { "successful_retrieval_example": { "summary": "Successful retrieval example", "value": { "did": "did:human:123456789abcdefghi", "anchor_id": "anchor123", "batch_id": "batch456", "merkle_root": "abcd1234efgh5678ijkl9101mnopqrst", "merkle_proof": [ { "position": "left", "hash": "abcd1234" }, { "position": "right", "hash": "efgh5678" } ], "leaf_index": 1, "leaf_hash": "mnop1234qrst5678", "transaction_hash": "tx1234567890abcdef", "block_number": 123456, "chain_id": 42, "chain_name": "Ethereum Mainnet", "anchored_at": "2023-10-01T12:00:00Z" } } } } } }, "202": { "description": "The passport is queued for anchoring and will be processed soon.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ] }, "queue_position": { "type": "integer" }, "estimated_anchor_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "queue_position", "estimated_anchor_at" ] }, "examples": { "queuing_example": { "summary": "Queuing example", "value": { "status": "pending", "queue_position": 5, "estimated_anchor_at": "2023-10-01T13:00:00Z" } } } } } }, "400": { "description": "The request was malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_did_format": { "summary": "Invalid DID format", "value": { "type": "https://example.com/probs/invalid-did", "title": "Invalid DID", "status": 400, "detail": "The provided DID is not in the correct format. Ensure it starts with 'did:human:'." } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing authentication", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to retrieve this passport's ledger anchor. Please log in and try again." } } } } } }, "403": { "description": "You are not authorized to view this passport's ledger anchor.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You are only allowed to access ledger anchors for your own passport." } } } } } }, "404": { "description": "The specified ledger anchor could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ledger_anchor_not_found": { "summary": "Ledger anchor not found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "A ledger anchor for the DID 'did:human:123456789abcdefghi' was not found." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/passports/:did/ledger-anchor/verify": { "post": { "summary": "Verify Passport Ledger Anchor Inclusion", "description": "Ensure your digital identity's anchoring is secure by verifying its inclusion in the blockchain's Merkle tree. This endpoint empowers users to authenticate their Passport's ledger integrity, reinforcing trust in decentralized identity management.", "operationId": "verifyPassportLedgerAnchor", "tags": [ "Identity", "Blockchain" ], "x-code-hash": "204a0057b7cbd979", "x-generated-at": "2026-04-11T02:37:13.107Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merkle_proof": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "left", "right" ] }, "hash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" } }, "required": [ "position", "hash" ] } }, "leaf_hash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" } }, "required": [ "merkle_proof", "leaf_hash" ] }, "examples": { "valid_merkle_proof_example": { "summary": "Valid Merkle Proof Example", "description": "A valid Merkle proof with corresponding leaf hash for identity verification.", "value": { "merkle_proof": [ { "position": "left", "hash": "0xabcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234" }, { "position": "right", "hash": "0x1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd" } ], "leaf_hash": "0xabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd" } } } } } }, "responses": { "200": { "description": "The Merkle proof is valid and the identity is securely anchored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "on_chain_ref": { "type": "object", "properties": { "transaction_hash": { "type": "string" }, "block_number": { "type": "integer" }, "chain_id": { "type": "integer" }, "chain_name": { "type": "string" } } }, "reason": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "valid": true, "on_chain_ref": { "transaction_hash": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef", "block_number": 123456, "chain_id": 1, "chain_name": "Ethereum Mainnet" } } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "User authentication failed due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required" } } } } } }, "403": { "description": "Authorization failed because the user attempted to verify an anchor for a different Passport.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/authorization-failed", "title": "Forbidden", "status": 403, "detail": "You may only verify anchors for your own passport" } } } } } }, "404": { "description": "The requested Passport ledger anchor could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Ledger anchor for did:human:123456789abcdef not found" } } } } } }, "500": { "description": "A server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:did/disclosures/:requestId": { "get": { "summary": "Retrieve Passport Disclosure Details", "description": "Unearth the cryptographic secrets of a Passport with this endpoint, which reveals the story behind a specific disclosure request. This endpoint is your key to understanding the intricate dance of data between a subject and requester, spotlighting the purpose, status, and cryptographic proofs involved.", "operationId": "getPassportDisclosureDetails", "tags": [ "Passport", "Disclosure" ], "x-code-hash": "d635a0c3f9a99a16", "x-generated-at": "2026-04-12T15:44:50.519Z", "responses": { "200": { "description": "Retrieves the details of a passport disclosure request, including status and cryptographic proofs if granted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "subject_did": { "type": "string" }, "requester_did": { "type": "string" }, "requested_claims": { "type": "array", "items": { "type": "string" } }, "purpose": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "proof_type": { "type": "string" }, "bbs_credential": { "type": "object" }, "verifier_challenge": { "type": "string" }, "disclosed_claims": { "type": "array", "items": { "type": "string" } }, "sd_jwt_presentation": { "type": "string" } } }, "examples": { "successful_disclosure_retrieval": { "summary": "Successful Disclosure Retrieval", "description": "A successful retrieval of a disclosure request for a Passport, with all cryptographic details included.", "value": { "request_id": "12345", "subject_did": "did:human:acme:john.doe", "requester_did": "did:human:acme:trusted.partner", "requested_claims": [ "birthdate", "address" ], "purpose": "Verification of identity for onboarding", "status": "granted", "created_at": "2023-10-05T12:34:56Z", "expires_at": "2023-12-31T23:59:59Z", "resolved_at": "2023-10-10T14:22:01Z", "proof_type": "bbs", "bbs_credential": { "credential": "BBS_PROOF" }, "verifier_challenge": "challenge_string", "disclosed_claims": [ "birthdate: 1990-01-01", "address: 123 Main St" ] } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_did_format": { "summary": "Invalid DID Format", "value": { "type": "https://example.com/probs/invalid-did-format", "title": "Invalid DID Format", "status": 400, "detail": "The DID must start with 'did:human:'. Ensure your input conforms to the expected format." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access this endpoint. Please provide valid authentication credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://example.com/probs/access-denied", "title": "Access Denied", "status": 403, "detail": "You are not authorized to access this disclosure request. Ensure you have the necessary permissions." } } } } } }, "404": { "description": "Resource not found due to non-existent DID or request ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "disclosure_request_not_found": { "summary": "Disclosure Request Not Found", "value": { "type": "https://example.com/probs/disclosure-request-not-found", "title": "Disclosure Request Not Found", "status": 404, "detail": "The disclosure request with the given ID does not exist. Verify the request ID and try again." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support with the incident ID: inc_1672531199." } } } } } } } } }, "/v1/humanos/route": { "post": { "summary": "Route tasks with HumanOS AI orchestration", "description": "This endpoint is a gateway to orchestrate tasks efficiently using the HumanOS routing capabilities. By combining AI-driven insights with human skills, it ensures tasks are assigned to the most suitable agents. This promotes seamless interaction between humans and AI, optimizing task outcomes.", "operationId": "routeTaskWithHumanOS", "tags": [ "HumanOS", "Task Routing" ], "x-code-hash": "2ecd6d944e45c0c2", "x-generated-at": "2026-04-11T02:38:28.824Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "description": "Unique identifier for the task" }, "task_type": { "type": "string", "description": "Type of task to be routed" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Priority level of the task" }, "metadata": { "type": "object", "description": "Additional data related to the task" } }, "required": [ "task_id", "task_type" ] }, "examples": { "standard_task_routing": { "summary": "Standard Task Routing", "description": "Routing a high-priority customer support task", "value": { "task_id": "task-12345", "task_type": "customer_support", "priority": "high", "metadata": { "customer_id": "cust-67890", "issue": "billing inquiry" } } } } } } }, "responses": { "200": { "description": "The task was successfully routed to the appropriate agent or team.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Confirmation of task routing success" }, "agent_id": { "type": "string", "description": "The ID of the agent or team assigned to the task" } }, "required": [ "status", "agent_id" ] }, "examples": { "successful_task_routing": { "summary": "Successful Task Routing", "value": { "status": "routed", "agent_id": "agent-98765" } } } } } }, "400": { "description": "The request was malformed or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_task_id": { "summary": "Missing Task ID", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "task_id and task_type are required", "errors": [ { "field": "task_id", "code": "REQUIRED_FIELD_MISSING", "message": "task_id and task_type are required", "expected": "task_id + task_type", "received": "incomplete" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "The request was understood but refused by the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Access to this resource is forbidden" } } } } } }, "404": { "description": "The specified resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested task routing resource was not found" } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/route/fraud-case": { "post": { "summary": "Route fraud case for human intervention", "description": "In the intricate dance of AI and human collaboration, this endpoint orchestrates the routing of potential fraud cases to human agents for further investigation. It ensures that suspicious activities don't slip through the cracks of automation, safeguarding the integrity of your operations.", "operationId": "routeFraudCase", "tags": [ "HumanOS", "FraudDetection" ], "x-code-hash": "6e47924d2e6156bc", "x-generated-at": "2026-04-11T02:38:47.556Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "case_ref": { "type": "string", "description": "A unique reference for the fraud case" } }, "required": [ "case_ref" ] }, "examples": { "standard_fraud_case": { "summary": "Standard Fraud Case", "description": "Routing a fraud case with a unique reference to human agents.", "value": { "case_ref": "fraud_case_12345" } } } } } }, "responses": { "201": { "description": "The fraud case has been successfully routed to a human agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "routing_id": { "type": "string", "description": "Unique identifier for the routing operation" }, "case_ref": { "type": "string", "description": "The reference of the fraud case" }, "routing_decision": { "type": "string", "description": "Decision taken to route the case to a human" }, "reason": { "type": "string", "description": "Reason for routing decision" }, "fourth_law_triggered": { "type": "boolean", "description": "Indicates if the AI safety protocol was triggered" }, "recorded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the routing decision was recorded" } } }, "examples": { "default": { "summary": "Example", "value": { "routing_id": "cp_frt_67890", "case_ref": "fraud_case_12345", "routing_decision": "route_to_human", "reason": "fraud_investigation_default", "fourth_law_triggered": true, "recorded_at": "2023-10-11T08:30:00Z" } } } } } }, "400": { "description": "Bad Request: The request body is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized: Delegation required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden: You do not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error: Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/humanos/route/:routingId/risk": { "get": { "summary": "Assess risk of a routed task", "description": "Uncover the hidden risks associated with a specific task routed through the HUMAN platform. This endpoint provides a risk score for a task, ensuring that potential issues are flagged early, allowing for proactive management and AI safety.", "operationId": "getHumanosRouteRisk", "tags": [ "HumanOS", "Risk Assessment" ], "x-code-hash": "f8be7be0c08a8012", "x-generated-at": "2026-04-11T02:39:10.303Z", "responses": { "200": { "description": "Successfully retrieves the risk score and details for the specified routing task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "routing_id": { "type": "string", "description": "The unique identifier for the routing task." }, "agent_did": { "type": "string", "description": "The decentralized identifier (DID) of the organization requesting the risk assessment." }, "task_description": { "type": "string", "description": "A brief description of the task associated with the routing ID." }, "risk_score": { "type": "number", "description": "The calculated risk score for the task." }, "scored_at": { "type": "string", "format": "date-time", "description": "The timestamp when the risk score was calculated." } }, "required": [ "routing_id", "agent_did", "risk_score", "scored_at" ] }, "examples": { "successful_risk_assessment": { "summary": "Successful Risk Assessment", "description": "Retrieve risk details for routing ID 12345.", "value": { "routing_id": "12345", "agent_did": "did:human:acme", "task_description": "Invoice processing for client XYZ", "risk_score": 7.5, "scored_at": "2023-10-05T14:48:00.000Z" } } } } } }, "400": { "description": "Request is malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_routing_id": { "summary": "Missing Routing ID", "description": "The request failed because the routing ID parameter was not provided.", "value": { "type": "https://humanprotocol.org/errors/required-field-missing", "title": "Missing Required Parameter", "status": 400, "detail": "The routing ID is required to complete this request.", "errors": [ { "field": "routingId", "code": "REQUIRED_FIELD_MISSING", "message": "routingId is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "The request failed because no authentication credentials were provided.", "value": { "type": "https://humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please include valid human passport credentials." } } } } } }, "404": { "description": "The specified routing event could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "routing_event_not_found": { "summary": "Routing Event Not Found", "description": "The request failed because the routing ID does not exist.", "value": { "type": "https://humanprotocol.org/errors/routing-event-not-found", "title": "Routing Event Not Found", "status": 404, "detail": "No routing event found for ID 67890." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An error occurred processing the request.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request. Please try again later." } } } } } } } } }, "/v1/humanos/policy/structured": { "get": { "summary": "Retrieve structured policy summaries", "description": "Discover the governance of your organization through HUMAN's curated policy summaries. This endpoint allows organizations to gain insights into their policy landscape by fetching structured overviews, helping you navigate and enhance your task orchestration with AI safety.", "operationId": "getStructuredPolicies", "tags": [ "Policy Management", "HumanOS" ], "x-code-hash": "eb62a6e9bcfe7b5f", "x-generated-at": "2026-04-11T02:39:26.797Z", "responses": { "200": { "description": "Structured policy summaries retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "policy_id": { "type": "string", "description": "Unique identifier for the policy." }, "name": { "type": "string", "description": "Descriptive name of the policy." }, "category_summary": { "type": "array", "items": { "type": "string" }, "description": "List of categories the policy encompasses." }, "rule_count": { "type": "integer", "description": "Number of rules defined within the policy." }, "active": { "type": "boolean", "description": "Indicates if the policy is currently active." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the policy was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the latest policy update." } }, "required": [ "policy_id", "name", "category_summary", "rule_count", "active", "created_at", "updated_at" ] } }, "limit": { "type": "integer", "description": "Maximum number of policies returned." }, "cursorField": { "type": "string", "description": "Field used for pagination." }, "hasMore": { "type": "boolean", "description": "Indicates if more policies are available beyond the current limit." } }, "required": [ "data", "limit", "cursorField", "hasMore" ] }, "examples": { "policy_overview_for_acme_corp": { "summary": "Policy Overview for Acme Corp", "description": "Acme Corp retrieves policy summaries to ensure compliance and operational efficiency.", "value": { "data": [ { "policy_id": "abc123", "name": "Data Handling Policy", "category_summary": [ "Data Privacy", "Security" ], "rule_count": 5, "active": true, "created_at": "2023-01-12T08:00:00Z", "updated_at": "2023-09-15T12:00:00Z" } ], "limit": 20, "cursorField": "policy_id", "hasMore": false } } } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid Limit Parameter", "description": "Limit query parameter is not a valid number.", "value": { "type": "https://example.com/probs/invalid-parameter", "title": "Invalid Query Parameter", "status": 400, "detail": "The 'limit' parameter must be a number between 1 and 100." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "The organization DID must be provided for authentication.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Ensure your request includes a valid organization DID." } } } } } }, "403": { "description": "Access forbidden to the requested resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "User lacks permission to access the resource.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access the policies for this organization." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "policy_not_found": { "summary": "Policy Not Found", "description": "No policies found for the given organization DID.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "No policies were found for the specified organization DID." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_error": { "summary": "Internal Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try your request again later." } } } } } } } }, "post": { "summary": "Create a structured HumanOS policy", "description": "Define structured policies within the HumanOS to govern task execution with precision. This endpoint empowers organizations to craft policies that ensure AI safety and task orchestration fidelity. By harnessing the protocol, you create robust governance frameworks that align with organizational objectives.", "operationId": "createHumanosStructuredPolicy", "tags": [ "HumanOS", "PolicyManagement" ], "x-code-hash": "63a49f4494e0aeaf", "x-generated-at": "2026-04-11T02:39:41.129Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A unique name for the policy." }, "policy": { "type": "object", "description": "The policy document detailing rules and parameters.", "additionalProperties": true }, "team_id": { "type": "string", "description": "Identifier for the team the policy applies to." }, "agent_did": { "type": "string", "description": "Decentralized Identifier for the agent responsible for the policy." }, "active": { "type": "boolean", "description": "Flag indicating if the policy is active." } }, "required": [ "name", "policy" ] }, "examples": { "create_new_policy": { "summary": "Create New Policy", "description": "This example demonstrates creating a new policy for invoice processing.", "value": { "name": "Invoice Processing Policy", "policy": { "rules": [ { "action": "approve", "condition": "total < 1000" }, { "action": "review", "condition": "total >= 1000" } ] }, "team_id": "team-1234", "agent_did": "did:human:agent-5678", "active": true } } } } } }, "responses": { "201": { "description": "Policy created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "type": "string", "description": "The unique identifier of the created policy." }, "name": { "type": "string", "description": "The name of the created policy." }, "version": { "type": "integer", "description": "The version number of the policy." }, "active": { "type": "boolean", "description": "The active status of the policy." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp of policy creation." } } }, "examples": { "default": { "summary": "Example", "value": { "policy_id": "policy-12345", "name": "Invoice Processing Policy", "version": 1, "active": true, "created_at": "2023-10-30T14:12:00Z" } } } } } }, "400": { "description": "Bad request due to invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/validation-error", "title": "Invalid JSON input", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication error, delegation required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/authentication-error", "title": "Delegation required", "status": 401, "detail": "Organization DID is required. Ensure you're authenticated and have the necessary permissions." } } } } } }, "403": { "description": "Permission denied, access to resource forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/permission-denied", "title": "Access denied", "status": 403, "detail": "You do not have permission to create policies for this organization. Check your role or contact your administrator." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/humanos/policy/structured/:id": { "delete": { "summary": "Delete a structured policy by ID", "description": "In the intricate dance of task automation, sometimes a policy outlives its usefulness. This endpoint allows organizations to gracefully retire a structured policy, ensuring that their orchestration remains agile and adaptive. By removing outdated policies, organizations can streamline their operations and maintain a clean, efficient task routing system.", "operationId": "deleteStructuredPolicy", "tags": [ "HumanOS", "Policy Management" ], "x-code-hash": "4a5dc5c417eed9b3", "x-generated-at": "2026-04-11T02:39:50.665Z", "responses": { "204": { "description": "Successfully deleted the policy. No content is returned as the confirmation is implicit in the absence of errors.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request could not be understood due to malformed syntax. Ensure the policy ID is a valid UUID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invaliduuid": { "summary": "InvalidUUID", "description": "An example where the policy ID is not a valid UUID.", "value": { "type": "https://humanos.api/errors/invalid-uuid", "title": "Invalid UUID", "status": 400, "detail": "The provided policy ID '12345' is not a valid UUID. Please provide a valid UUID." } } } } } }, "401": { "description": "Authentication is required to perform this action. Ensure that the request includes proper delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegationrequired": { "summary": "DelegationRequired", "description": "An example where the request is missing delegation.", "value": { "type": "https://humanos.api/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please authenticate and try again." } } } } } }, "404": { "description": "The specified policy could not be found. Verify the policy ID and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "policynotfound": { "summary": "PolicyNotFound", "description": "An example where the policy ID does not exist.", "value": { "type": "https://humanos.api/errors/not-found", "title": "Policy Not Found", "status": 404, "detail": "Policy with ID 'f47ac10b-58cc-4372-a567-0e02b2c3d479' not found. Please check the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server side. Retry the request or contact support if the issue persists.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internalservererror": { "summary": "InternalServerError", "description": "An example of a server error.", "value": { "type": "https://humanos.api/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected server error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Fetch structured policy details by ID", "description": "Retrieve intricate policy details tailored to your organization's dynamics. This endpoint empowers organizations to understand and manage their task routing policies effectively, ensuring alignment with their AI safety protocols.", "operationId": "getStructuredPolicyById", "tags": [ "HumanOS", "Policy Management" ], "x-code-hash": "1a2bc4293178447d", "x-generated-at": "2026-04-12T15:43:24.010Z", "responses": { "200": { "description": "Successfully retrieved the policy details", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "policy": { "type": "object" }, "active": { "type": "boolean" }, "version": { "type": "integer" }, "team_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_did": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "policy_for_invoice_processing": { "summary": "Policy for invoice processing", "description": "Represents a policy for handling invoices within the 'acme' organization.", "value": { "policy_id": "a123b456-c789-0123-d456-789e012f3456", "name": "Invoice Processing", "policy": { "rules": [ { "action": "approve", "threshold": 1000 } ] }, "active": true, "version": 2, "team_id": "f7890123-4567-89ab-cdef-0123456789ab", "agent_did": "did:human:agents:acme-processor", "created_at": "2023-01-15T08:00:00Z", "updated_at": "2023-09-20T14:30:00Z" } } } } } }, "400": { "description": "Bad Request due to malformed ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_uuid_format": { "summary": "Invalid UUID format", "description": "Occurs when the provided policy ID is not a valid UUID.", "value": { "type": "https://docs.human.com/errors/invalid-id", "title": "Invalid Policy ID", "status": 400, "detail": "The policy ID '1234' is not a valid UUID.", "errors": [ "ID must be a valid UUID format." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "description": "Occurs when the request lacks proper delegation credentials.", "value": { "type": "https://docs.human.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access this resource." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "Occurs when the user does not have permission to view the policy.", "value": { "type": "https://docs.human.com/errors/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have the necessary permissions to view this policy." } } } } } }, "404": { "description": "Policy not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "non-existent_policy": { "summary": "Non-existent policy", "description": "Occurs when the specified policy ID does not exist.", "value": { "type": "https://docs.human.com/errors/policy-not-found", "title": "Policy Not Found", "status": 404, "detail": "No policy found with ID 'a123b456-c789-0123-d456-789e012f3456'." } } } } } }, "500": { "description": "Internal server error due to unexpected issues", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_connection_failure": { "summary": "Database connection failure", "description": "Occurs when there's an issue connecting to the policy database.", "value": { "type": "https://docs.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving the policy." } } } } } } } }, "put": { "summary": "Update structured HumanOS policy", "description": "This endpoint empowers organizations to update their structured policies within the HumanOS task routing system. By maintaining accurate and current policy definitions, organizations can ensure AI safety and compliance. This operation is crucial for organizations like 'acme' who need to adapt their policy frameworks promptly.", "operationId": "updateStructuredPolicy", "tags": [ "Policy Management", "HumanOS" ], "x-code-hash": "58b82f8d6748ee07", "x-generated-at": "2026-04-12T15:43:35.232Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A descriptive name for the policy." }, "policy": { "type": "object", "description": "The new policy document to validate and apply.", "additionalProperties": true }, "active": { "type": "boolean", "description": "Indicates whether the policy should be active." } } }, "examples": { "update_policy_example": { "summary": "Update Policy Example", "description": "An example of updating a policy with a new name and active status.", "value": { "name": "Updated Invoice Processing Policy", "policy": { "rules": [ { "action": "allow", "resource": "invoices", "condition": "if amount < 10000" } ] }, "active": true } } } } } }, "responses": { "200": { "description": "The policy was successfully updated with the new details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "type": "string", "description": "The unique identifier of the updated policy." }, "name": { "type": "string", "description": "The name of the updated policy." }, "active": { "type": "boolean", "description": "The active status of the updated policy." }, "version": { "type": "integer", "description": "The version number of the updated policy." }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the policy was last updated." } } }, "examples": { "default": { "summary": "Example", "value": { "policy_id": "123e4567-e89b-12d3-a456-426614174000", "name": "Updated Invoice Processing Policy", "active": true, "version": 2, "updated_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "The request body is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this policy." } } } } } }, "404": { "description": "The specified policy was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The policy with the specified ID does not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/policy/structured/:id/validate": { "post": { "summary": "Validate human policy structure", "description": "In the ever-evolving landscape of AI collaborations, ensuring that policies are structured correctly is paramount. This endpoint invites organizations to validate their policy documents, ensuring they meet the cryptographic standards required for secure, efficient AI orchestration. By confirming the validity of these policies, organizations can trust in a seamless integration with HUMAN's distributed ledger.", "operationId": "validatePolicyStructure", "tags": [ "HumanOS", "Policy" ], "x-code-hash": "2b14903bc20e7fec", "x-generated-at": "2026-04-11T02:40:02.823Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "description": "The policy document to validate.", "properties": { "id": { "type": "string", "description": "Unique policy identifier" }, "rules": { "type": "array", "items": { "type": "string" }, "description": "Policy rules defining capabilities and constraints" } }, "required": [ "id", "rules" ] } }, "required": [ "policy" ] }, "examples": { "acme_corp_policy_validation": { "summary": "Acme Corp Policy Validation", "description": "A sample policy document from Acme Corp undergoing validation.", "value": { "policy": { "id": "policy-1234", "rules": [ "capability://read", "capability://write" ] } } } } } } }, "responses": { "200": { "description": "The policy document has been successfully validated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" } }, "required": [ "valid" ] }, "examples": { "valid_policy_response": { "summary": "Valid Policy Response", "value": { "valid": true } } } } } }, "400": { "description": "The policy document is malformed or incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_policy_document": { "summary": "Malformed Policy Document", "value": { "type": "https://humanprotocol.org/errors/invalid-policy", "title": "Invalid Policy Document", "status": 400, "detail": "The provided policy document does not conform to the expected schema.", "errors": [ "Missing 'rules' field" ] } } } } } }, "401": { "description": "Authentication is required to validate a policy.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_did": { "summary": "Missing Organization DID", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized Access", "status": 401, "detail": "A valid organization DID is required for policy validation." } } } } } }, "403": { "description": "The organization does not have permission to validate this policy.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_policy_validation_attempt": { "summary": "Unauthorized Policy Validation Attempt", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to validate policies for this organization." } } } } } }, "404": { "description": "The specified policy ID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "nonexistent_policy": { "summary": "Nonexistent Policy", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Policy Not Found", "status": 404, "detail": "The policy with ID 'policy-1234' could not be found." } } } } } }, "500": { "description": "An unexpected error occurred during policy validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_during_validation": { "summary": "Server Error During Validation", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing the policy validation request." } } } } } } } } }, "/v1/humanos/batch-route": { "post": { "summary": "Route batch tasks through HumanOS", "description": "The batch-route endpoint empowers organizations to efficiently direct multiple tasks through HumanOS, leveraging AI-driven orchestration for safe and effective task execution. This endpoint underlines the platform's commitment to scalability and precision, optimizing the management of up to 50 tasks in a single request.", "operationId": "postBatchRoute", "tags": [ "TaskRouting", "HumanOS" ], "x-code-hash": "b13a08dc894c2732", "x-generated-at": "2026-04-11T02:46:42.314Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string" }, "type": { "type": "string" }, "ai_assessment": { "type": "object", "properties": { "confidence": { "type": "number" } } }, "confidence": { "type": "number" } }, "required": [ "task_id", "type" ] } } }, "required": [ "tasks" ] }, "examples": { "batch_task_submission": { "summary": "Batch Task Submission", "description": "Submitting a batch of tasks for AI routing within 'acme' organization.", "value": { "tasks": [ { "task_id": "task_123", "type": "invoice_processing", "confidence": 0.95 }, { "task_id": "task_124", "type": "data_entry", "confidence": 0.8 } ] } } } } } }, "responses": { "200": { "description": "Tasks successfully routed through HumanOS.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string" }, "result": { "type": "object" } } } }, "batch_size": { "type": "integer" } } }, "examples": { "successful_batch_routing": { "summary": "Successful Batch Routing", "description": "All tasks in the batch are successfully processed.", "value": { "results": [ { "index": 0, "status": "success", "result": { "task_id": "task_123", "processed": true } }, { "index": 1, "status": "success", "result": { "task_id": "task_124", "processed": true } } ], "batch_size": 2 } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_tasks_array": { "summary": "Missing Tasks Array", "description": "The request body is missing the required 'tasks' array.", "value": { "type": "https://docs.humanos.api/errors/validation", "title": "Bad Request", "status": 400, "detail": "A required field is missing or malformed.", "errors": [ { "field": "tasks", "code": "REQUIRED_FIELD_MISSING", "message": "tasks array is required", "expected": "array", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "The request lacks necessary delegation credentials.", "value": { "type": "https://docs.humanos.api/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have permission to route tasks.", "value": { "type": "https://docs.humanos.api/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "The specified endpoint or resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "endpoint_not_found": { "summary": "Endpoint Not Found", "description": "The requested endpoint does not exist.", "value": { "type": "https://docs.humanos.api/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested endpoint does not exist. Please check the URL." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://docs.humanos.api/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/boundaries": { "get": { "summary": "Retrieve Payment Boundaries for Actions", "description": "Dive into the realm of HumanOS task routing by exploring payment boundaries for specific actions. This endpoint helps organizations understand financial limits tied to their actions, ensuring AI interactions remain within budgetary constraints.", "operationId": "getHumanosBoundaries", "tags": [ "HumanOS", "Payments" ], "x-code-hash": "18cf76787fa2ec10", "x-generated-at": "2026-04-11T02:46:54.194Z", "responses": { "200": { "description": "Successfully retrieved payment boundaries for the specified action and amount.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action for which boundaries are retrieved." }, "limit": { "type": "number", "description": "The financial limit associated with the action." }, "currency": { "type": "string", "description": "Currency in which the limit is denominated." } }, "required": [ "action", "limit", "currency" ] }, "examples": { "retrieve_payment_boundary_for_'process_invoice'": { "summary": "Retrieve Payment Boundary for 'process_invoice'", "description": "An example where the 'acme' organization checks the payment boundary for processing invoices.", "value": { "action": "process_invoice", "limit": 1000, "currency": "USD" } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_amount_parameter": { "summary": "Invalid Amount Parameter", "description": "Example where the amount parameter is not a number.", "value": { "type": "https://api.human/probs/invalid-parameter", "title": "Invalid Parameter", "status": 400, "detail": "The 'amount' parameter must be a valid number." } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "Example where no delegation header is present.", "value": { "type": "https://api.human/probs/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation required. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Example where the user does not have permission to access payment boundaries.", "value": { "type": "https://api.human/probs/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have the required permissions to view this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Example where the specified action does not exist.", "value": { "type": "https://api.human/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The action 'nonexistent_action' does not exist." } } } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Example where an unexpected error occurs.", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/audit": { "get": { "summary": "Retrieve audit events from HumanOS", "description": "Unveil the intricate dance of actions within your organization by exploring the audit trail maintained by HumanOS. This endpoint allows you to sift through the past, examining the orchestration of tasks and decisions made by both humans and AI. Whether you're tracking down anomalies or ensuring compliance, these records hold the key.", "operationId": "getHumanosAuditEvents", "tags": [ "HumanOS", "Audit" ], "x-code-hash": "22b503200c2d79dc", "x-generated-at": "2026-04-11T02:47:07.642Z", "responses": { "200": { "description": "Successfully retrieved audit events", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "event_type": { "type": "string" }, "task_type": { "type": [ "string", "null" ] }, "routing_id": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } }, "required": [ "id", "event_type", "created_at", "payload" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total_count": { "type": [ "number", "null" ] } }, "required": [ "data", "has_more" ] }, "examples": { "typical_audit_retrieval": { "summary": "Typical audit retrieval", "description": "Retrieve the latest audit events for monitoring task execution", "value": { "data": [ { "id": 10001, "event_type": "task_completed", "task_type": "invoice_processing", "routing_id": "route_12345", "confidence": 0.95, "created_at": "2023-10-10T14:48:00.000Z", "payload": { "invoice_id": "INV-2023101", "status": "approved" } } ], "has_more": true, "next_cursor": "eyJfaHVtYW5vc19hdWRpdF9zb3J0IjoiY3JlYXRlZF9hdCIsImlkIjoxMDAwMX0=" } } } } } }, "400": { "description": "Request has invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_sort_parameter": { "summary": "Invalid sort parameter", "description": "Example of an error when the sort parameter is incorrect", "value": { "type": "https://docs.humanos.com/errors/invalid-request", "title": "Invalid Request Parameter", "status": 400, "detail": "The sort parameter is invalid.", "errors": [ { "field": "sort", "code": "INVALID_SORT_FIELD", "message": "Unknown audit sort field: unknown_field", "expected": "comma fields: created_at, id, event_type, confidence; prefix - for DESC", "received": "unknown_field" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing authentication", "description": "Error when no valid authentication is provided", "value": { "type": "https://docs.humanos.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Forbidden: Missing required scopes", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_required_scopes": { "summary": "Missing required scopes", "description": "Error when delegation does not have required scopes", "value": { "type": "https://docs.humanos.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Delegation is missing required scopes: humanos:read and audit:read." } } } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "Example of a not found error", "value": { "type": "https://docs.humanos.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "An error example when something goes wrong on the server", "value": { "type": "https://docs.humanos.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/routing": { "post": { "summary": "Route tasks with AI safety protocols", "description": "The POST /v1/humanos/routing endpoint orchestrates task routing within the HumanOS ecosystem, ensuring AI safety and accountability. By leveraging cryptographic identities and capability graphs, it guarantees secure and efficient human-AI collaboration. This endpoint is essential for organizations seeking to balance human intuition with AI precision.", "operationId": "postTaskRouting", "tags": [ "TaskRouting", "AI Safety" ], "x-code-hash": "1b456718ebabdfd4", "x-generated-at": "2026-04-11T02:47:16.123Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "description": "Unique identifier for the task." }, "task_type": { "type": "string", "description": "Type of task to be routed, defining required skills." } }, "required": [ "task_id", "task_type" ] }, "examples": { "routing_a_data_processing_task": { "summary": "Routing a Data Processing Task", "description": "Routes a data processing task for the 'acme' organization.", "value": { "task_id": "12345", "task_type": "data_processing" } } } } } }, "responses": { "200": { "description": "Task successfully routed with AI safety protocols.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "routed" }, "task_id": { "type": "string", "description": "The ID of the routed task." }, "orgDid": { "type": "string", "description": "Decentralized identifier for the organization." } } }, "examples": { "successful_routing_response": { "summary": "Successful Routing Response", "value": { "status": "routed", "task_id": "12345", "orgDid": "did:example:acme" } } } } } }, "400": { "description": "Invalid input or missing fields in the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_fields_error": { "summary": "Missing Fields Error", "value": { "type": "https://example.com/probs/invalid-input", "title": "Invalid Request", "status": 400, "detail": "task_id and task_type are required", "errors": [ { "field": "task_id", "code": "REQUIRED_FIELD_MISSING", "message": "task_id is required" } ] } } } } } }, "401": { "description": "Authentication failed, delegation required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication Error", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Error", "status": 401, "detail": "Delegation required" } } } } } } } } }, "/v1/humanos/routing/history": { "get": { "summary": "Retrieve task routing history for organization", "description": "Explore the journey of tasks as they dance through the intricate choreography of HumanOS. This endpoint unveils the past decisions and confidence levels that guided tasks, providing insights into the orchestration process and the AI's role in task routing.", "operationId": "getRoutingHistory", "tags": [ "TaskRouting", "History" ], "x-code-hash": "af33b6afa4cae6b2", "x-generated-at": "2026-04-11T02:47:29.729Z", "responses": { "200": { "description": "Successfully retrieved the task routing history with pagination details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "routing_id": { "type": "string" }, "task_id": { "type": "string" }, "task_type": { "type": "string" }, "status": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "routing_decision": { "type": [ "string", "null" ] }, "pipeline_success": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } } }, "examples": { "acme_corp_task_routing_history": { "summary": "Acme Corp Task Routing History", "description": "A snapshot of Acme Corp's task routing history showing the status and decisions made for recent tasks.", "value": { "data": [ { "routing_id": "route-123", "task_id": "task-456", "task_type": "invoice-processing", "status": "completed", "confidence": 0.92, "routing_decision": "approved", "pipeline_success": true, "created_at": "2023-10-05T14:48:00.000Z" }, { "routing_id": "route-124", "task_id": "task-457", "task_type": "data-entry", "status": "pending", "confidence": 0.85, "routing_decision": null, "pipeline_success": null, "created_at": "2023-10-04T13:30:00.000Z" } ], "limit": 2, "cursorFields": [ "created_at", "routing_id" ], "hasMore": true } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_example": { "summary": "Invalid Cursor Example", "description": "Demonstrates an error due to an invalid cursor parameter.", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The provided cursor is invalid. Ensure it contains both 'created_at' and 'routing_id'.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid cursor", "expected": "{ created_at, routing_id }", "received": "opaque" } ] } } } } } }, "401": { "description": "Authentication required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_example": { "summary": "Missing Authentication Example", "description": "Illustrates an authentication error when delegation is not provided.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access routing history. Please authenticate with valid credentials." } } } } } }, "403": { "description": "Access to the resource is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Shows a forbidden access error when the user lacks permissions.", "value": { "type": "https://example.com/probs/forbidden-access", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access the routing history for this organization." } } } } } }, "500": { "description": "Internal server error encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "Illustrates a server error during the request.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request. Please try again later." } } } } } } } } }, "/v1/humanos/routing/:routingId": { "get": { "summary": "Retrieve routing decision details", "description": "Discover the intricate journey of a task within HUMAN's AI orchestration. This endpoint illuminates the path a task takes, revealing the decision-making intricacies and outcomes. Tracking the provenance of AI-driven processes is crucial for transparency and trust.", "operationId": "getRoutingById", "tags": [ "HumanOS", "Routing" ], "x-code-hash": "535e94807e7d0610", "x-generated-at": "2026-04-11T02:47:42.432Z", "responses": { "200": { "description": "The routing details were successfully retrieved, showcasing the decision path and outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "routing_id": { "type": "string" }, "task_id": { "type": "string" }, "task_type": { "type": "string" }, "status": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "fourth_law_triggered": { "type": "boolean" }, "routing_decision": { "type": "string" }, "pipeline_success": { "type": "boolean" }, "request_payload": { "type": "object" }, "response_payload": { "type": "object" }, "pipeline_stages": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "successful_routing_retrieval": { "summary": "Successful Routing Retrieval", "description": "Shows a successful retrieval of routing information for a task", "value": { "routing_id": "routing-123", "task_id": "task-456", "task_type": "invoice-processing", "status": "completed", "confidence": 0.95, "fourth_law_triggered": false, "routing_decision": "approved", "pipeline_success": true, "request_payload": { "invoice_id": "inv-789" }, "response_payload": { "status": "processed", "amount": 1500 }, "pipeline_stages": [ { "stage": "validation", "status": "passed" }, { "stage": "approval", "status": "passed" } ], "created_at": "2023-10-04T14:48:00Z" } } } } } }, "400": { "description": "Invalid request parameters, such as malformed routingId.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_routing_id": { "summary": "Malformed Routing ID", "description": "An invalid routingId format was provided", "value": { "type": "https://example.com/probs/invalid-parameter", "title": "Invalid Parameter", "status": 400, "detail": "The routingId provided is not in a valid format.", "errors": [ "routingId must be a UUID." ] } } } } } }, "401": { "description": "Authentication required to access routing details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "No valid Passport or DID provided.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Passport or DID must be provided for authentication." } } } } } }, "403": { "description": "Insufficient permissions to access the routing record.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user does not have permission to view this routing record.", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access this routing record." } } } } } }, "404": { "description": "The specified routing record was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "routing_record_not_found": { "summary": "Routing Record Not Found", "description": "No routing record exists for the provided ID.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Routing record with ID routing-123 was not found." } } } } } }, "500": { "description": "An unexpected server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server error prevented retrieving routing information.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while retrieving the routing record." } } } } } } } } }, "/v1/humanos/escalation/rules": { "post": { "summary": "Create a new escalation rule", "description": "In the HUMAN realm, routing tasks safely and efficiently often demands escalation. This endpoint empowers organizations to define rules that trigger when conditions warrant human intervention, ensuring seamless task management and AI oversight.", "operationId": "createEscalationRule", "tags": [ "HumanOS", "Escalation" ], "x-code-hash": "5ad9aa233dff2ff5", "x-generated-at": "2026-04-11T02:47:55.015Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A unique name for the escalation rule." }, "conditions": { "type": "object", "description": "Conditions under which the escalation rule is triggered." } }, "required": [ "name" ] }, "examples": { "basic_escalation_rule": { "summary": "Basic Escalation Rule", "description": "An example rule that triggers when default conditions are met.", "value": { "name": "Urgent Task Escalation", "conditions": { "match": "default" } } } } } } }, "responses": { "201": { "description": "The escalation rule was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule_id": { "type": "string", "description": "Unique identifier for the created rule." }, "name": { "type": "string", "description": "The name of the created rule." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of rule creation." } } }, "examples": { "escalation_rule_created": { "summary": "Escalation Rule Created", "description": "A successful response indicating a new rule was created.", "value": { "rule_id": "hos_rule_123456", "name": "Urgent Task Escalation", "created_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "The request was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "You do not have permission to create escalation rules.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/humanos/escalation/manual": { "post": { "summary": "Manually escalate tasks for human oversight", "description": "In the dynamic realm of HUMAN's orchestration, this endpoint enables organizations to manually escalate tasks requiring human intervention. It ensures that critical tasks are handled with the attention they demand, combining the power of AI with the wisdom of human judgment.", "operationId": "postManualEscalation", "tags": [ "HumanOS", "Escalation" ], "x-code-hash": "ac31b0fd0d622615", "x-generated-at": "2026-04-11T02:48:06.075Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "The reason for escalating this task, providing context for human intervention." }, "task_type": { "type": "string", "description": "The type of task being escalated, helping route to the appropriate human agent." }, "routing_id": { "type": "string", "description": "An identifier for the routing of the task, ensuring precise tracking." }, "context": { "type": "object", "description": "Additional context for the escalation, allowing for a richer understanding of the situation.", "additionalProperties": true } }, "required": [ "reason" ] }, "examples": { "invoice_escalation": { "summary": "Invoice escalation", "description": "Escalating an invoice processing task due to complex discrepancy.", "value": { "reason": "Discrepancy in invoice data requires human review.", "task_type": "invoice_processing", "routing_id": "task-12345", "context": { "invoice_id": "INV-6789", "amount": 10000, "currency": "USD" } } } } } } }, "responses": { "200": { "description": "The task escalation was successfully recorded and queued for human review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "recorded" ], "description": "Indicates the result of the escalation." }, "escalated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the escalation was recorded." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request body was invalid JSON or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.org/probs/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication failed due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.org/probs/auth-required", "title": "Delegation Required", "status": 401, "detail": "Delegation required. Please provide a valid delegation token." } } } } } }, "403": { "description": "Permission denied for the requested operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.org/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to escalate tasks manually." } } } } } }, "404": { "description": "The task or resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.org/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified routing_id does not exist in the system." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.org/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/safety/check": { "post": { "summary": "Evaluate HumanOS task safety checks", "description": "This endpoint assesses whether a specific action within a given domain complies with the organization's HumanOS safety policies. By evaluating these actions, HumanOS ensures that tasks are performed within the ethical and procedural boundaries set by the organization, protecting both human and AI participants.", "operationId": "postSafetyCheck", "tags": [ "HumanOS", "Safety" ], "x-code-hash": "56b2ae3d5f529982", "x-generated-at": "2026-04-11T02:48:19.141Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain of the action, e.g., 'finance' or 'general'", "default": "general" }, "action": { "type": "string", "description": "Specific action to be evaluated, e.g., 'processInvoice'", "default": "unknown" } }, "required": [ "domain", "action" ] }, "examples": { "check_finance_action": { "summary": "Check Finance Action", "description": "Check safety for processing an invoice in the finance domain.", "value": { "domain": "finance", "action": "processInvoice" } } } } } }, "responses": { "200": { "description": "Successful evaluation of the action's safety.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean", "description": "Indicates if the action is permitted." }, "domain": { "type": "string", "description": "The domain in which the action was evaluated." }, "action": { "type": "string", "description": "The action that was evaluated." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Reasons why the action is allowed or denied." }, "reviewed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the review was conducted." } } }, "examples": { "default": { "summary": "Example", "value": { "allowed": true, "domain": "finance", "action": "processInvoice", "reasons": [ "Policy compliance verified" ], "reviewed_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Invalid request due to malformed JSON.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication required for the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Permission denied for the requested action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/humanos/safety/config": { "get": { "summary": "Retrieve HumanOS Safety Configuration", "description": "Uncover the safety protocols that guide HumanOS in safeguarding your organization’s tasks. This endpoint provides an organization-specific configuration that aligns AI task routing with safety policies, ensuring secure and efficient operations.", "operationId": "getHumanosSafetyConfig", "tags": [ "HumanOS", "Safety" ], "x-code-hash": "624cb27c33c2b715", "x-generated-at": "2026-04-11T02:48:29.254Z", "responses": { "200": { "description": "Successfully retrieved the organization-specific safety configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": true }, "org_scoped": { "type": "boolean", "description": "Indicates if the configuration is scoped to the organization." } }, "required": [ "config", "org_scoped" ] }, "examples": { "acme_safety_configuration": { "summary": "Acme Safety Configuration", "description": "Acme Corporation's safety configuration for HumanOS task routing.", "value": { "config": { "domain": "general", "policies": { "ai_task_safety": { "enabled": true, "threshold": 0.8 } } }, "org_scoped": true } } } } } }, "400": { "description": "Invalid request due to malformed query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_domain_parameter": { "summary": "Invalid Domain Parameter", "description": "An invalid domain was provided which does not exist.", "value": { "type": "https://humanos.api/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The specified domain parameter is invalid. Ensure the domain is correct and try again." } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request did not include necessary authentication details.", "value": { "type": "https://humanos.api/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please authenticate with a valid Passport to access this endpoint." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The authenticated user does not have the necessary permissions to access this resource.", "value": { "type": "https://humanos.api/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permissions to access this organization's safety configuration. Please contact your administrator." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "configuration_not_found": { "summary": "Configuration Not Found", "description": "The specified configuration for the requested domain does not exist.", "value": { "type": "https://humanos.api/errors/not-found", "title": "Not Found", "status": 404, "detail": "The safety configuration for the given domain was not found. Verify the domain and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "The server encountered an unexpected condition.", "value": { "type": "https://humanos.api/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/humanos/provenance/:routingId": { "get": { "summary": "Retrieve task provenance details", "description": "Explore the intricate journey of a task within the HUMAN ecosystem through its provenance data. This endpoint weaves a narrative of how tasks evolve, ensuring transparency and accountability in AI-human collaboration.", "operationId": "getHumanosProvenanceByRoutingId", "tags": [ "Provenance", "HumanOS" ], "x-code-hash": "521f2d57e212a941", "x-generated-at": "2026-04-11T02:48:42.378Z", "responses": { "200": { "description": "Successfully retrieved the provenance details of a task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "routing_id": { "type": "string", "description": "The unique identifier for the task's routing." }, "task_id": { "type": "string", "description": "The scoped identifier for the task." }, "routing_summary": { "type": "object", "description": "Summary of the task's routing process.", "additionalProperties": true }, "pipeline_stages": { "type": "object", "description": "Details of each stage in the task's pipeline.", "additionalProperties": true }, "provenance_graph": { "type": "object", "nullable": true, "properties": { "graph_id": { "type": "string", "description": "Identifier for the provenance graph." }, "graph_json": { "type": "object", "description": "The JSON representation of the provenance graph.", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provenance graph was created." } } } } }, "examples": { "provenance_retrieval_for_task_a1": { "summary": "Provenance retrieval for task A1", "description": "Fetching the provenance details for task A1 belonging to org acme.", "value": { "routing_id": "1234-5678-9012", "task_id": "acme:task-a1", "routing_summary": { "status": "completed", "duration": "5 minutes" }, "pipeline_stages": { "stage1": "Data preprocessing", "stage2": "Model training" }, "provenance_graph": { "graph_id": "graph-001", "graph_json": { "nodes": [ { "id": "n1", "label": "Start" }, { "id": "n2", "label": "Process" }, { "id": "n3", "label": "End" } ], "edges": [ { "from": "n1", "to": "n2" }, { "from": "n2", "to": "n3" } ] }, "created_at": "2023-10-01T12:00:00Z" } } } } } } }, "400": { "description": "The request was malformed, such as a missing or invalid routing ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_routing_id": { "summary": "Invalid routing ID", "description": "An invalid routing ID format was provided.", "value": { "type": "https://humanos.api/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The routing ID format is invalid. Ensure it conforms to the GUID standard." } } } } } }, "401": { "description": "Authentication failed due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "description": "Authorization failed because delegation was not provided.", "value": { "type": "https://humanos.api/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please authenticate with valid credentials." } } } } } }, "403": { "description": "Access is forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "description": "The user does not have permission to access this provenance data.", "value": { "type": "https://humanos.api/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Contact your administrator." } } } } } }, "404": { "description": "The specified routing record was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "routing_record_not_found": { "summary": "Routing record not found", "description": "No routing record exists for the provided ID.", "value": { "type": "https://humanos.api/errors/not-found", "title": "Not Found", "status": 404, "detail": "No routing record found for ID 1234-5678-9012." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "A server error occurred due to an unexpected condition.", "value": { "type": "https://humanos.api/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/agents/register": { "post": { "summary": "Register a new agent under an organization", "description": "Embark on a journey with HUMAN by registering a new agent. This process not only formalizes an agent's identity but also seamlessly integrates them into the HUMAN ecosystem, ensuring their skills are tracked and tasks are routed efficiently.", "operationId": "registerAgent", "tags": [ "Agents", "Registration" ], "x-code-hash": "ce155ab8fcd7a132", "x-generated-at": "2026-04-11T02:48:54.069Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "A unique identifier for the agent." }, "agent_external_id": { "type": "string", "description": "An external identifier for the agent, used if agent_id is not provided." }, "metadata": { "type": "object", "description": "Additional metadata for the agent registration.", "additionalProperties": true } }, "oneOf": [ { "required": [ "agent_id" ] }, { "required": [ "agent_external_id" ] } ] }, "examples": { "registering_an_agent_with_agent_id": { "summary": "Registering an agent with agent_id", "description": "An example showing registration with a specified agent_id.", "value": { "agent_id": "agent_12345", "metadata": { "role": "processor", "department": "finance" } } }, "registering_an_agent_with_agent_external_id": { "summary": "Registering an agent with agent_external_id", "description": "An example showing registration with agent_external_id when agent_id is unavailable.", "value": { "agent_external_id": "external_67890", "metadata": { "role": "analyst", "department": "research" } } } } } } }, "responses": { "201": { "description": "Agent successfully registered, returning registration details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "registration_id": { "type": "string", "description": "The unique registration identifier for the agent." }, "agent_id": { "type": "string", "description": "The identifier of the registered agent." }, "registered_at": { "type": "string", "format": "date-time", "description": "The timestamp when the agent was registered." } } }, "examples": { "successful_registration_response": { "summary": "Successful registration response", "description": "A response example of a successfully registered agent.", "value": { "registration_id": "hos_ag_abcdef123456", "agent_id": "agent_12345", "registered_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Bad Request due to invalid JSON or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_json_error": { "summary": "Invalid JSON error", "description": "The request body was not valid JSON.", "value": { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } }, "missing_required_field_error": { "summary": "Missing required field error", "description": "Either agent_id or agent_external_id must be provided.", "value": { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "agent_id is required", "errors": [ { "field": "agent_id", "code": "REQUIRED_FIELD_MISSING", "message": "agent_id is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid organization delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_required_error": { "summary": "Delegation required error", "description": "Organization DID is missing, blocking agent registration.", "value": { "type": "about:blank", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Forbidden when the organization lacks permission to register agents.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied_error": { "summary": "Permission denied error", "description": "The organization does not have the required capability to register agents.", "value": { "type": "about:blank", "title": "Forbidden", "status": 403, "detail": "Organization lacks registration capability" } } } } } }, "404": { "description": "Not Found when the specified agent or organization cannot be located.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found_error": { "summary": "Agent not found error", "description": "The specified agent or organization could not be found.", "value": { "type": "about:blank", "title": "Not Found", "status": 404, "detail": "Agent or organization not found" } } } } } }, "500": { "description": "Internal Server Error due to unforeseen circumstances during registration.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "An unexpected error occurred on the server.", "value": { "type": "about:blank", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred during agent registration" } } } } } } } } }, "/v1/humanos/agents/:agentId/performance": { "get": { "summary": "Retrieve agent performance metrics", "description": "Discover how an agent has been performing over time, tracked by audit events. This endpoint helps organizations analyze AI agent activity to ensure efficient task handling and compliance with operational standards.", "operationId": "getAgentPerformance", "tags": [ "HumanOS", "Performance" ], "x-code-hash": "07958fd7bedeab3d", "x-generated-at": "2026-04-11T02:49:03.802Z", "responses": { "200": { "description": "Successfully retrieved the performance metrics for the specified agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "The unique identifier for the agent." }, "period": { "type": "string", "description": "The time period over which the performance is evaluated." }, "events_recorded": { "type": "integer", "description": "The number of events recorded for the agent during the specified period." }, "rollup": { "type": "string", "description": "Indicates the method used to roll up event data." } } }, "examples": { "agent_performance_example": { "summary": "Agent Performance Example", "description": "Performance metrics for agent 'agent123' over the past 30 days.", "value": { "agent_id": "agent123", "period": "30d", "events_recorded": 150, "rollup": "audit_payload_agent_id" } } } } } }, "400": { "description": "Invalid request due to incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_period_format": { "summary": "Invalid Period Format", "value": { "type": "https://docs.humanos.com/errors/invalid-period", "title": "Invalid Period Format", "status": 400, "detail": "The period parameter must be in the format 'Nd', where N is a positive integer. Please correct and retry." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "value": { "type": "https://docs.humanos.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to access performance data. Ensure your request includes valid organization credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://docs.humanos.com/errors/insufficient-permissions", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to view this agent's performance data. Verify your access rights or contact an administrator." } } } } } }, "404": { "description": "The specified agent could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "agent_not_found": { "summary": "Agent Not Found", "value": { "type": "https://docs.humanos.com/errors/agent-not-found", "title": "Agent Not Found", "status": 404, "detail": "The agent with the specified ID does not exist. Please check the agent ID and try again." } } } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://docs.humanos.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/humanos/compliance/report": { "post": { "summary": "Generate compliance activity report", "description": "Dive into the depths of your organization's compliance activities with this endpoint, which meticulously crafts a report detailing event occurrences over a specified time window. This ensures accountability and transparency, painting a clear picture of your operational integrity.", "operationId": "generateComplianceReport", "tags": [ "Compliance", "Reports" ], "x-code-hash": "1884482a16359997", "x-generated-at": "2026-04-11T02:49:15.800Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date-time", "description": "The start date for the report window. Only events from this date forward will be included." }, "end_date": { "type": "string", "format": "date-time", "description": "The end date for the report window. Only events up to this date will be included." }, "report_type": { "type": "string", "enum": [ "summary", "detailed" ], "description": "The type of report to generate. 'summary' provides a high-level overview, while 'detailed' offers in-depth insights." } }, "required": [ "report_type" ] }, "examples": { "summary_report_for_q1": { "summary": "Summary Report for Q1", "description": "Generate a summary report for the first quarter of the year.", "value": { "start_date": "2023-01-01T00:00:00Z", "end_date": "2023-03-31T23:59:59Z", "report_type": "summary" } } } } } }, "responses": { "200": { "description": "A successful report generation with counts of events by type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "report_type": { "type": "string", "description": "The type of report generated." }, "generated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the report was generated." }, "window": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" } }, "description": "The time window for the report." }, "counts_by_event_type": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "A mapping of event types to their occurrence counts." } } }, "examples": { "successful_summary_report": { "summary": "Successful Summary Report", "description": "A successful generation of a summary report showing event counts.", "value": { "report_type": "summary", "generated_at": "2023-10-01T12:00:00Z", "window": { "start_date": "2023-01-01T00:00:00Z", "end_date": "2023-03-31T23:59:59Z" }, "counts_by_event_type": { "login_attempt": 150, "file_access": 75, "data_export": 30 } } } } } } }, "400": { "description": "The request body was malformed or contained invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "The authenticated user does not have permission to generate this report.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/humanos/policy/fraud-review": { "post": { "summary": "Initiate a fraud policy review", "description": "This endpoint empowers organizations to initiate a review of potential fraud activities within their systems. By submitting relevant case references, organizations can ensure a systematic and documented approach to fraud detection and mitigation. This service plays a critical role in enhancing transparency and accountability in financial transactions.", "operationId": "initiateFraudPolicyReview", "tags": [ "Fraud", "Compliance" ], "x-code-hash": "04b1e226203aea65", "x-generated-at": "2026-04-11T02:49:26.792Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "case_ref": { "type": "string", "description": "Unique reference for the fraud case" }, "case_id": { "type": "string", "description": "Alternate identifier for the fraud case" } }, "oneOf": [ { "required": [ "case_ref" ] }, { "required": [ "case_id" ] } ] }, "examples": { "basic_fraud_review": { "summary": "Basic Fraud Review", "description": "Initiating a fraud review using a case reference", "value": { "case_ref": "FRD-20231010-001" } } } } } }, "responses": { "201": { "description": "Fraud review successfully recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "review_id": { "type": "string", "description": "Unique identifier for the recorded review" }, "case_ref": { "type": "string", "description": "Reference of the reviewed case" }, "status": { "type": "string", "enum": [ "recorded" ], "description": "Current status of the review process" }, "reviewed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the review was recorded" } } }, "examples": { "default": { "summary": "Example", "value": { "review_id": "cp_fpol_123456", "case_ref": "FRD-20231010-001", "status": "recorded", "reviewed_at": "2023-10-10T14:48:00.000Z" } } } } } }, "400": { "description": "Request body validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/invalid-json", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication failure due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Ensure your request includes a valid Passport" } } } } } }, "403": { "description": "Access denied due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "Your account does not have the necessary capabilities to initiate a fraud review. Contact support if you believe this is an error." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The organization or resource you are trying to access does not exist. Verify the DID provided." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/humanos/policy/effective": { "get": { "summary": "Retrieve Effective HumanOS Policy", "description": "Discover the confluence of organizational directives within the HUMAN platform. This endpoint reveals the effective HumanOS policy, interwoven with organizational overlays, offering insights into AI task governance and safety protocols.", "operationId": "getEffectiveHumanosPolicy", "tags": [ "HumanOS", "Policy" ], "x-code-hash": "b3a14e82ea144193", "x-generated-at": "2026-04-11T02:49:38.992Z", "responses": { "200": { "description": "Successfully retrieved the effective HumanOS policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_version": { "type": "string", "description": "The version identifier of the policy." }, "fourth_law_confidence_threshold": { "type": "number", "description": "The confidence threshold for the Fourth Law of AI Safety." }, "learning_requires_approval": { "type": "boolean", "description": "Indicates if learning tasks require external approval." }, "learning": { "type": "object", "description": "Details of the effective learning policy.", "additionalProperties": true }, "merged_policy": { "type": "object", "description": "The complete merged policy object with overlays.", "additionalProperties": true }, "policy_resolution": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The decentralized identifier of the organization." }, "team_id": { "type": [ "string", "null" ], "description": "The team identifier if specified." }, "passport_did": { "type": [ "string", "null" ], "description": "The passport DID if specified." } } } } }, "examples": { "acme_org_policy_retrieval": { "summary": "Acme Org Policy Retrieval", "description": "Fetching the effective HumanOS policy for Acme Corporation.", "value": { "policy_version": "1.4.5", "fourth_law_confidence_threshold": 0.85, "learning_requires_approval": true, "learning": { "skill_enhancements": [], "knowledge_sharing": {} }, "merged_policy": { "version": "1.4.5", "overlays": [] }, "policy_resolution": { "org_did": "did:example:acme", "team_id": "team-123", "passport_did": "did:passport:agent-xyz" } } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_team_id": { "summary": "Invalid Team ID", "description": "Error returned when the team ID is invalid.", "value": { "type": "https://example.com/probs/invalid-team-id", "title": "Invalid Team ID", "status": 400, "detail": "The provided team_id 'team-xyz' does not exist.", "errors": [] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "Error returned when no authentication credentials are provided.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please provide valid authentication credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Error returned when user lacks necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "policy_not_found": { "summary": "Policy Not Found", "description": "Error returned when the specified policy cannot be found.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The effective policy for the specified organization could not be found." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "Generic server error.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } } }, "/v1/humanos/policy/org": { "put": { "summary": "Update or create organizational policy", "description": "This endpoint empowers administrators to seamlessly update or create policies for their organization, ensuring that the latest configurations are always in place. By leveraging a cryptographic identity (Passport), the HUMAN protocol guarantees that only authorized users can manage these critical settings.", "operationId": "updateOrgPolicy", "tags": [ "HumanOS", "Policy Management" ], "x-code-hash": "53a07af34b3f81c1", "x-generated-at": "2026-04-11T02:49:51.589Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_json": { "type": "object", "description": "The JSON object representing the organization's policy settings. It acts as a partial overlay to merge with existing policies." } }, "required": [ "policy_json" ] }, "examples": { "update_acme_corp_policy": { "summary": "Update Acme Corp Policy", "description": "This example demonstrates updating the policy document for Acme Corporation, adding a new billing rule.", "value": { "policy_json": { "billing": { "auto_approve": true, "max_limit": 10000 } } } } } } } }, "responses": { "200": { "description": "Successfully updated the organization's policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The decentralized identifier (DID) of the organization." }, "merged_policy": { "type": "object", "description": "The resulting policy after the merge operation." }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the policy was last updated." } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:human:acmeCorp123", "merged_policy": { "billing": { "auto_approve": true, "max_limit": 10000, "previous_rule": "preserved" } }, "updated_at": "2023-10-23T14:55:00Z" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/invalid-request", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "policy_json", "code": "REQUIRED_FIELD_MISSING", "message": "policy_json must be a JSON object (partial org overlay)", "expected": "object", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this policy." } } } } } }, "404": { "description": "Not found error if the organization DID is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "Organization not found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/policy/team/:team_id": { "put": { "summary": "Update Team Policy Overlay", "description": "Seamlessly merge new AI safety policies into your team's existing configuration, ensuring that your organization's human-AI orchestration remains both agile and robust. This endpoint empowers administrators by allowing them to update team-specific capabilities, harnessing the strength of distributed ledger technology for impeccable provenance tracking.", "operationId": "updateTeamPolicyOverlay", "tags": [ "HumanOS", "Policy Management" ], "x-code-hash": "f68cd5eb6716dd97", "x-generated-at": "2026-04-11T02:50:04.317Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_json": { "type": "object", "description": "A JSON object representing the policy overlay to merge into the existing team policy." } }, "required": [ "policy_json" ] }, "examples": { "update_invoicing_policy": { "summary": "Update Invoicing Policy", "description": "An example showing how to update the invoicing policy for a team within an organization.", "value": { "policy_json": { "invoice_approval": { "min_amount": 5000, "requirement": "supervisor_approval" } } } } } } } }, "responses": { "200": { "description": "The team's policy overlay was successfully updated, merging with existing policies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier for the organization." }, "team_id": { "type": "string", "description": "Unique identifier for the team." }, "merged_policy": { "type": "object", "description": "The resulting policy after merging the provided overlay." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the policy was last updated." } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:example:acme", "team_id": "team-1234", "merged_policy": { "invoice_approval": { "min_amount": 5000, "requirement": "supervisor_approval" } }, "updated_at": "2023-12-01T12:34:56Z" } } } } } }, "400": { "description": "Bad request due to invalid input. Check parameter requirements.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "policy_json", "code": "REQUIRED_FIELD_MISSING", "message": "policy_json must be a JSON object (partial team overlay)", "expected": "object", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication required. Ensure correct delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Forbidden. Lack of permissions for this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this team policy" } } } } } }, "404": { "description": "Resource not found. The specified team ID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified team ID does not exist" } } } } } }, "500": { "description": "Internal Server Error. Unexpected condition encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while updating the team policy" } } } } } } } } }, "/v1/humanos/policy/user/self": { "put": { "summary": "Update User's Policy Overlay", "description": "Empower users to tailor their HumanOS task orchestration by updating their policy overlays. This endpoint allows a delegation to redefine how tasks are routed, ensuring that the AI respects personalized rules and preferences.", "operationId": "updateUserPolicySelf", "tags": [ "HumanOS", "Policy Management" ], "x-code-hash": "b572dde562b00a15", "x-generated-at": "2026-04-11T02:50:18.674Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_json": { "type": "object", "description": "A partial user policy overlay defining task routing rules." } }, "required": [ "policy_json" ] }, "examples": { "update_task_routing_policy": { "summary": "Update Task Routing Policy", "description": "An example showing how to update task routing preferences to prioritize safety checks.", "value": { "policy_json": { "task_routing": { "prioritize_safety_checks": true } } } } } } } }, "responses": { "200": { "description": "The user's policy overlay was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The organization's DID associated with the policy update." }, "passport_did": { "type": "string", "description": "The user's passport DID for whom the policy was updated." }, "merged_policy": { "type": "object", "description": "The merged policy after applying the updates." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the policy was updated." } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:example:123456789abcdefghi", "passport_did": "did:example:abcdef123456789", "merged_policy": { "task_routing": { "prioritize_safety_checks": true } }, "updated_at": "2023-10-15T12:30:00Z" } } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "The request lacked valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "The client was authenticated but does not have permission to perform the operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The resource specified was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/humanos/policy/user/:passport_did": { "put": { "summary": "Update User Policy with Passport DID", "description": "Enhance user experience by updating policy overlays for users identified by their Passport DID. This endpoint empowers administrators to tailor AI safety and task routing policies, ensuring the HUMAN platform aligns with organizational needs.", "operationId": "updateUserPolicy", "tags": [ "HumanOS", "Policy Management" ], "x-code-hash": "ed4ef161e6c7e9a7", "x-generated-at": "2026-04-11T02:50:33.258Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_json": { "type": "object", "description": "A JSON object that represents the user's policy settings." } }, "required": [ "policy_json" ] }, "examples": { "update_user_policy": { "summary": "Update User Policy", "description": "Example of a policy update for user tasks and AI interaction.", "value": { "policy_json": { "task_priority": "high", "ai_interaction_level": "restricted" } } } } } } }, "responses": { "200": { "description": "The user policy has been successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The DID of the organization." }, "passport_did": { "type": "string", "description": "The DID of the user's Passport." }, "merged_policy": { "type": "object", "description": "The merged policy object after applying the overlay." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the latest update." } } }, "examples": { "successful_update": { "summary": "Successful Update", "value": { "org_did": "org:example-corp", "passport_did": "did:human:123456789abcdefghi", "merged_policy": { "task_priority": "high", "ai_interaction_level": "restricted" }, "updated_at": "2023-10-15T12:34:56Z" } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "validation_error": { "summary": "Validation Error", "value": { "type": "https://example.com/probs/validation-error", "title": "Invalid Request", "status": 400, "detail": "One or more fields have invalid values.", "errors": [ { "field": "policy_json", "code": "REQUIRED_FIELD_MISSING", "message": "policy_json must be a JSON object (partial user overlay)", "expected": "object", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication Error", "value": { "type": "https://example.com/probs/authentication-error", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Ensure you are authenticated and have the necessary permissions." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "value": { "type": "https://example.com/probs/permission-denied", "title": "Forbidden", "status": 403, "detail": "You do not have the required permissions to update user policy." } } } } } }, "404": { "description": "User not found for the provided Passport DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "user_not_found": { "summary": "User Not Found", "value": { "type": "https://example.com/probs/user-not-found", "title": "Not Found", "status": 404, "detail": "No user found with the specified Passport DID. Verify the DID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/humanos/learning/index": { "get": { "summary": "Retrieve learning pointers with pagination", "description": "Explore the learning index to discover pointers associated with your organization's skillset. This endpoint serves as the navigator through the knowledge network, providing entries that match your criteria. Perfect for organizations aiming to streamline their AI-enabled learning pathways.", "operationId": "getHumanosLearningIndex", "tags": [ "HumanOS", "Learning" ], "x-code-hash": "f7cbdace436c8b0f", "x-generated-at": "2026-04-11T02:50:46.458Z", "responses": { "200": { "description": "Successfully retrieved a paginated list of learning pointers for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier for the organization." }, "resource_kind": { "type": "string", "description": "Type of the resource in the learning index." }, "resource_id": { "type": "string", "description": "Unique identifier for the specific resource." }, "scope": { "type": "string", "description": "Scope of the learning resource." }, "team_id": { "type": "string", "description": "Identifier for the team associated with the learning resource." }, "summary": { "type": "string", "description": "A brief overview of the learning resource." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last update to the learning resource." } } } }, "limit": { "type": "integer", "description": "The maximum number of items to return." }, "hasMore": { "type": "boolean", "description": "Indicates if there are more items beyond the current page." }, "cursorFields": { "type": "array", "items": { "type": "string" }, "description": "Fields used for pagination cursor." }, "totalCount": { "type": "integer", "nullable": true, "description": "Total count of items, if available." } } }, "examples": { "sample_response": { "summary": "Sample Response", "description": "A list of learning pointers for the 'acme' organization.", "value": { "data": [ { "org_did": "did:human:org:acme", "resource_kind": "invoice-processor", "resource_id": "12345", "scope": "finance", "team_id": "team-67890", "summary": "Automated invoice processing for increased efficiency.", "updated_at": "2023-10-01T12:34:56Z" } ], "limit": 10, "hasMore": true, "cursorFields": [ "updated_at", "resource_kind", "resource_id" ], "totalCount": null } } } } } }, "400": { "description": "Invalid request due to malformed pagination parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination_parameters": { "summary": "Invalid Pagination Parameters", "description": "Occurs when the `limit` or `cursor` parameters are not valid.", "value": { "type": "https://humanprotocol.org/probs/invalid-pagination", "title": "Invalid Pagination Parameters", "status": 400, "detail": "The `limit` parameter must be a positive integer.", "errors": [ "`limit` must be a positive integer." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid organizational delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "The request lacks proper delegation credentials.", "value": { "type": "https://humanprotocol.org/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Ensure your request includes valid delegation credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have the necessary permissions to access this resource.", "value": { "type": "https://humanprotocol.org/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these learning pointers." } } } } } }, "404": { "description": "Resource not found, possibly due to incorrect identifiers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Occurs when the specified resource cannot be located.", "value": { "type": "https://humanprotocol.org/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested learning pointer was not found. Verify the resource identifiers." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected condition was encountered.", "value": { "type": "https://humanprotocol.org/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/learning/proposals": { "get": { "summary": "Retrieve learning proposals with pagination", "description": "In a world where human expertise meets AI orchestration, learning proposals are the blueprints for adaptive growth. This endpoint allows organizations to fetch these proposals, ensuring they harness the right skills at the right time. Pagination and status filtering provide fine-tuned control over the data flow.", "operationId": "getLearningProposals", "tags": [ "HumanOS", "Learning" ], "x-code-hash": "2ee5b69731c7173e", "x-generated-at": "2026-04-11T02:50:59.579Z", "responses": { "200": { "description": "Successfully retrieved a list of learning proposals with pagination and filtering capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "proposal_id": { "type": "string" }, "org_did": { "type": "string" }, "passport_did": { "type": "string" }, "scope": { "type": "string" }, "status": { "type": "string" }, "proposal_kind": { "type": "string" }, "payload": { "type": "object" }, "explain": { "$ref": "#/components/schemas/LearningExplainMetadata" }, "approval_request_id": { "type": "string" }, "source_feedback_ids": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total_count": { "type": [ "integer", "null" ] } } }, "examples": { "successful_retrieval": { "summary": "Successful retrieval", "value": { "data": [ { "proposal_id": "prop-123", "org_did": "did:example:org123", "passport_did": "did:example:passport456", "scope": "capability://data-processing", "status": "pending", "proposal_kind": "skill-enhancement", "payload": { "task": "Process invoice for Acme Corp", "details": "Improve accuracy of invoice categorization" }, "explain": { "reason": "To enhance financial processing skills", "expected_outcome": "Reduced errors in invoice processing" }, "approval_request_id": "req-789", "source_feedback_ids": [ "fb-001", "fb-002" ], "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T12:00:00Z", "expires_at": "2023-11-01T12:00:00Z" } ], "has_more": false, "next_cursor": null, "total_count": null } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameters": { "summary": "Invalid parameters", "value": { "type": "https://humanos.example.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'limit' parameter must be a positive integer.", "errors": [ { "field": "limit", "message": "Must be a positive integer." } ] } } } } } }, "401": { "description": "Authentication is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_or_invalid_authentication": { "summary": "Missing or invalid authentication", "value": { "type": "https://humanos.example.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Ensure your request includes a valid authentication token." } } } } } }, "403": { "description": "Permission denied for the requested operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission denied", "value": { "type": "https://humanos.example.com/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access these learning proposals. Contact your administrator for access." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "type": "https://humanos.example.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified learning proposal could not be found. Verify the proposal ID and try again." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "value": { "type": "https://humanos.example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } }, "post": { "summary": "Draft a new learning proposal", "description": "Create a draft proposal to orchestrate human learning tasks with AI safety. This endpoint empowers organizations to define and track skills development initiatives, ensuring each proposal is routed efficiently while maintaining a secure and auditable trail.", "operationId": "createHumanosLearningProposal", "tags": [ "HumanOS", "Learning" ], "x-code-hash": "741c6b630d531319", "x-generated-at": "2026-04-11T02:51:18.684Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_kind": { "type": "string", "description": "The type of learning proposal being created." }, "scope": { "type": "string", "description": "The scope of the proposal, defaults to 'org'." }, "passport_did": { "type": "string", "description": "The cryptographic identity of the passport associated with the proposal." }, "approval_request_id": { "type": "string", "description": "ID for the approval request, if applicable." }, "source_feedback_ids": { "type": "array", "items": { "type": "integer" }, "description": "Identifiers for feedback sources related to the proposal." }, "expires_at": { "type": "string", "format": "date-time", "description": "The expiration timestamp for the proposal." }, "payload": { "type": "object", "description": "Additional data associated with the proposal." }, "explain": { "$ref": "#/components/schemas/LearningExplainMetadata", "description": "Optional explanation metadata for the proposal." } }, "required": [ "proposal_kind" ] }, "examples": { "basic_learning_proposal": { "summary": "Basic Learning Proposal", "description": "A simple draft proposal for a new training module.", "value": { "proposal_kind": "new_training_module", "scope": "org", "passport_did": "did:human:123456789abcdefghi", "approval_request_id": "approval-6789", "source_feedback_ids": [ 101, 102 ], "expires_at": "2023-12-31T23:59:59Z", "payload": { "module": "Advanced AI Ethics" }, "explain": { "source": "internal_review", "scope": "org", "confidence": 0.95, "evidence_refs": [ "doc1", "doc2" ], "approval_state": "pending", "changed_at": "2023-10-01T12:00:00Z", "changed_by": "did:human:agent123", "rollback_target": "v1.0", "expiry": "2023-11-30T23:59:59Z" } } } } } } }, "responses": { "201": { "description": "The learning proposal was successfully created and is now in draft status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string" }, "org_did": { "type": "string" }, "status": { "type": "string" }, "proposal_kind": { "type": "string" }, "payload": { "type": "object" }, "explain": { "$ref": "#/components/schemas/LearningExplainMetadata" }, "approval_request_id": { "type": "string" }, "source_feedback_ids": { "type": "array", "items": { "type": "integer" } }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "summary": "Example", "value": { "proposal_id": "lrp-20231001-abc123", "org_did": "did:human:org123", "status": "draft", "proposal_kind": "new_training_module", "payload": { "module": "Advanced AI Ethics" }, "explain": { "source": "internal_review", "scope": "org", "confidence": 0.95, "evidence_refs": [ "doc1", "doc2" ], "approval_state": "pending", "changed_at": "2023-10-01T12:00:00Z", "changed_by": "did:human:agent123", "rollback_target": "v1.0", "expiry": "2023-11-30T23:59:59Z" }, "approval_request_id": "approval-6789", "source_feedback_ids": [ 101, 102 ], "expires_at": "2023-12-31T23:59:59Z", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-01T12:00:00Z" } } } } } }, "400": { "description": "The request could not be understood due to malformed syntax.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanos.com/errors/validation", "title": "Invalid Request Body", "status": 400, "detail": "Request body must be valid JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be valid JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "The request requires user authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanos.com/errors/authentication", "title": "Authentication Required", "status": 401, "detail": "Delegation required. Please ensure your request includes a valid Passport." } } } } } }, "403": { "description": "The client does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanos.com/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create learning proposals for this organization." } } } } } }, "404": { "description": "The server has not found anything matching the request URI.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanos.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The resource you are looking for does not exist." } } } } } }, "500": { "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanos.com/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/learning/proposals/:proposal_id": { "get": { "summary": "Retrieve a specific learning proposal.", "description": "Fetch details of a learning proposal for an organization in the HUMAN network, empowering you to track AI skill enhancements with precision and accountability. Understand the status, scope, and feedback of your proposals at a glance, ensuring your initiatives align with organizational goals.", "operationId": "getLearningProposal", "tags": [ "HumanOS", "Learning" ], "x-code-hash": "d792f727f2bc4694", "x-generated-at": "2026-04-11T02:51:31.999Z", "responses": { "200": { "description": "Successfully retrieved the learning proposal details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "Unique identifier of the learning proposal." }, "org_did": { "type": "string", "description": "Decentralized identifier of the organization." }, "passport_did": { "type": "string", "description": "Decentralized identifier of the passport associated with the proposal." }, "scope": { "type": "string", "description": "Scope of the learning proposal." }, "status": { "type": "string", "description": "Current status of the proposal." }, "proposal_kind": { "type": "string", "description": "Type of the learning proposal." }, "payload": { "type": "object", "description": "Detailed payload of the proposal." }, "explain": { "$ref": "#/components/schemas/LearningExplainMetadata" }, "approval_request_id": { "type": "string", "description": "Identifier for the approval request linked to this proposal." }, "source_feedback_ids": { "type": "array", "items": { "type": "string" }, "description": "List of feedback identifiers associated with the proposal." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration timestamp of the proposal." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp of the proposal." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp of the proposal." } }, "required": [ "proposal_id", "org_did", "status", "created_at" ] }, "examples": { "acme_corp_proposal": { "summary": "Acme Corp Proposal", "description": "An example of a learning proposal retrieved for the Acme Corp organization.", "value": { "proposal_id": "abc123", "org_did": "did:human:acme", "passport_did": "did:human:john.doe", "scope": "AI skill enhancement", "status": "approved", "proposal_kind": "training", "payload": { "course": "Advanced AI Ethics" }, "explain": { "reason": "Aligns with strategic goals", "impact": "Increases team efficiency" }, "approval_request_id": "req-456def", "source_feedback_ids": [ "fb-789ghi" ], "expires_at": "2024-01-01T00:00:00Z", "created_at": "2023-08-15T12:00:00Z", "updated_at": "2023-09-01T08:30:00Z" } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_proposal_id": { "summary": "Invalid Proposal ID", "description": "The proposal ID format was incorrect.", "value": { "type": "https://human.com/probs/invalid-proposal-id", "title": "Invalid Proposal ID", "status": 400, "detail": "The provided proposal_id is not in a valid format. Please ensure it is a valid UUID.", "errors": [ "proposal_id must be a valid UUID" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing Delegation", "description": "The request was unauthenticated due to missing organization delegation.", "value": { "type": "https://human.com/probs/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation required. Please ensure your request includes a valid organizational delegation." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "The user does not have permission to access the learning proposal.", "value": { "type": "https://human.com/probs/forbidden-access", "title": "Forbidden Access", "status": 403, "detail": "You do not have the necessary permissions to view this learning proposal. Contact your administrator for access." } } } } } }, "404": { "description": "The specified learning proposal was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "proposal_not_found": { "summary": "Proposal Not Found", "description": "The learning proposal with the given ID does not exist.", "value": { "type": "https://human.com/probs/not-found", "title": "Proposal Not Found", "status": 404, "detail": "The learning proposal with ID abc123 could not be found. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_error": { "summary": "Database Error", "description": "An unexpected error occurred when querying the database.", "value": { "type": "https://human.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request. Please try again later." } } } } } } } }, "patch": { "summary": "Update Learning Proposal Status", "description": "Navigate the complex journey of transforming a learning proposal's status with precision. This endpoint empowers you to orchestrate seamless transitions, ensuring that proposals progress through the appropriate lifecycle stages while maintaining compliance with server-enforced status transitions.", "operationId": "patchHumanosLearningProposal", "tags": [ "HumanOS", "Learning Proposals" ], "x-code-hash": "82581a7b60f9bd1b", "x-generated-at": "2026-04-11T02:51:44.867Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "pending_review", "approved", "rejected", "applied", "rolled_back" ], "description": "The new status for the proposal." }, "approval_request_id": { "type": "string", "nullable": true, "description": "Optional ID for an approval request related to this status change." } }, "required": [ "status" ] }, "examples": { "transition_to_pending_review": { "summary": "Transition to Pending Review", "description": "This example demonstrates updating a proposal status from 'draft' to 'pending_review' with an associated approval request.", "value": { "status": "pending_review", "approval_request_id": "approval-1234" } } } } } }, "responses": { "200": { "description": "The learning proposal status was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "The identifier for the proposal." }, "org_did": { "type": "string", "description": "The decentralized identifier (DID) of the organization." }, "status": { "type": "string", "description": "The current status of the proposal." }, "proposal_kind": { "type": "string", "description": "The kind of proposal." }, "payload": { "type": "object", "description": "The detailed payload of the proposal." }, "explain": { "$ref": "#/components/schemas/LearningExplainMetadata" }, "approval_request_id": { "type": "string", "nullable": true, "description": "The ID of the approval request if any." }, "expires_at": { "type": "string", "format": "date-time", "description": "The expiration date of the proposal." }, "updated_at": { "type": "string", "format": "date-time", "description": "The timestamp when the proposal was last updated." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was malformed or contained invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-status-transition", "title": "Invalid status transition", "status": 400, "detail": "Invalid learning proposal status transition", "errors": [ { "field": "status", "code": "INVALID_STATUS_TRANSITION", "message": "status must transition from draft to pending_review, rejected; pending_review to approved, rejected, draft; approved to rejected, pending_review; rejected to draft; rolled_back to draft", "expected": "draft → pending_review (or same status for no-op)", "received": "draft → applied" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication-required", "title": "Authentication required", "status": 401, "detail": "Delegation required. Please provide a valid authentication token." } } } } } }, "403": { "description": "The server understood the request, but refuses to authorize it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/permission-denied", "title": "Permission denied", "status": 403, "detail": "You do not have permission to change the status of this learning proposal." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The learning proposal with ID proposal-5678 was not found. Please verify the proposal ID and try again." } } } } } }, "500": { "description": "An internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request. Please try again later." } } } } } } } } }, "/v1/humanos/learning/proposals/:proposal_id/apply": { "post": { "summary": "Apply an approved learning proposal", "description": "In the dynamic world of HumanOS, this endpoint breathes life into your approved learning proposals, transforming potential into action. By applying an approved proposal, you propel your organization into the future, harnessing the power of adaptive learning to stay ahead in the ever-evolving landscape.", "operationId": "applyHumanosLearningProposal", "tags": [ "HumanOS" ], "x-code-hash": "e90bef78716434a4", "x-generated-at": "2026-04-11T02:51:59.486Z", "responses": { "200": { "description": "The proposal was successfully applied, marking a new chapter in your organization's learning journey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "The unique identifier of the applied proposal." }, "status": { "type": "string", "enum": [ "applied" ], "description": "The status of the proposal after application." }, "tuning_action_id": { "type": "string", "description": "The unique identifier of the tuning action created." }, "action_type": { "type": "string", "description": "The type of action performed by the tuning." }, "scope": { "type": "string", "description": "The scope of the applied proposal." }, "tuning_expires_at": { "type": "string", "format": "date-time", "description": "The expiration timestamp for the tuning action." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the proposal was applied." } } }, "examples": { "successful_application": { "summary": "Successful Application", "description": "A successful application of an approved learning proposal.", "value": { "proposal_id": "prop123456", "status": "applied", "tuning_action_id": "tun789012", "action_type": "set_preference", "scope": "org", "tuning_expires_at": "2023-12-31T23:59:59Z", "created_at": "2023-11-01T12:00:00Z" } } } } } }, "400": { "description": "Proposal payload validation failed due to missing or invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_action_type": { "summary": "Missing Action Type", "description": "An attempt to apply a proposal without the required action_type in the payload.", "value": { "type": "https://humanos.com/probs/invalid-payload", "title": "Invalid Proposal Payload", "status": 400, "detail": "Proposal payload must include action_type for apply", "errors": [ { "field": "proposal.payload.action_type", "code": "INVALID_PROPOSAL_PAYLOAD", "message": "Proposal payload must include action_type for apply", "expected": "string", "received": "missing" } ] } } } } } }, "403": { "description": "Organization's policy prohibits learning actions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "learning_disabled": { "summary": "Learning Disabled", "description": "An attempt to apply a learning proposal when the organization's learning is disabled.", "value": { "type": "https://humanos.com/probs/learning-disabled", "title": "Learning Disabled", "status": 403, "detail": "Org policy has learning disabled" } } } } } }, "404": { "description": "The specified proposal was not found within the organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "proposal_not_found": { "summary": "Proposal Not Found", "description": "An attempt to apply a proposal that does not exist.", "value": { "type": "https://humanos.com/probs/not-found", "title": "Proposal Not Found", "status": 404, "detail": "The learning proposal with ID prop123456 could not be found." } } } } } }, "409": { "description": "Conflict due to proposal not being approved or already applied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "proposal_already_applied": { "summary": "Proposal Already Applied", "description": "An attempt to apply a proposal that has already been applied.", "value": { "type": "https://humanos.com/probs/conflict", "title": "Proposal Conflict", "status": 409, "detail": "Learning proposal was already applied." } } } } } }, "500": { "description": "An unexpected error occurred while applying the proposal.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "An unexpected server error during proposal application.", "value": { "type": "https://humanos.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } } }, "/v1/humanos/learning/proposals/:proposal_id/rollback": { "post": { "summary": "Roll back a learning proposal", "description": "This endpoint empowers organizations to roll back previously applied learning proposals within HumanOS. By reversing an applied proposal, the system ensures flexibility and adaptability in dynamic environments, allowing for strategic pivots when necessary.", "operationId": "rollbackHumanosLearningProposal", "tags": [ "HumanOS", "Learning" ], "x-code-hash": "cf6f3199090bd90c", "x-generated-at": "2026-04-11T02:52:11.639Z", "responses": { "200": { "description": "Successfully rolled back the learning proposal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "Identifier of the rolled-back proposal" }, "status": { "type": "string", "enum": [ "rolled_back" ], "description": "Updated status of the proposal" }, "compensating_tuning_action_id": { "type": "string", "description": "ID of the compensating tuning action" }, "scope": { "type": "string", "description": "Scope of the rollback operation" }, "superseded_tuning_action_id": { "type": [ "string", "null" ], "description": "ID of the previous tuning action, if any" } }, "required": [ "proposal_id", "status", "compensating_tuning_action_id", "scope" ] }, "examples": { "successful_rollback": { "summary": "Successful rollback", "description": "Example of a successful rollback of a learning proposal.", "value": { "proposal_id": "abc123", "status": "rolled_back", "compensating_tuning_action_id": "tun567", "scope": "org", "superseded_tuning_action_id": "tun789" } } } } } }, "400": { "description": "Bad request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request": { "summary": "Invalid Request", "description": "The request was malformed, invalid proposal ID.", "value": { "type": "https://api.human.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The proposal ID provided is invalid.", "errors": [ "Invalid proposal ID format." ] } } } } } }, "401": { "description": "Authentication error due to missing delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication Required", "description": "Delegation is required to roll back a proposal.", "value": { "type": "https://api.human.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Delegation required to perform this action. Please authenticate with appropriate credentials." } } } } } }, "403": { "description": "Learning feature is disabled in the organization's policy.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "feature_disabled": { "summary": "Feature Disabled", "description": "The organization has disabled learning functionalities.", "value": { "type": "https://api.human.com/probs/feature-disabled", "title": "Feature Disabled", "status": 403, "detail": "Org policy has learning disabled. Contact your administrator to enable this feature." } } } } } }, "404": { "description": "Learning proposal not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "proposal_not_found": { "summary": "Proposal Not Found", "description": "The requested learning proposal does not exist.", "value": { "type": "https://api.human.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Learning proposal with ID 'abc123' was not found. Verify the proposal ID and try again." } } } } } }, "409": { "description": "Conflict due to the proposal not being applied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "proposal_not_applied": { "summary": "Proposal Not Applied", "description": "Attempt to roll back a proposal that wasn't applied.", "value": { "type": "https://api.human.com/probs/conflict", "title": "Conflict", "status": 409, "detail": "Learning proposal must be applied before rollback (current status: pending). Apply the proposal first, then retry." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "Unexpected error during rollback process.", "value": { "type": "https://api.human.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the rollback. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/humanos/learning/infer/v0": { "post": { "summary": "Infer learning proposals from feedback", "description": "Harness the power of collective intelligence by transforming feedback into actionable learning proposals. This endpoint analyzes recent feedback events within your organization to suggest improvements, helping you stay ahead in a rapidly evolving landscape.", "operationId": "inferLearningProposalsV0", "tags": [ "HumanOS", "Learning" ], "x-code-hash": "709033d36d5f9910", "x-generated-at": "2026-04-11T02:52:24.674Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum number of feedback events to process. Defaults to 20 if not specified.", "minimum": 1, "maximum": 100 } } }, "examples": { "limit_feedback_events": { "summary": "Limit Feedback Events", "description": "Request to process up to 30 feedback events.", "value": { "limit": 30 } } } } } }, "responses": { "200": { "description": "Successfully generated learning proposals from feedback events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized identifier for the organization." }, "drafts": { "type": "array", "description": "Array of inferred learning proposals.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the learning proposal." }, "payload_type": { "type": "string", "description": "Type of payload associated with the proposal." }, "payload": { "type": "object", "description": "Detailed content of the learning proposal." } } } }, "feedback_rows_considered": { "type": "integer", "description": "Number of feedback events considered in the analysis." } } }, "examples": { "default": { "summary": "Example", "value": { "org_did": "did:example:123456789abcdef", "drafts": [ { "id": "proposal-001", "payload_type": "improvement", "payload": { "title": "Enhance AI Model Accuracy", "description": "Implement new data augmentation techniques to improve model performance." } } ], "feedback_rows_considered": 30 } } } } } }, "400": { "description": "Invalid request due to incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid Parameters", "status": 400, "detail": "The 'limit' parameter must be a number between 1 and 100." } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please authenticate with a valid Passport." } } } } } }, "403": { "description": "Forbidden request due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The organization data could not be located for the provided DID." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/humanos/risk/calibrate": { "post": { "summary": "Calibrate audit event risk embeddings", "description": "Enhance your audit insights by recalibrating the risk scores of humanos audit events with fresh embeddings. This endpoint exists to ensure your risk assessment remains accurate and up-to-date, leveraging the power of AI for more precise decision-making.", "operationId": "calibrateRiskEmbeddings", "tags": [ "Risk Management", "Audit" ], "x-code-hash": "4dc3120c171fd3fa", "x-generated-at": "2026-04-12T16:18:46.265Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "full", "incremental" ], "description": "Determines whether to perform a full recalibration or an incremental update." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "description": "Limits the number of events processed in this request." }, "after_id": { "type": "integer", "description": "The ID to start processing from, for pagination purposes." } } }, "examples": { "full_calibration_with_limit": { "summary": "Full calibration with limit", "description": "Requests a full recalibration of audit events with a limit of 200.", "value": { "mode": "full", "limit": 200 } } } } } }, "responses": { "200": { "description": "Embeddings recalibrated successfully, returning a summary of the operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "integer", "description": "Number of events queued for recalibration." }, "already_embedded": { "type": "integer", "description": "Total count of events that already have embeddings." }, "next_after_id": { "type": "integer", "description": "The ID to be used in the next request for continued processing." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized request due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden: The current user does not have the required permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found, possibly due to an invalid after_id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error due to an unexpected issue.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/.well-known/bbs-public-key": { "get": { "summary": "Retrieve BBS+ Issuer Verification Key", "description": "Unveil the powerful BBS+ issuer verification key, designed for offline verifiers to ensure trust without the tether of constant connectivity. By accessing this endpoint, you empower decentralized identity systems to validate credentials authentically and securely.", "operationId": "getBbsPublicKeyWellKnown", "tags": [ "Identity", "Cryptography" ], "x-code-hash": "d533e6f3edc413ae", "x-generated-at": "2026-04-12T15:43:13.970Z", "responses": { "200": { "description": "Successfully retrieved the public BBS+ issuer verification key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string" }, "kid": { "type": "string" }, "use": { "type": "string" }, "alg": { "type": "string" }, "n": { "type": "string" }, "e": { "type": "string" } }, "required": [ "kty", "kid", "use", "alg", "n", "e" ] } } }, "required": [ "keys" ] }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "description": "Retrieve the BBS+ issuer verification key for offline verification.", "value": { "keys": [ { "kty": "RSA", "kid": "1a2b3c4d", "use": "sig", "alg": "RS256", "n": "abc123...", "e": "AQAB" } ] } } } } } }, "503": { "description": "BBS+ issuer not configured properly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "issuer_not_configured": { "summary": "Issuer Not Configured", "description": "The system is unable to provide the BBS+ key as it is not configured.", "value": { "type": "https://human.example/problems/bbs-issuer-not-configured", "title": "BBS+ issuer not configured", "status": 503, "detail": "Set PASSPORT_BBS_ISSUER_PUBLIC_KEY_JWK or PASSPORT_BBS_ISSUER_PRIVATE_KEY_JWK." } } } } } } } } }, "/v1/passports/:did/devices/sync/:sessionId/signal": { "post": { "summary": "Signal device sync for passport session", "description": "This endpoint is a digital bridge connecting devices within a user's cryptographic identity, enabling them to exchange signaling information securely. By allowing devices to sync signals like 'offer', 'answer', or 'ice-candidate', it ensures seamless interaction and coordination within the HUMAN network, enhancing efficiency and safety.", "operationId": "signalDeviceSync", "tags": [ "Passports", "Devices", "Sync" ], "x-code-hash": "8cddaffcd8448d66", "x-generated-at": "2026-04-12T15:57:58.940Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "offer", "answer", "ice-candidate" ], "description": "The type of signal being sent" }, "payload": { "type": "string", "description": "The signaling payload data to be transmitted" }, "from_device_id": { "type": "string", "description": "Identifier of the device sending the signal" } }, "required": [ "type", "payload", "from_device_id" ] }, "examples": { "device_signaling_offer": { "summary": "Device signaling offer", "description": "A device sends an offer to initiate a WebRTC connection", "value": { "type": "offer", "payload": "v=0\r\n...", "from_device_id": "device-123" } } } } } }, "responses": { "200": { "description": "Signals successfully synced between devices", "content": { "application/json": { "schema": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "payload": { "type": "string" }, "from_device_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "examples": { "successful_signal_sync": { "summary": "Successful signal sync", "description": "Devices successfully exchanged signaling information", "value": { "signals": [ { "type": "offer", "payload": "v=0\r\n...", "from_device_id": "device-123", "created_at": "2023-10-05T14:48:00.000Z" } ] } } } } } }, "400": { "description": "Invalid request due to incorrect input data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_required_fields": { "summary": "Missing required fields", "value": { "type": "/problems/validation", "title": "Validation error", "status": 400, "detail": "The payload and from_device_id fields are required.", "errors": [ { "field": "body", "code": "REQUIRED_FIELD_MISSING", "message": "payload and from_device_id (or from_device) are required", "expected": "strings", "received": "incomplete" } ] } } } } } }, "401": { "description": "Authentication required to access the endpoint", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing authentication", "value": { "type": "/problems/authentication", "title": "Authentication required", "status": 401, "detail": "You must authenticate to signal for a passport session." } } } } } }, "403": { "description": "Authorization error due to permission issues", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_device_access": { "summary": "Unauthorized device access", "value": { "type": "/problems/authorization", "title": "Authorization error", "status": 403, "detail": "You may only signal for your own passport." } } } } } }, "404": { "description": "Session not found for the given identifiers", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "session_not_found": { "summary": "Session not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The session id provided does not exist." } } } } } }, "500": { "description": "Internal server error due to unexpected issues", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred, please try again later." } } } } } } } }, "get": { "summary": "Retrieve synchronized signals for device", "description": "Harness the potential of secure identity with HUMAN's Passport by retrieving synchronized signals for a specific device session. This endpoint empowers users to poll device signals, ensuring that only authorized individuals can access their cryptographic identities' data.", "operationId": "getDeviceSyncSignals", "tags": [ "Passports", "Devices" ], "x-code-hash": "de0ed9501d870023", "x-generated-at": "2026-04-12T15:43:56.201Z", "responses": { "200": { "description": "Successfully retrieved device signals for the session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "signalId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } } } } } }, "examples": { "successful_signal_retrieval": { "summary": "Successful signal retrieval", "description": "An example showing successfully fetched signals for a session.", "value": { "signals": [ { "signalId": "sig123", "timestamp": "2023-10-14T14:23:00Z", "payload": { "type": "heartbeat", "value": "normal" } } ] } } } } } }, "400": { "description": "Request is malformed or missing crucial parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_or_malformed_did": { "summary": "Missing or malformed DID", "description": "The DID parameter is missing or does not conform to the required format.", "value": { "type": "https://example.com/probs/malformed-did", "title": "Malformed DID", "status": 400, "detail": "The DID provided is either missing or incorrectly formatted. Ensure it starts with 'did:human:'." } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_required": { "summary": "Authentication required", "description": "The user is not authenticated.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "Please provide valid authentication credentials to access this endpoint." } } } } } }, "403": { "description": "Access is forbidden for the provided DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "User attempts to access signals for a DID they do not own.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You may only poll signals for your own passport. Ensure the DID matches your authentication credentials." } } } } } }, "404": { "description": "The specified session could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "session_not_found": { "summary": "Session not found", "description": "The session ID provided does not exist.", "value": { "type": "https://example.com/probs/session-not-found", "title": "Session Not Found", "status": 404, "detail": "The session ID could not be located. Verify that the session ID is correct and try again." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/passports/:did/devices/revocation-events": { "get": { "summary": "Retrieve Passport Device Revocation Events", "description": "Explore the journey of your cryptographic identity by accessing a history of device revocation events linked to your HUMAN Passport. This endpoint enables users to verify and understand the security actions taken on their devices, ensuring transparency and trust in the orchestration between humans and AI.", "operationId": "getPassportDeviceRevocationEvents", "tags": [ "Identity Management", "Security" ], "x-code-hash": "9e5d83a8a50e2e93", "x-generated-at": "2026-04-12T15:58:07.998Z", "responses": { "200": { "description": "A list of revocation events for the specified passport, along with the public key of the revocation hub.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "passport_did": { "type": "string" }, "revoked_device_id": { "type": "string" }, "revoked_at": { "type": "string", "format": "date-time" }, "signed_by_device_id": { "type": "string" }, "revocation_signature": { "type": "string" }, "request_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "passport_did", "revoked_device_id", "revoked_at", "signed_by_device_id", "revocation_signature", "created_at" ] } }, "hub_public_key": { "type": "string" } }, "required": [ "data", "hub_public_key" ] }, "examples": { "revocation_event_list": { "summary": "Revocation Event List", "description": "An example showing a set of device revocation events for a specific passport.", "value": { "data": [ { "id": "rev_12345", "passport_did": "did:human:acme123", "revoked_device_id": "device_67890", "revoked_at": "2023-10-01T12:34:56Z", "signed_by_device_id": "device_11111", "revocation_signature": "signature_string", "request_id": "req_98765", "created_at": "2023-10-01T12:34:56Z" } ], "hub_public_key": "public_key_base64url" } } } } } }, "400": { "description": "The request was malformed, such as an invalid 'since' parameter.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_since_parameter": { "summary": "Invalid Since Parameter", "value": { "type": "https://humanprotocol.org/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'since' parameter must be a valid ISO 8601 date-time string." } } } } } }, "401": { "description": "Authentication is required to access revocation events.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://humanprotocol.org/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must provide valid authentication credentials to access this resource." } } } } } }, "403": { "description": "Authorization failed because the user attempted to access another passport's revocation events.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://humanprotocol.org/probs/unauthorized", "title": "Unauthorized Access", "status": 403, "detail": "You may only list revocation events for your own passport." } } } } } }, "404": { "description": "The specified DID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "did_not_found": { "summary": "DID Not Found", "value": { "type": "https://humanprotocol.org/probs/not-found", "title": "DID Not Found", "status": 404, "detail": "The requested DID was not found in the system." } } } } } }, "500": { "description": "An unexpected server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanprotocol.org/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/recovery/:requestId/complete-with-proof": { "post": { "summary": "Complete Recovery with Proof", "description": "This endpoint finalizes the recovery of a cryptographic identity using client-side reconstructed HMAC proof. It empowers users to securely reclaim their digital identity in a decentralized manner, ensuring that only legitimate recovery requests are completed.", "operationId": "completeRecoveryWithProof", "tags": [ "Identity Management", "Security" ], "x-code-hash": "02cfbdd20f275853", "x-generated-at": "2026-04-12T15:56:57.671Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proof_of_reconstruction": { "type": "string", "description": "A cryptographic proof to verify the reconstruction process." }, "new_device_public_key": { "type": "string", "description": "The public key of the new device to associate with the identity." }, "registration_id": { "type": "string", "description": "Unique identifier for the registration process." }, "credential": { "type": "object", "description": "Additional credential details required for verification." } }, "required": [ "proof_of_reconstruction", "new_device_public_key", "registration_id", "credential" ] }, "examples": { "successful_recovery_example": { "summary": "Successful Recovery Example", "description": "An example of a successful recovery request with all necessary fields.", "value": { "proof_of_reconstruction": "hmac-encoded-proof", "new_device_public_key": "new-device-public-key", "registration_id": "reg123456", "credential": { "type": "webauthn", "data": "credential-data" } } } } } } }, "responses": { "200": { "description": "The recovery process was successfully completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message of successful recovery." }, "new_device_id": { "type": "string", "description": "Identifier of the newly registered device." } } }, "examples": { "default": { "summary": "Example", "value": { "message": "Recovery completed successfully.", "new_device_id": "device123" } } } } } }, "400": { "description": "The request was malformed or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/invalid-request", "title": "Validation Error", "status": 400, "detail": "proof_of_reconstruction, new_device_public_key, registration_id, and credential are required.", "errors": [ { "field": "proof_of_reconstruction", "code": "REQUIRED_FIELD_MISSING", "message": "Field is required", "expected": "object", "received": "incomplete" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to complete this request." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "The specified recovery request could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/not-found", "title": "Not Found", "status": 404, "detail": "The recovery request ID provided does not exist." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:id/recovery/:requestId/submit-shard-p2p": { "post": { "summary": "Submit Shard for Guardian Recovery", "description": "Embark on a journey of digital resurrection as you submit the vital cryptographic shard needed for recovering a lost device. This endpoint ensures that the guardians of your identity unite to restore access, maintaining the sanctity of your cryptographic Passport.", "operationId": "submitShardP2pRecovery", "tags": [ "Passport", "Recovery" ], "x-code-hash": "4427576147314c64", "x-generated-at": "2026-04-12T15:57:18.920Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proof_of_reconstruction": { "type": "string", "description": "Proof that the shards have been correctly reassembled" }, "new_device_public_key": { "type": "string", "description": "Public key of the new device being registered" }, "registration_id": { "type": "string", "description": "Registration identifier for the new device" }, "credential": { "type": "object", "description": "Credential object or WebAuthn attestation", "additionalProperties": true }, "webauthn_attestation": { "type": "object", "description": "WebAuthn attestation details, alternative to credential", "additionalProperties": true } }, "required": [ "proof_of_reconstruction", "new_device_public_key", "registration_id", "credential" ] }, "examples": { "successful_recovery_submission": { "summary": "Successful Recovery Submission", "description": "A valid submission with all required fields", "value": { "proof_of_reconstruction": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "new_device_public_key": "04bfcab2f53a...", "registration_id": "reg-12345", "credential": { "type": "public-key", "id": "MIGbMBAGByqG...", "rawId": "MIGbMBAGByqG...", "response": { "clientDataJSON": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "attestationObject": "o2NmbWF0dGVzdCJoYWxmc2FtbGJuZGZzdGc=" } } } } } } } }, "responses": { "200": { "description": "The cryptographic shard was successfully submitted, and the guardian recovery process is underway.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Confirmation of the recovery process initiation", "example": "Recovery process initiated successfully" } } }, "examples": { "default": { "summary": "Example", "value": { "status": "Recovery process initiated successfully" } } } } } }, "400": { "description": "The request body is missing required fields or contains invalid data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "proof_of_reconstruction, new_device_public_key, registration_id, and credential are required", "errors": [ { "field": "proof_of_reconstruction", "code": "REQUIRED_FIELD_MISSING", "message": "This field is required" } ] } } } } } }, "401": { "description": "Unauthorized access - the request did not include valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to perform this action." } } } } } }, "403": { "description": "Forbidden - the client does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to submit this recovery shard." } } } } } }, "404": { "description": "Not Found - the recovery request with the specified ID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/not-found", "title": "Not Found", "status": 404, "detail": "The recovery request ID does not match any existing recovery process." } } } } } }, "409": { "description": "Conflict - not enough guardian approvals to proceed with the recovery.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/threshold-not-met", "title": "Threshold Not Met", "status": 409, "detail": "Not enough guardian approvals for this recovery request." } } } } } }, "422": { "description": "Unprocessable Entity - recovery cannot be completed due to missing or invalid proof verifier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/recovery-not-ready", "title": "Recovery Not Ready", "status": 422, "detail": "Recovery cannot be completed: request not found, not approved, or proof verifier missing." } } } } } }, "423": { "description": "Locked - the guardian recovery lock period is still active.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/lock-period-active", "title": "Lock Period Active", "status": 423, "detail": "The guardian recovery lock period has not elapsed yet." } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanlayer.io/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please contact support with incident ID: inc_1697043000000." } } } } } } } } }, "/v1/passports/:id/recovery/:requestId/guardians/:guardianDid/accept-role": { "post": { "summary": "Accept Guardian Role for Passport Recovery", "description": "In the intricate dance of Human-AI orchestration, ensuring a secure recovery process is paramount. This endpoint allows a guardian to accept their role in the recovery of a passport, downloading an encrypted shard bundle to their device. By acknowledging this responsibility, guardians protect the sanctity of digital identities.", "operationId": "acceptGuardianRole", "tags": [ "Identity", "Recovery" ], "x-code-hash": "02658ab3946ca4e6", "x-generated-at": "2026-04-12T15:57:29.916Z", "responses": { "200": { "description": "Guardian successfully accepted the role and received the encrypted shard.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The unique identifier for the recovery request." }, "passport_did": { "type": "string", "description": "The DID of the passport holder." }, "guardian_did": { "type": "string", "description": "The DID of the guardian acknowledging the shard." }, "shard_index": { "type": "integer", "description": "The index of the shard in the recovery process." }, "encrypted_shard_b64": { "type": "string", "description": "The base64-encoded encrypted shard." }, "ephemeral_public_key_b64": { "type": "string", "description": "The base64-encoded ephemeral public key used for encryption." }, "iv_b64": { "type": "string", "description": "The base64-encoded initialization vector for encryption." }, "delivered_to_device": { "type": "boolean", "description": "Indicates successful delivery of the shard to the device." } }, "required": [ "request_id", "passport_did", "guardian_did", "shard_index", "encrypted_shard_b64", "ephemeral_public_key_b64", "iv_b64", "delivered_to_device" ] }, "examples": { "successful_role_acceptance": { "summary": "Successful Role Acceptance", "description": "A guardian successfully accepts their role and receives the encrypted shard.", "value": { "request_id": "req_12345", "passport_did": "did:human:abc123", "guardian_did": "did:human:guardian456", "shard_index": 1, "encrypted_shard_b64": "VGhpcyBpcyBhbiBlbmNyeXB0ZWQgc2hhcmQ=", "ephemeral_public_key_b64": "RW5jcnlwdGVkIFB1YmxpYyBLZXk=", "iv_b64": "SW5pdCBWZWN0b3I=", "delivered_to_device": true } } } } } }, "401": { "description": "Authentication required for the guardian.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_guardian": { "summary": "Unauthenticated Guardian", "description": "The guardian attempted to accept the role without being authenticated.", "value": { "type": "https://haio.run/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Guardian must be authenticated" } } } } } }, "403": { "description": "Guardian is not authorized for this request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_guardian": { "summary": "Unauthorized Guardian", "description": "The session DID does not match the guardian DID in the path.", "value": { "type": "https://haio.run/errors/authorization-required", "title": "Authorization Error", "status": 403, "detail": "Session DID must match guardian in path" } } } } } }, "404": { "description": "The requested shard was not found for the guardian.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "shard_not_found": { "summary": "Shard Not Found", "description": "The system could not find an encrypted shard for the guardian and request ID provided.", "value": { "type": "https://haio.run/errors/not-found", "title": "Shard Not Found", "status": 404, "detail": "No encrypted shard for this guardian and request." } } } } } }, "422": { "description": "The recovery request cannot be acknowledged due to mismatched data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "recovery_data_mismatch": { "summary": "Recovery Data Mismatch", "description": "The guardian attempted to acknowledge a shard that does not match the passport.", "value": { "type": "https://humanlayer.io/errors/recovery-not-ready", "title": "Cannot Acknowledge Shard", "status": 422, "detail": "Request or shard row does not match this passport." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A server error occurred during the processing of the request.", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred.", "incidentId": "inc_123456789" } } } } } } } } }, "/v1/passports/:id/recovery/:requestId/shard-signal": { "post": { "summary": "Relay Guardian Ciphertext for Recovery", "description": "This endpoint allows a Guardian to post a ciphertext for a device attempting to recover a Passport identity. It plays a crucial role in ensuring that the right credentials are securely relayed, maintaining the integrity and security of identity recovery in the HUMAN platform.", "operationId": "postShardSignal", "tags": [ "Passports", "Recovery" ], "x-code-hash": "adb9c322a1ccf59b", "x-generated-at": "2026-04-13T18:46:22.983Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload_b64": { "type": "string", "description": "Base64-encoded ciphertext for the recovering device." } }, "required": [ "payload_b64" ] }, "examples": { "base64_ciphertext_submission": { "summary": "Base64 Ciphertext Submission", "description": "An example where a Guardian submits the required ciphertext for a recovery process.", "value": { "payload_b64": "c29tZS1lbmNvZGVkLWNpcGhlcnRleHQ=" } } } } } }, "responses": { "201": { "description": "The ciphertext was successfully relayed to the recovering device.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "request_id": { "type": "string", "example": "request-12345" }, "guardian_did": { "type": "string", "example": "did:example:guardian-6789" } } }, "examples": { "successful_relay": { "summary": "Successful Relay", "description": "A successful response indicating the ciphertext was relayed.", "value": { "ok": true, "request_id": "request-12345", "guardian_did": "did:example:guardian-6789" } } } } } }, "400": { "description": "Bad Request due to missing or invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_ciphertext": { "summary": "Missing Ciphertext", "description": "An error response when the payload_b64 field is missing.", "value": { "type": "https://api.human/probs/invalid-input", "title": "Invalid Input", "status": 400, "detail": "payload_b64 is required (ciphertext for recovering device)", "errors": [ { "field": "payload_b64", "code": "REQUIRED_FIELD_MISSING", "message": "payload_b64 is required", "expected": "string", "received": "missing" } ] } } } } } }, "401": { "description": "Unauthorized request when the session holder is not a guardian.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_guardian": { "summary": "Unauthorized Guardian", "description": "An error response when the session does not belong to an active guardian.", "value": { "type": "https://api.human/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Session holder is not an active guardian for this policy" } } } } } }, "403": { "description": "Forbidden access due to incorrect completion mode.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "incorrect_completion_mode": { "summary": "Incorrect Completion Mode", "description": "An error when the request completion mode is not 'client_proof'.", "value": { "type": "https://api.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "shard-signal is only valid when completion_mode is client_proof", "errors": [ { "field": "request", "code": "WRONG_COMPLETION_MODE", "message": "shard-signal is only valid when completion_mode is client_proof", "expected": "client_proof", "received": "another_mode" } ] } } } } } }, "404": { "description": "Not Found error when the recovery request does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "recovery_request_not_found": { "summary": "Recovery Request Not Found", "description": "An error response when the specified recovery request ID does not exist.", "value": { "type": "https://api.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "Recovery request not found for requestId: request-12345" } } } } } }, "500": { "description": "Internal Server Error if an unexpected condition was encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A response indicating an internal server error occurred.", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID inc_1698765432." } } } } } } } }, "get": { "summary": "Retrieve Passport Recovery Shard Signals", "description": "In a world where identity recovery is paramount, this endpoint empowers the passport holder to retrieve shard signals vital for reconstructing their cryptographic identity. It ensures the safe delivery of pending ciphertext payloads, marking them as received.", "operationId": "getPassportRecoveryShardSignal", "tags": [ "Passport", "Recovery" ], "x-code-hash": "06865217972cc43d", "x-generated-at": "2026-04-13T18:46:39.504Z", "responses": { "200": { "description": "Successfully retrieved pending shard signals for the passport recovery process.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The ID of the recovery request." }, "signals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the shard signal." }, "guardian_did": { "type": "string", "description": "Decentralized Identifier of the guardian." }, "shard_index": { "type": "integer", "description": "Index of the shard in the recovery process." }, "payload_b64": { "type": "string", "description": "Base64 encoded payload of the shard signal." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the shard signal was created." } }, "required": [ "id", "guardian_did", "shard_index", "payload_b64", "created_at" ] } } }, "required": [ "request_id", "signals" ] }, "examples": { "successful_retrieval_example": { "summary": "Successful Retrieval Example", "description": "Shows a successful retrieval of shard signals.", "value": { "request_id": "req-123456789", "signals": [ { "id": "signal-1", "guardian_did": "did:human:guardian123", "shard_index": 0, "payload_b64": "SGVsbG8gV29ybGQ=", "created_at": "2023-10-01T12:34:56Z" } ] } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_completion_mode": { "summary": "Invalid Completion Mode", "description": "Occurs when attempting to fetch shard signals with an unsupported completion mode.", "value": { "type": "https://humanprotocol.example.com/errors/invalid-completion-mode", "title": "Invalid Completion Mode", "status": 400, "detail": "shard-signal is only valid when completion_mode is client_proof", "errors": [ { "field": "request", "code": "WRONG_COMPLETION_MODE", "message": "Invalid completion mode provided. Expected 'client_proof'." } ] } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Occurs when the session does not belong to the passport holder attempting recovery.", "value": { "type": "https://humanprotocol.example.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Session must be the recovering passport holder." } } } } } }, "403": { "description": "Forbidden action for the current session.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Occurs when an action is attempted without proper permissions.", "value": { "type": "https://humanprotocol.example.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Recovery request or shard signal not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "recovery_request_not_found": { "summary": "Recovery Request Not Found", "description": "Occurs when the specified recovery request ID does not exist.", "value": { "type": "https://humanprotocol.example.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "Recovery request with ID 'req-123456789' was not found." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "Occurs when an unexpected error happens on the server.", "value": { "type": "https://humanprotocol.example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/:did/consent-policies": { "post": { "summary": "Create a Consent Policy for a Passport", "description": "This endpoint allows a passport holder to define consent policies that dictate how their data can be accessed. By automating approval or denial of specific claims, users maintain control over their digital identity while reducing manual intervention.", "operationId": "createConsentPolicy", "tags": [ "Passport", "Consent" ], "x-code-hash": "3c60012280964113", "x-generated-at": "2026-04-12T20:26:49.681Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claim_names": { "type": "array", "items": { "type": "string" }, "description": "A non-empty array of claims that this policy applies to" }, "action": { "type": "string", "enum": [ "auto_approve", "auto_deny" ], "description": "The action to take when the claims match this policy" }, "requester_did_pattern": { "type": "string", "description": "An optional pattern to match requesters by their DID" }, "purpose_pattern": { "type": "string", "description": "An optional pattern describing the purpose context" }, "priority": { "type": "integer", "description": "The priority of this policy, with lower numbers indicating higher priority" } }, "required": [ "claim_names", "action" ] }, "examples": { "basic_consent_policy": { "summary": "Basic Consent Policy", "description": "Creates a policy to auto-approve access for specific claims", "value": { "claim_names": [ "email", "profile" ], "action": "auto_approve", "requester_did_pattern": "did:human:org:test", "purpose_pattern": "data:access", "priority": 50 } } } } } }, "responses": { "201": { "description": "Consent policy successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the newly created policy" }, "passport_did": { "type": "string", "description": "The DID of the passport this policy is associated with" }, "requester_did_pattern": { "type": "string", "description": "The pattern for matching requester DIDs" }, "claim_names": { "type": "array", "items": { "type": "string" }, "description": "Claims that this policy applies to" }, "purpose_pattern": { "type": "string", "description": "Pattern describing the context of purpose" }, "action": { "type": "string", "description": "Action taken when claims match the policy" }, "priority": { "type": "integer", "description": "Priority of this policy" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the policy was created" } } }, "examples": { "default": { "summary": "Example", "value": { "id": "policy-123", "passport_did": "did:human:example:123456", "requester_did_pattern": "did:human:org:test", "claim_names": [ "email", "profile" ], "purpose_pattern": "data:access", "action": "auto_approve", "priority": 50, "created_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Bad Request due to invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-input", "title": "Invalid Request Body", "status": 400, "detail": "claim_names must be a non-empty array of strings", "errors": [ { "field": "claim_names", "message": "claim_names must be a non-empty array of strings" } ] } } } } } }, "401": { "description": "Unauthorized request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required to create a consent policy." } } } } } }, "403": { "description": "Forbidden due to authorization constraints", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authorization-error", "title": "Authorization Error", "status": 403, "detail": "Only the subject passport may manage consent policies." } } } } } }, "404": { "description": "Passport not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Passport Not Found", "status": 404, "detail": "No passport found with the DID did:human:example:123456." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please retry the request." } } } } } } } }, "get": { "summary": "Retrieve consent policies for a passport", "description": "Dive into the intricate world of consent management with HUMAN's Passport Consent Policies. This endpoint allows you to explore the nuanced policies that govern what claims and actions are automatically approved or denied for a specific passport. Empowering users and organizations, it ensures transparency and control over data sharing.", "operationId": "getConsentPolicies", "tags": [ "Passport", "Consent" ], "x-code-hash": "97c5cd5740b0ba73", "x-generated-at": "2026-04-12T20:27:02.237Z", "responses": { "200": { "description": "Successfully retrieved the list of consent policies associated with the specified passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "passport_did": { "type": "string" }, "requester_did_pattern": { "type": [ "string", "null" ] }, "claim_names": { "type": "array", "items": { "type": "string" } }, "purpose_pattern": { "type": [ "string", "null" ] }, "action": { "type": "string", "enum": [ "auto_approve", "auto_deny" ] }, "priority": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "passport_did", "claim_names", "action", "priority", "created_at" ] } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorFields", "hasMore" ] }, "examples": { "acme_corp_retrieving_consent_policies": { "summary": "Acme Corp retrieving consent policies", "description": "Acme Corp is reviewing its consent policies for compliance and data governance.", "value": { "data": [ { "id": "1234-abcd", "passport_did": "did:human:acme123", "requester_did_pattern": null, "claim_names": [ "email", "name" ], "purpose_pattern": "data processing", "action": "auto_approve", "priority": 1, "created_at": "2023-06-01T12:00:00Z" } ], "limit": 10, "cursorFields": [ "created_at", "id" ], "hasMore": false } } } } } }, "400": { "description": "Invalid request parameters, such as malformed DID or pagination values.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_did_example": { "summary": "Malformed DID example", "value": { "type": "https://api.human/probs/invalid-request", "title": "Invalid Request Parameters", "status": 400, "detail": "The DID parameter is malformed. Ensure it follows the 'did:human:' format.", "errors": [ "The DID must start with 'did:human:'" ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_authentication_provided": { "summary": "No authentication provided", "value": { "type": "https://api.human/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to access consent policies. Please provide valid authentication credentials." } } } } } }, "403": { "description": "Authorization error when attempting to access policies not belonging to the authenticated DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_attempt": { "summary": "Unauthorized access attempt", "value": { "type": "https://api.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Access denied. Only the subject passport may list consent policies." } } } } } }, "404": { "description": "The specified passport DID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport not found", "value": { "type": "https://api.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "The passport with DID 'did:human:unknown' was not found. Verify the DID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while retrieving consent policies. Please try again later." } } } } } } } } }, "/v1/passports/:did/consent-policies/:policyId": { "delete": { "summary": "Remove a user's consent policy", "description": "In the HUMAN protocol, consent is crucial. This endpoint allows the owner of a cryptographic identity, or Passport, to remove a consent policy they've previously granted. It's a step towards empowering users by giving them control over their personal data and how it's shared.", "operationId": "deleteConsentPolicy", "tags": [ "Identity Management", "Consent" ], "x-code-hash": "08096c6547a8c888", "x-generated-at": "2026-04-12T20:27:12.254Z", "responses": { "200": { "description": "Consent policy successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "ok", "id" ] }, "examples": { "successful_deletion": { "summary": "Successful Deletion", "description": "The consent policy with ID 'policy-1234-5678' was successfully removed.", "value": { "ok": true, "id": "policy-1234-5678" } } } } } }, "400": { "description": "Bad request due to malformed DID or policyId", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_did": { "summary": "Malformed DID", "description": "The provided DID does not conform to the expected format.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The DID provided is malformed. Please ensure it starts with 'did:human:' and follows the correct format." } } } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "No authentication was provided in the request.", "value": { "type": "https://humanprotocol.org/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Please provide valid authentication credentials to access this endpoint." } } } } } }, "403": { "description": "Forbidden access due to authorization failure", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The authenticated user is not authorized to delete this consent policy.", "value": { "type": "https://humanprotocol.org/errors/authorization-failure", "title": "Authorization Failure", "status": 403, "detail": "You are not authorized to delete this consent policy. Only the owner of the passport can perform this action." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "consent_policy_not_found": { "summary": "Consent Policy Not Found", "description": "The consent policy specified by the policyId does not exist.", "value": { "type": "https://humanprotocol.org/errors/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The consent policy with the specified ID was not found. Please verify the policyId and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected failure", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support with incident ID: inc_1698771200000." } } } } } } } } }, "/v1/passports/:did/devices/revocation-snapshot": { "get": { "summary": "Fetch Passport Device Revocation Snapshot", "description": "Retrieve a cryptographic snapshot of revoked devices for a given Human Passport. This endpoint empowers offline verifiers by providing them with a cached list of device IDs that have been revoked, ensuring the integrity and validity of AI orchestrations.", "operationId": "getPassportDeviceRevocationSnapshot", "tags": [ "Identity", "Revocation" ], "x-code-hash": "a20289669582c159", "x-generated-at": "2026-04-12T20:27:21.751Z", "responses": { "200": { "description": "Successfully retrieved the revocation snapshot for the specified DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "The Decentralized Identifier (DID) of the passport." }, "revoked_device_ids": { "type": "array", "items": { "type": "string" }, "description": "List of IDs of devices that have been revoked." }, "snapshot_at": { "type": "string", "format": "date-time", "description": "Timestamp when the snapshot was taken." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration timestamp for the cached snapshot." }, "content_sha256": { "type": "string", "description": "SHA-256 hash of the revoked device IDs list." }, "hub_public_key": { "type": "string", "description": "Base64Url encoded public key of the revocation hub." }, "hub_signature": { "type": "string", "description": "Signature of the canonical revocation message." }, "canonical_message": { "type": "string", "description": "Canonical form of the revocation snapshot message." } } }, "examples": { "successful_revocation_snapshot": { "summary": "Successful Revocation Snapshot", "description": "Fetching the revocation snapshot for an active passport.", "value": { "passport_did": "did:human:123456789abcdefghi", "revoked_device_ids": [ "device1", "device2", "device3" ], "snapshot_at": "2023-10-15T12:00:00.000Z", "expires_at": "2023-10-16T12:00:00.000Z", "content_sha256": "5d41402abc4b2a76b9719d911017c592", "hub_public_key": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD...", "hub_signature": "MEUCIQDy9...aR+Q==", "canonical_message": "revocation-snapshot|did:human:123456789abcdefghi|2023-10-15T12:00:00.000Z|5d41402abc4b2a76b9719d911017c592" } } } } } }, "404": { "description": "Passport not found or not active.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "description": "The provided DID does not correspond to an active passport.", "value": { "type": "https://api.human/probs/passport-not-found", "title": "Passport Not Found", "status": 404, "detail": "The passport with DID 'did:human:123456789abcdefghi' does not exist or is not active. Verify the DID and try again." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred within the server.", "value": { "type": "https://api.human/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request. Please try again later." } } } } } } } } }, "/v1/provenance/chain/:decisionId": { "get": { "summary": "Retrieve decision audit chain details", "description": "Explore the intricate web of decisions with this endpoint, which unveils the comprehensive audit trail of a specific decision. By fetching the materialized decision chain, organizations can ensure accountability and transparency in their decision-making processes, paving the way for improved governance and trust.", "operationId": "getProvenanceChainDetails", "tags": [ "Provenance", "Audit" ], "x-code-hash": "0f697854f3fe46fa", "x-generated-at": "2026-04-13T19:56:00.280Z", "responses": { "200": { "description": "Successfully retrieved the decision and its associated events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "object", "properties": { "id": { "type": "string" }, "provenance_chain_id": { "type": "string" }, "source_event_hashes": { "type": "array", "items": { "type": "string" } }, "source_governed_event_ids": { "type": "array", "items": { "type": "string" } }, "workflow_id": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "org_did": { "type": "string" }, "decision_type": { "type": "string" }, "actor_passport_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "metadata_json": { "type": "object" }, "session_id": { "type": "string" } } } } } }, "examples": { "successful_retrieval_of_a_decision_chain": { "summary": "Successful retrieval of a decision chain", "value": { "decision": { "id": "dec123", "provenance_chain_id": "chain789", "source_event_hashes": [ "hash1", "hash2" ], "source_governed_event_ids": [ "gid456", "gid789" ], "workflow_id": "wf001", "title": "Approval of Q1 Budget", "updated_at": "2023-10-01T12:34:56Z" }, "events": [ { "id": "event001", "org_did": "did:example:acme", "decision_type": "approval", "actor_passport_id": "passport123", "timestamp": "2023-10-01T09:15:00Z", "metadata_json": { "key": "value" }, "session_id": "session789" } ] } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_decisionid_parameter": { "summary": "Missing decisionId parameter", "value": { "type": "https://haio.run/errors/validation", "title": "Missing decisionId", "status": 400, "detail": "decisionId path parameter is required.", "errors": [] } }, "missing_orgdid_query_parameter": { "summary": "Missing orgDid query parameter", "value": { "type": "https://haio.run/errors/validation", "title": "Validation Error", "status": 400, "detail": "One or more validation errors occurred.", "errors": [ { "field": "org_did", "code": "REQUIRED_QUERY_PARAM", "message": "org_did query param is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_token": { "summary": "Missing authentication token", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication token is missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found for the given decisionId.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "decision_not_found": { "summary": "Decision not found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No decision found with the given ID." } } } } } }, "500": { "description": "Internal server error, indicating an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "value": { "type": "https://haio.run/errors/server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/provenance/explain/:decisionId": { "post": { "summary": "Retrieve structured decision explanation", "description": "Unlock the story behind a decision with detailed provenance and routing signals. This endpoint offers a deep dive into the decision-making process, providing insights into the integrity and policy conformance of AI-augmented human actions.", "operationId": "postProvenanceExplain", "tags": [ "Provenance", "Audit" ], "x-code-hash": "062daf0136163a2c", "x-generated-at": "2026-04-13T19:56:22.379Z", "responses": { "200": { "description": "Successfully retrieved decision explanation", "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_id": { "type": "string", "description": "Unique identifier for the decision" }, "summary": { "type": "string", "description": "A brief summary of the decision" }, "policy_version_snapshot": { "type": "string", "description": "Snapshot of the policy version applied at decision time" }, "escalation_occurred": { "type": "boolean", "description": "Indicates if an escalation was triggered" }, "override_occurred": { "type": "boolean", "description": "Indicates if an override was applied" }, "integrity_status": { "type": "string", "description": "Current integrity status of the decision" }, "routing_signals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Event identifier" }, "confidence": { "type": "number", "format": "float", "description": "Confidence level of the routing decision" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of the event creation" }, "payload": { "type": "object", "description": "Additional metadata associated with the event" } } } }, "citations": { "type": "array", "items": { "type": "object", "properties": { "decision_id": { "type": "string", "description": "Reference to the decision ID" }, "claim": { "type": "string", "description": "Description of the citation" }, "event_id": { "type": [ "string", "null" ], "description": "Associated event ID, if any" } } } } } }, "examples": { "successful_explanation_retrieval": { "summary": "Successful Explanation Retrieval", "description": "An example showing decision explanation for an AI decision.", "value": { "decision_id": "dec123", "summary": "AI decision for invoice processing", "policy_version_snapshot": "v2023.10", "escalation_occurred": false, "override_occurred": true, "integrity_status": "verified", "routing_signals": [ { "id": "event456", "confidence": 0.95, "created_at": "2023-10-23T10:00:00Z", "payload": { "workflow_id": "wf789", "execution_id": "exec101112" } } ], "citations": [ { "decision_id": "dec123", "claim": "Materialized decision row", "event_id": null } ] } } } } } }, "400": { "description": "Invalid request due to missing query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_query_parameter": { "summary": "Missing Query Parameter", "description": "Occurs when 'org_did' query parameter is not provided.", "value": { "type": "https://example.com/errors/missing-query-param", "title": "Missing Required Query Parameter", "status": 400, "detail": "The query parameter 'org_did' is required but was not provided.", "errors": [ { "field": "org_did", "code": "REQUIRED_QUERY_PARAM", "message": "org_did query param is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication failure due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "description": "The request fails due to invalid authentication credentials.", "value": { "type": "https://example.com/errors/invalid-auth", "title": "Invalid Authentication", "status": 401, "detail": "Authentication failed due to invalid credentials. Please verify your API key or token." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have the necessary permissions to access the resource.", "value": { "type": "https://example.com/errors/forbidden", "title": "Access Forbidden", "status": 403, "detail": "You do not have the required permissions to access this resource. Contact your administrator to request access." } } } } } }, "404": { "description": "The specified decision was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "decision_not_found": { "summary": "Decision Not Found", "description": "The decisionId provided does not correspond to any existing records.", "value": { "type": "https://example.com/errors/not-found", "title": "Decision Not Found", "status": 404, "detail": "No decision with the ID 'dec123' was found. Please verify the decision ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server error occurred while processing the request.", "value": { "type": "https://example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/audit/decisions": { "get": { "summary": "Retrieve audit decisions within an organization", "description": "Dive into the decision-making process of your organization with the power of audit insights. Understanding who decided what and why is crucial for transparent operations and compliance. This endpoint equips organizations with the ability to pull detailed decision records, ensuring accountability and traceability.", "operationId": "getAuditDecisions", "tags": [ "Audit", "Compliance" ], "x-code-hash": "12bb5f3a493ef17c", "x-generated-at": "2026-04-13T19:57:33.011Z", "responses": { "200": { "description": "A paginated list of audit decisions for the specified organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "workflow_id": { "type": "string" }, "org_did": { "type": "string" }, "decision_type": { "type": "string" }, "status": { "type": "string" }, "risk_level": { "type": "string" }, "policy_checks": { "type": "array", "items": { "type": "object" } }, "escalation_occurred": { "type": "boolean" }, "override_occurred": { "type": "boolean" }, "provenance_chain_id": { "type": "string" }, "actors": { "type": "array", "items": { "type": "object" } }, "graph_execution_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "workflow_id", "org_did", "decision_type", "status", "risk_level", "provenance_chain_id", "created_at", "updated_at" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" }, "redacted_count": { "type": "integer" }, "redacted_reason": { "type": "string" } }, "required": [ "data", "limit", "cursorField", "hasMore", "redacted_count", "redacted_reason" ] }, "examples": { "audit_decision_retrieval_example": { "summary": "Audit decision retrieval example", "description": "Retrieve decisions for the 'acme' organization, focusing on a specific workflow within a date range.", "value": { "data": [ { "id": "decision123", "title": "Approval of Invoice #987", "workflow_id": "workflow456", "org_did": "did:human:acme", "decision_type": "approval", "status": "completed", "risk_level": "low", "policy_checks": [], "escalation_occurred": false, "override_occurred": false, "provenance_chain_id": "chain789", "actors": [], "graph_execution_id": "exec101", "created_at": "2023-10-01T10:00:00Z", "updated_at": "2023-10-02T12:00:00Z" } ], "limit": 10, "cursorField": "updated_at", "hasMore": false, "redacted_count": 0, "redacted_reason": "" } } } } } }, "400": { "description": "Invalid request due to malformed parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_parameter": { "summary": "Missing orgDid parameter", "description": "The client did not provide the required 'orgDid' parameter.", "value": { "type": "https://haio.run/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "orgDid is required", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "403": { "description": "Forbidden due to overly broad audit scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "audit_scope_too_broad": { "summary": "Audit scope too broad", "description": "The query attempted to retrieve too many records without proper constraints.", "value": { "type": "https://haio.run/errors/forbidden", "title": "Audit scope too broad", "status": 403, "detail": "actorPassportId requires caseId, workflowId, or a bounded time range." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_connection_failure": { "summary": "Database connection failure", "description": "A backend database error prevented the request from completing.", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } } }, "/v1/audit/decisions/:id/chain": { "get": { "summary": "Retrieve Audit Decision Chain Details", "description": "Uncover the provenance of decisions by exploring their audit trail within the HUMAN ecosystem. This endpoint serves as a gateway to transparency, allowing organizations to verify the integrity and source of decisions made by their systems.", "operationId": "getAuditDecisionChain", "tags": [ "Audit", "Provenance" ], "x-code-hash": "ef857bbed21f50fe", "x-generated-at": "2026-04-13T19:58:18.639Z", "responses": { "200": { "description": "Returns the provenance chain details for a specific audit decision, including its unique chain integrity hash.", "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_id": { "type": "string", "description": "The unique identifier of the decision." }, "provenance_chain_id": { "type": "string", "description": "The identifier of the provenance chain associated with the decision." }, "source_event_hashes": { "type": "array", "items": { "type": "string" }, "description": "Hashes of the source events that contributed to the decision." }, "chain_integrity": { "type": "string", "description": "SHA-256 hash representing the chain integrity, ensuring the decision's source events remain untampered." } } }, "examples": { "successful_retrieval_of_decision_chain": { "summary": "Successful Retrieval of Decision Chain", "description": "An organization retrieves the chain details of a decision to audit its origin and verify its integrity.", "value": { "decision_id": "123e4567-e89b-12d3-a456-426614174000", "provenance_chain_id": "chain-abc123", "source_event_hashes": [ "hash1abcd1234", "hash2efgh5678" ], "chain_integrity": "b1946ac92492d2347c6235b4d2611184" } } } } } }, "400": { "description": "The request is malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_parameter": { "summary": "Missing orgDid Parameter", "value": { "type": "https://haio.run/errors/validation-error", "title": "Bad Request", "status": 400, "detail": "The request is missing required query parameters.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access requires valid authentication credentials." } } } } } }, "403": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view this decision chain." } } } } } }, "404": { "description": "The specified decision ID could not be found within the organization's records.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "decision_not_found": { "summary": "Decision Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "Decision not found." } } } } } }, "500": { "description": "An error occurred on the server while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/audit/decisions/:id/explain": { "get": { "summary": "Retrieve and explain an audit decision", "description": "Unravel the intricacies of a specific audit decision by fetching its detailed explanation. This endpoint empowers organizations to understand the outcomes of their decision-making processes, ensuring transparency and accountability in the orchestration of human and AI interactions.", "operationId": "getAuditDecisionExplanation", "tags": [ "Audit", "Decisions" ], "x-code-hash": "43f17810b07542f7", "x-generated-at": "2026-04-13T19:58:36.422Z", "responses": { "200": { "description": "Successfully retrieved the audit decision explanation", "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_id": { "type": "string", "description": "The unique identifier of the decision" }, "summary": { "type": "string", "description": "A brief summary of the decision" }, "policy_version_snapshot": { "type": "string", "description": "The policy version in place during the decision" }, "escalation_occurred": { "type": "boolean", "description": "Indicates if an escalation occurred" }, "override_occurred": { "type": "boolean", "description": "Indicates if an override occurred" }, "integrity_status": { "type": "string", "description": "The integrity status of the decision" }, "evidence_status": { "type": "string", "enum": [ "complete" ], "description": "The completeness status of the evidence" } } }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "description": "An example response for a successful audit decision explanation retrieval.", "value": { "decision_id": "12345", "summary": "Approved invoice processing", "policy_version_snapshot": "v2023.10.01", "escalation_occurred": false, "override_occurred": true, "integrity_status": "verified", "evidence_status": "complete" } } } } } }, "400": { "description": "Bad request due to missing required parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_query_parameter": { "summary": "Missing orgDid Query Parameter", "description": "The request was missing a required 'orgDid' query parameter.", "value": { "type": "https://haio.run/errors/validation", "title": "Validation Error", "status": 400, "detail": "The request is missing required query parameters.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "description": "The request failed due to invalid authentication credentials.", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Invalid authentication credentials provided." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have the necessary permissions to access this resource.", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to view this decision." } } } } } }, "404": { "description": "Decision not found for the given ID and orgDid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "decision_not_found": { "summary": "Decision Not Found", "description": "No decision was found matching the provided ID and orgDid.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "Decision not found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "The server encountered an unexpected condition.", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/audit/overrides": { "get": { "summary": "Retrieve audit override events history", "description": "Dive into the past and explore audit override events for your organization. This endpoint offers a window into the decisions that altered the usual course of operations, enabling transparency and accountability. Use it to track changes, understand discrepancies, and ensure compliance with established protocols.", "operationId": "getAuditOverrides", "tags": [ "Audit", "Compliance" ], "x-code-hash": "ad17ca9d16b43991", "x-generated-at": "2026-04-13T19:59:00.688Z", "responses": { "200": { "description": "Successfully retrieved a list of audit override events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "override-123" }, "occurred_at": { "type": "string", "format": "date-time", "example": "2023-10-01T12:34:56Z" }, "description": { "type": "string", "example": "Override for invoice processing" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "id", "occurred_at", "description" ] } }, "limit": { "type": "integer", "example": 10 }, "cursorField": { "type": "string", "example": "occurred_at" }, "hasMore": { "type": "boolean", "example": true }, "redacted_count": { "type": "integer", "example": 0 }, "redacted_reason": { "type": "string", "example": "" } }, "required": [ "data", "limit", "cursorField", "hasMore", "redacted_count", "redacted_reason" ] }, "examples": { "successful_retrieval_of_audit_overrides": { "summary": "Successful retrieval of audit overrides", "description": "Shows a paginated list of past override events for the organization.", "value": { "data": [ { "id": "override-123", "occurred_at": "2023-10-01T12:34:56Z", "description": "Override for invoice processing", "details": { "reason": "Manual review required" } } ], "limit": 10, "cursorField": "occurred_at", "hasMore": true, "redacted_count": 0, "redacted_reason": "" } } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_parameter": { "summary": "Missing orgDid parameter", "description": "The request lacks the necessary orgDid parameter.", "value": { "type": "https://human-protocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request is missing required parameters.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_token": { "summary": "Missing authentication token", "description": "The request is missing an authentication token.", "value": { "type": "https://human-protocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_without_sufficient_permissions": { "summary": "Access without sufficient permissions", "description": "The user attempts to access a resource without the necessary permissions.", "value": { "type": "https://human-protocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found due to invalid endpoint or missing data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_endpoint": { "summary": "Invalid endpoint", "description": "The request was made to an endpoint that does not exist.", "value": { "type": "https://human-protocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_encountered_unexpected_condition": { "summary": "Server encountered unexpected condition", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://human-protocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/audit/attestations/missing": { "post": { "summary": "Identify Missing Audit Attestations", "description": "In the vast landscape of audit trails, some stones are left unturned. This endpoint shines a light on the gaps in your audit attestations, ensuring every decision is verified. By identifying where attestations are missing, organizations can maintain integrity and trust in their processes.", "operationId": "postAuditAttestationsMissing", "tags": [ "Audit", "Attestations" ], "x-code-hash": "820224a5937b77fe", "x-generated-at": "2026-04-13T19:59:18.192Z", "responses": { "200": { "description": "Returns a list of missing attestations and the count of decisions scanned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "decision_id": { "type": "string", "description": "The unique identifier of the audit decision." }, "missing": { "type": "boolean", "description": "Indicator that the attestation is missing." } } } }, "scanned_decisions": { "type": "integer", "description": "Total number of audit decisions scanned." }, "missing_count": { "type": "integer", "description": "Number of missing attestations found." } } }, "examples": { "missing_attestations_example": { "summary": "Missing Attestations Example", "description": "An example response where certain attestations are missing.", "value": { "data": [ { "decision_id": "dec123", "missing": true }, { "decision_id": "dec456", "missing": true } ], "scanned_decisions": 150, "missing_count": 2 } } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_error": { "summary": "Missing orgDid Error", "description": "A 400 error when the orgDid parameter is missing.", "value": { "type": "/errors/validation", "title": "Validation Error", "status": 400, "detail": "orgDid is required", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_error": { "summary": "Unauthorized Error", "description": "An example of a 401 error due to invalid authentication.", "value": { "type": "/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Invalid API key or token." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_error": { "summary": "Forbidden Error", "description": "A 403 error due to lack of permissions.", "value": { "type": "/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_error": { "summary": "Not Found Error", "description": "A 404 error when the resource cannot be located.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A 500 error due to unforeseen server issues.", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/audit/bundles": { "post": { "summary": "Create and store audit evidence bundles", "description": "This endpoint is a crucial part of maintaining transparency and trust within the HUMAN ecosystem. It enables organizations to submit decision-making evidence, ensuring accountability and providing a clear audit trail. By storing these bundles, it supports robust AI governance and compliance efforts.", "operationId": "createAuditEvidenceBundle", "tags": [ "Audit", "Compliance" ], "x-code-hash": "71d562db4dff731b", "x-generated-at": "2026-04-13T19:59:39.274Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_ids": { "type": "array", "items": { "type": "string" }, "description": "List of decision IDs related to the evidence bundle." }, "format": { "type": "string", "description": "Format in which the evidence bundle should be stored, defaults to 'ops'." }, "generated_by": { "type": "string", "description": "Identifier for the entity generating the evidence, defaults to the agent audit API if not provided." } }, "required": [ "decision_ids" ] }, "examples": { "standard_audit_bundle": { "summary": "Standard Audit Bundle", "description": "A typical example where an organization submits an evidence bundle for multiple decisions.", "value": { "decision_ids": [ "dec-12345", "dec-67890" ], "format": "json", "generated_by": "acmeCorpAuditTool" } } } } } }, "responses": { "201": { "description": "The evidence bundle was successfully created and stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle_id": { "type": "string", "description": "Identifier for the created evidence bundle." }, "status": { "type": "string", "description": "Status of the bundle creation." } } }, "examples": { "default": { "summary": "Example", "value": { "bundle_id": "bundle-98765", "status": "created" } } } } } }, "400": { "description": "The request body is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Request parameters are incorrect.", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "JSON body required", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication is required and has failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/probs/authentication-failed", "title": "Authentication Failed", "status": 401, "detail": "Valid authentication credentials are required." } } } } } }, "403": { "description": "The user does not have the necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/probs/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "The specified resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource was not found." } } } } } }, "500": { "description": "An unexpected error has occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/audit/chains/compare": { "post": { "summary": "Compare Two Audit Decision Chains", "description": "Dive deep into decision-making by comparing two audit decision chains. Unveil the differences in policies, workflows, and overrides to ensure your organization’s audits are transparent and accountable.", "operationId": "compareAuditDecisionChains", "tags": [ "Audit", "Comparison" ], "x-code-hash": "67978902c61bdff6", "x-generated-at": "2026-04-13T19:59:58.510Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_id_a": { "type": "string", "description": "Unique identifier for the first decision" }, "decision_id_b": { "type": "string", "description": "Unique identifier for the second decision" } }, "required": [ "decision_id_a", "decision_id_b" ] }, "examples": { "compare_two_decisions": { "summary": "Compare Two Decisions", "description": "Compares two decisions to identify changes in policy versions and overrides.", "value": { "decision_id_a": "dec123", "decision_id_b": "dec456" } } } } } }, "responses": { "200": { "description": "Successfully returns the comparison results between two audit decisions", "content": { "application/json": { "schema": { "type": "object", "properties": { "a": { "type": "object", "description": "Details of the first decision", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "workflow_id": { "type": "string" }, "org_did": { "type": "string" }, "policy_version_snapshot": { "type": "string" }, "override_occurred": { "type": "boolean" }, "escalation_occurred": { "type": "boolean" } } }, "b": { "type": "object", "description": "Details of the second decision", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "workflow_id": { "type": "string" }, "org_did": { "type": "string" }, "policy_version_snapshot": { "type": "string" }, "override_occurred": { "type": "boolean" }, "escalation_occurred": { "type": "boolean" } } }, "diff": { "type": "object", "description": "Differences between the two decisions", "properties": { "title_changed": { "type": "boolean" }, "policy_version_changed": { "type": "boolean" }, "override_flag_changed": { "type": "boolean" }, "workflow_changed": { "type": "boolean" } } } } }, "examples": { "successful_comparison": { "summary": "Successful Comparison", "value": { "a": { "id": "dec123", "title": "Q3 Compliance Audit", "workflow_id": "wf789", "org_did": "did:example:acme", "policy_version_snapshot": "v1.0", "override_occurred": false, "escalation_occurred": false }, "b": { "id": "dec456", "title": "Q3 Compliance Audit Revised", "workflow_id": "wf789", "org_did": "did:example:acme", "policy_version_snapshot": "v1.1", "override_occurred": true, "escalation_occurred": false }, "diff": { "title_changed": true, "policy_version_changed": true, "override_flag_changed": true, "workflow_changed": false } } } } } } }, "400": { "description": "Bad Request due to missing or invalid fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_fields": { "summary": "Missing Fields", "value": { "type": "https://haio.run/errors/validation", "title": "Missing fields", "status": 400, "detail": "orgDid query param, decision_id_a, decision_id_b required." } } } } } }, "401": { "description": "Unauthorized: Authentication is required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "Forbidden: User does not have permission", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://haio.run/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not Found: One or both decisions not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "decision_not_found": { "summary": "Decision Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The decision with the given ID could not be found." } } } } } }, "500": { "description": "Internal Server Error: Unexpected issue on the server", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://haio.run/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } } }, "/v1/audit/subscribe": { "post": { "summary": "Subscribe to audit event notifications", "description": "In the pursuit of seamless orchestration, this endpoint was envisioned to allow subscribers to receive notifications of audit events. However, this feature is currently unimplemented. For now, it serves as a gentle reminder to use the POST /v1/webhooks/subscriptions endpoint, where audit event types can be specified for notifications. Stay tuned as the HUMAN platform evolves to support more intricate functionalities.", "operationId": "subscribeAuditEventNotifications", "tags": [ "Audit", "Notifications" ], "x-code-hash": "24a6fe02f8b13a0d", "x-generated-at": "2026-04-13T20:00:12.947Z", "responses": { "501": { "description": "This feature is not implemented. Redirect users to the correct endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/control-plane/audit/decisions/:id": { "get": { "summary": "Retrieve decision audit by ID", "description": "Dive into the depths of decision-making with the HUMAN platform's decision audit retrieval. This endpoint lets you explore the intricate web of decisions made within your organization, ensuring transparency and traceability in a world increasingly driven by AI and human collaboration. Whether you are validating an audit grant or simply accessing your own decision history, this endpoint guarantees that every decision is accounted for.", "operationId": "getDecisionAuditById", "tags": [ "Audit", "Decisions" ], "x-code-hash": "736ac9e681b5b558", "x-generated-at": "2026-04-14T23:29:23.139Z", "responses": { "200": { "description": "Successfully retrieved the decision audit details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the decision." }, "title": { "type": "string", "description": "Title of the decision." }, "workflow_id": { "type": "string", "description": "Associated workflow ID." }, "org_did": { "type": "string", "description": "Organization DID for the decision." }, "decision_type": { "type": "string", "description": "Type of decision made." }, "status": { "type": "string", "description": "Current status of the decision." }, "risk_level": { "type": "string", "description": "Risk level associated with the decision." }, "policy_checks": { "type": "array", "items": { "type": "object" }, "description": "List of policy checks involved." }, "escalation_occurred": { "type": "boolean", "description": "Indicates if any escalation occurred." }, "override_occurred": { "type": "boolean", "description": "Indicates if any override occurred." }, "provenance_chain_id": { "type": "string", "description": "ID of the provenance chain for tracking." }, "actors": { "type": "array", "items": { "type": "object" }, "description": "Actors involved in the decision." }, "graph_execution_id": { "type": "string", "description": "Execution ID for the capability graph." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the decision was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the decision was last updated." }, "escalation_events": { "type": "array", "items": { "type": "object" }, "description": "List of escalation events for the decision." }, "override_events": { "type": "array", "items": { "type": "object" }, "description": "List of override events for the decision." }, "redacted_count": { "type": "integer", "description": "Count of redacted entries." }, "redacted_reason": { "type": "string", "description": "Reason for redaction, if any." } } }, "examples": { "successful_retrieval_of_decision_audit": { "summary": "Successful retrieval of decision audit", "description": "A comprehensive audit of a decision within the 'acme' organization, showcasing the decision's origins and lifecycle.", "value": { "id": "dec-12345", "title": "Approve Invoice Payment", "workflow_id": "wf-67890", "org_did": "did:human:acme", "decision_type": "Approval", "status": "Completed", "risk_level": "Low", "policy_checks": [ { "check_id": "chk-001", "result": "Passed" } ], "escalation_occurred": false, "override_occurred": false, "provenance_chain_id": "chain-12345", "actors": [ { "actor_id": "act-001", "role": "Approver" } ], "graph_execution_id": "exec-54321", "created_at": "2023-10-01T10:00:00Z", "updated_at": "2023-10-02T12:00:00Z", "escalation_events": [], "override_events": [], "redacted_count": 0, "redacted_reason": "" } } } } } }, "400": { "description": "Bad Request due to missing or incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_parameter": { "summary": "Missing orgDid parameter", "description": "The request fails due to a missing orgDid query parameter, which is essential for identifying the organization.", "value": { "type": "https://haio.run/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "Request parameters are missing or malformed.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing authentication", "description": "The request fails due to a lack of authentication token.", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required and has failed or has not yet been provided." } } } } } }, "403": { "description": "Forbidden access due to invalid or expired audit grant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "expired_audit_grant": { "summary": "Expired audit grant", "description": "The request is denied because the audit grant has expired or is not valid for the viewer.", "value": { "type": "https://haio.run/errors/forbidden", "title": "Invalid or expired audit grant", "status": 403, "detail": "grantId must reference an active grant for the authenticated viewer.", "code": "AUDIT_GRANT_INVALID" } } } } } }, "404": { "description": "The requested decision was not found for the specified organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "decision_not_found": { "summary": "Decision not found", "description": "The request fails because the decision ID does not exist within the given organization.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "Decision not found for this org." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_during_processing": { "summary": "Server error during processing", "description": "An unexpected server-side error disrupts the operation.", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/control-plane/audit/decisions/assemble": { "post": { "summary": "Assemble audit decisions for an organization", "description": "This endpoint meticulously assembles audit decisions, weaving together a tapestry of organizational insights. It ensures every decision is documented with precision, offering a transparent view of actions taken within the HUMAN platform. This orchestration is essential for maintaining accountability and trust in automated processes.", "operationId": "assembleAuditDecisions", "tags": [ "Audit", "ControlPlane" ], "x-code-hash": "2d780eb713e10001", "x-generated-at": "2026-04-14T23:29:40.016Z", "responses": { "200": { "description": "Audit decisions successfully assembled for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upserted": { "type": "integer", "description": "The number of audit decisions assembled." }, "assembled_at": { "type": "string", "format": "date-time", "description": "Timestamp when the assembly was completed." } }, "required": [ "upserted", "assembled_at" ] }, "examples": { "successful_assembly": { "summary": "Successful Assembly", "description": "A successful response indicating the number of decisions assembled and the timestamp.", "value": { "upserted": 42, "assembled_at": "2023-10-15T10:00:00Z" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid": { "summary": "Missing orgDid", "description": "The orgDid parameter is missing, which is required unless using an internal token.", "value": { "type": "https://humanprotocol.org/docs/errors/validation", "title": "Validation Error", "status": 400, "detail": "orgDid is required unless caller uses INTERNAL_API_TOKEN", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_OR_INTERNAL", "message": "orgDid is required unless caller uses INTERNAL_API_TOKEN", "expected": "orgDid query param or Bearer internal token", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization_token": { "summary": "Missing Authorization Token", "description": "The request lacks the required authorization token.", "value": { "type": "https://humanprotocol.org/docs/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authorization token is missing or invalid. Please provide a valid token to access this resource." } } } } } }, "403": { "description": "Forbidden: The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "The user does not have permission to assemble audit decisions.", "value": { "type": "https://humanprotocol.org/docs/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action. Ensure your account has the necessary privileges." } } } } } }, "404": { "description": "Not Found: The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found": { "summary": "Organization Not Found", "description": "The specified organization DID does not exist.", "value": { "type": "https://humanprotocol.org/docs/errors/not-found", "title": "Not Found", "status": 404, "detail": "The organization with the provided DID could not be found. Please verify the DID and try again." } } } } } }, "500": { "description": "Internal Server Error: Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://humanprotocol.org/docs/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/audit/decisions/:id/challenge": { "post": { "summary": "Challenge an audit decision", "description": "In the dynamic world of AI governance, sometimes decisions need a second look. This endpoint allows organizations to challenge audit decisions, ensuring transparency and accuracy. By leveraging HUMAN's capability graph, users can request further review or clarification, fostering trust in AI interactions.", "operationId": "challengeAuditDecision", "tags": [ "Audit", "Decision Management" ], "x-code-hash": "789849834ebce007", "x-generated-at": "2026-04-14T23:29:58.502Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenger_passport_id": { "type": "string", "description": "The Passport ID of the challenger." }, "reason": { "type": "string", "description": "The reason for the challenge." }, "narrative": { "type": "string", "description": "Additional narrative or context for the challenge." }, "requested_action": { "type": "string", "description": "The action the challenger is requesting, such as 'second_review'." } } }, "examples": { "challenging_an_audit_decision": { "summary": "Challenging an audit decision", "description": "An organization requests a second review of an audit decision due to perceived discrepancies.", "value": { "challenger_passport_id": "passport:12345", "reason": "Discrepancy in data interpretation", "narrative": "The decision was based on outdated data.", "requested_action": "second_review" } } } } } }, "responses": { "201": { "description": "Challenge successfully created, awaiting review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "Unique identifier for the created challenge." }, "provenance_chain_id": { "type": "string", "description": "Identifier for the provenance chain tracking this challenge." }, "status": { "type": "string", "enum": [ "open" ], "description": "The current status of the challenge." } } }, "examples": { "default": { "summary": "Example", "value": { "challenge_id": "chal_67890", "provenance_chain_id": "chal_chain_chal_67890", "status": "open" } } } } } }, "400": { "description": "Validation error due to missing or invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid request body", "status": 400, "detail": "Body must be JSON", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Missing or invalid authentication credentials." } } } } } }, "403": { "description": "Permission error indicating the user lacks necessary rights.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to challenge this decision." } } } } } }, "404": { "description": "The specified audit decision was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "Decision not found." } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/challenges": { "get": { "summary": "Fetch audit challenges for organization", "description": "Retrieve a list of audit challenges associated with your organization, enabling you to track and manage compliance and decision-making processes. This endpoint is vital for organizations like 'acme' to ensure transparency and accountability in their AI task orchestration.", "operationId": "getAuditChallenges", "tags": [ "Audit", "Compliance" ], "x-code-hash": "3e12c58b9534f041", "x-generated-at": "2026-04-14T23:30:17.184Z", "responses": { "200": { "description": "Successfully retrieved audit challenges", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "challengeId": { "type": "string" }, "decisionId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" } }, "required": [ "challengeId", "decisionId", "createdAt", "status" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" }, "redacted_count": { "type": "integer" }, "redacted_reason": { "type": "string" } } }, "examples": { "successful_retrieval_with_pagination": { "summary": "Successful retrieval with pagination", "description": "A realistic example where 'acme' organization fetches audit challenges with pagination.", "value": { "data": [ { "challengeId": "challenge-123", "decisionId": "decision-456", "createdAt": "2023-10-01T12:00:00Z", "status": "pending" }, { "challengeId": "challenge-789", "decisionId": "decision-012", "createdAt": "2023-09-30T11:00:00Z", "status": "completed" } ], "limit": 2, "cursorField": "createdAt", "hasMore": true, "redacted_count": 0, "redacted_reason": "" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid": { "summary": "Missing orgDid", "description": "Example of a 400 error when orgDid is not provided.", "value": { "type": "https://docs.humanprotocol.org/errors#REQUIRED_QUERY_PARAM", "title": "Invalid Request", "status": 400, "detail": "The 'orgDid' query parameter is required.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access to the endpoint", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_attempt": { "summary": "Unauthorized access attempt", "description": "Example of a 401 error when a user attempts to access without valid credentials.", "value": { "type": "https://docs.humanprotocol.org/errors#unauthorized", "title": "Unauthorized", "status": 401, "detail": "You need to provide valid credentials to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "Example of a 403 error when user permissions are insufficient to access the resource.", "value": { "type": "https://docs.humanprotocol.org/errors#forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "Example of a 404 error when the requested resource is not found.", "value": { "type": "https://docs.humanprotocol.org/errors#not_found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error occurred while processing the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "Example of a 500 error when an unexpected condition was encountered.", "value": { "type": "https://docs.humanprotocol.org/errors#internal_error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/challenges/:challengeId": { "get": { "summary": "Retrieve a specific audit challenge case", "description": "Uncover the story behind a specific challenge in your organization's audit trail. Every challenge tells a tale of compliance and decision-making, ensuring transparency and accountability within the HUMAN ecosystem.", "operationId": "getAuditChallengeCase", "tags": [ "Audit", "Compliance" ], "x-code-hash": "971d1846d9e962ec", "x-generated-at": "2026-04-14T23:30:33.572Z", "responses": { "200": { "description": "Successfully retrieved the audit challenge case.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the challenge case." }, "decision_id": { "type": "string", "description": "Identifier for the decision associated with this challenge." }, "org_did": { "type": "string", "description": "Distributed Identifier for the organization." }, "redacted_count": { "type": "integer", "description": "Number of redactions applied to the challenge case." }, "redacted_reason": { "type": "string", "description": "Reason for any redactions applied." } }, "required": [ "id", "decision_id", "org_did" ] }, "examples": { "example_audit_challenge_case": { "summary": "Example audit challenge case", "description": "Retrieving an audit challenge case for organization with DID 'did:human:acme'.", "value": { "id": "challenge-123", "decision_id": "decision-456", "org_did": "did:human:acme", "redacted_count": 0, "redacted_reason": "" } } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_parameter": { "summary": "Missing orgDid parameter", "description": "An error occurs when the required orgDid parameter is not provided.", "value": { "type": "https://haio.run/errors/validation-error", "title": "Invalid request parameters", "status": 400, "detail": "One or more request parameters are invalid.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_request": { "summary": "Unauthorized request", "description": "An example response when authentication is missing or invalid.", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "description": "An example response when the user does not have permission to access the resource.", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested audit challenge case was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "challenge_not_found": { "summary": "Challenge not found", "description": "An example response when the specified challenge is not found in the audit trail.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "Challenge not found." } } } } } }, "500": { "description": "Server encountered an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "An example response when the server encounters an unexpected condition.", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "The server encountered an unexpected condition that prevented it from fulfilling the request." } } } } } } } }, "patch": { "summary": "Update audit challenge status and disposition", "description": "In the complex dance of ensuring compliance, this endpoint allows organizations to update the status and disposition of audit challenges. By empowering organizations to mark challenges as resolved or withdrawn, it orchestrates a seamless interaction between human oversight and AI precision, ensuring that the audit trail remains robust and transparent.", "operationId": "updateAuditChallenge", "tags": [ "Audit", "Challenge Management" ], "x-code-hash": "1245050902b47938", "x-generated-at": "2026-04-14T23:30:53.024Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "resolved", "withdrawn", "under_review" ], "description": "The new status of the challenge." }, "disposition": { "type": "string", "description": "A note or decision regarding the challenge." } }, "required": [ "status" ] }, "examples": { "resolve_challenge": { "summary": "Resolve Challenge", "description": "An example showing the resolution of a challenge.", "value": { "status": "resolved", "disposition": "The issue was addressed satisfactorily." } } } } } }, "responses": { "200": { "description": "Challenge updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "description": "The ID of the updated challenge." }, "updated": { "type": "boolean", "description": "Indicates if the update was successful." } } }, "examples": { "default": { "summary": "Example", "value": { "challenge_id": "12345", "updated": true } } } } } }, "400": { "description": "Invalid input data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/invalid-input", "title": "Invalid input", "status": 400, "detail": "Body must be JSON", "errors": [ { "field": "body", "message": "Body must be JSON" } ] } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication required to access this resource." } } } } } }, "403": { "description": "Forbidden: You lack the necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to update this challenge." } } } } } }, "404": { "description": "The specified challenge could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "Challenge not found." } } } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/grants": { "get": { "summary": "Retrieve Active Audit Grants", "description": "Discover the active grants for an organization, granting you insights into what capabilities are being utilized and by whom. This endpoint helps maintain transparency and accountability within the HUMAN network, ensuring all actions are traceable and verifiable.", "operationId": "getAuditGrants", "tags": [ "Audit", "Grants" ], "x-code-hash": "6d13256c5a505a78", "x-generated-at": "2026-04-14T23:31:10.958Z", "responses": { "200": { "description": "Successfully retrieves a paginated list of active audit grants for the specified organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "grantId": { "type": "string" }, "orgDid": { "type": "string" }, "capability": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" }, "redacted_count": { "type": "integer" }, "redacted_reason": { "type": "string" } } }, "examples": { "successful_response": { "summary": "Successful Response", "description": "A list of active audit grants for organization 'acme'.", "value": { "data": [ { "grantId": "grant-123", "orgDid": "did:human:org:acme", "capability": "capability://payment.process", "createdAt": "2023-10-01T12:00:00Z", "expiresAt": "2023-12-31T23:59:59Z" } ], "limit": 10, "cursorField": "created_at", "hasMore": false, "redacted_count": 0, "redacted_reason": "" } } } } } }, "400": { "description": "The request was invalid, often due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid": { "summary": "Missing orgDid", "description": "The orgDid query parameter is required but was not provided.", "value": { "type": "https://example.com/probs/required-query-parameter", "title": "Required Query Parameter", "status": 400, "detail": "The query parameter 'orgDid' is required.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } }, "invalid_cursor": { "summary": "Invalid Cursor", "description": "The pagination cursor provided is invalid.", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid Pagination Cursor", "status": 400, "detail": "The pagination cursor is not valid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque", "received": "invalidCursor" } ] } } } } } }, "401": { "description": "Unauthorized access, often due to missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "When the user is not authenticated.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "Forbidden access, indicating that the user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "When the user does not have permission to access the grants.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these audit grants." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found": { "summary": "Not Found", "description": "When the specified organization or resource is not found.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected server error occurred. Please try again later." } } } } } } } }, "post": { "summary": "Create a new audit grant", "description": "In the HUMAN platform, oversight and transparency are paramount. This endpoint empowers organizations to delegate audit rights through cryptographic Passports, ensuring that the right individuals can review and validate transactions. By facilitating controlled access, it maintains trust and security within the system.", "operationId": "createAuditGrant", "tags": [ "Audit", "Access Control" ], "x-code-hash": "b645256fb74005b9", "x-generated-at": "2026-04-14T23:31:27.965Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grantee_passport_id": { "type": "string", "description": "The Passport ID of the grantee who receives the audit rights." }, "granter_passport_id": { "type": "string", "description": "The Passport ID of the granter delegating the audit rights." }, "purpose": { "type": "string", "description": "The reason for granting the audit rights, e.g., 'audit_review'." }, "mode": { "type": "string", "description": "The mode of audit rights, e.g., 'delegated_investigation'." }, "scope": { "type": "object", "additionalProperties": true, "description": "The scope of the audit rights, defined as a JSON object." }, "expires_at": { "type": "string", "format": "date-time", "description": "The expiration date and time for the audit grant." } }, "required": [ "grantee_passport_id" ] }, "examples": { "grant_audit_rights_for_compliance": { "summary": "Grant Audit Rights for Compliance", "description": "Delegating audit rights to an external auditor for compliance checks.", "value": { "grantee_passport_id": "passport:12345", "granter_passport_id": "passport:67890", "purpose": "compliance_audit", "mode": "delegated_investigation", "scope": { "access": "full" }, "expires_at": "2023-12-31T23:59:59Z" } } } } } }, "responses": { "201": { "description": "Audit grant successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "description": "The unique identifier for the created audit grant." } } }, "examples": { "default": { "summary": "Example", "value": { "grant_id": "agrant:1234567890" } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing fields", "status": 400, "detail": "grantee_passport_id and granter context required.", "errors": [ { "field": "grantee_passport_id", "code": "REQUIRED", "message": "This field is required." } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Valid credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden: The user lacks the necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/permissions", "title": "Permission Denied", "status": 403, "detail": "Creating audit grants requires audit:admin or cloud:admin:global permissions." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/server", "title": "Server Error", "status": 500, "detail": "An unexpected condition was encountered. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/views": { "get": { "summary": "Retrieve audit views for an organization", "description": "Explore the intricate records of saved audit views within an organization on the HUMAN platform. This endpoint helps administrators track and manage the audit trail of various views, ensuring transparency and accountability in data handling practices.", "operationId": "getAuditSavedViews", "tags": [ "Audit", "Views" ], "x-code-hash": "ae663753bb7fd764", "x-generated-at": "2026-04-14T23:32:42.325Z", "responses": { "200": { "description": "Successfully retrieved a paginated list of audit views.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "viewId": { "type": "string" }, "orgDid": { "type": "string" }, "ownerPassportId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "viewId", "orgDid", "ownerPassportId", "createdAt" ] } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorField", "hasMore" ] }, "examples": { "successful_retrieval_of_audit_views": { "summary": "Successful retrieval of audit views", "value": { "data": [ { "viewId": "view123", "orgDid": "did:human:acme", "ownerPassportId": "passport123", "createdAt": "2023-10-01T12:34:56Z" } ], "limit": 10, "cursorField": "created_at", "hasMore": false } } } } } }, "400": { "description": "Invalid request due to missing or incorrect query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_query_parameters": { "summary": "Missing query parameters", "value": { "type": "https://humanprotocol.org/errors/missing-query-params", "title": "Bad Request", "status": 400, "detail": "orgDid and ownerPassportId are required query parameters.", "errors": [ { "field": "orgDid|ownerPassportId", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid and ownerPassportId are required", "expected": "string", "received": "undefined" } ] } }, "invalid_cursor": { "summary": "Invalid cursor", "value": { "type": "https://humanprotocol.org/errors/invalid-cursor", "title": "Bad Request", "status": 400, "detail": "The provided pagination cursor is invalid.", "errors": [ { "field": "cursor", "code": "INVALID_CURSOR", "message": "Invalid pagination cursor", "expected": "opaque", "received": "someInvalidCursor" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access to this resource requires authentication. Please provide a valid Passport." } } } } } }, "403": { "description": "Forbidden access when the user lacks necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these audit views. Contact your administrator for access." } } } } } }, "404": { "description": "Resource not found if the specified organization or owner does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified organization or owner does not exist in the system." } } } } } }, "500": { "description": "Internal server error indicating a server-side problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } }, "post": { "summary": "Create a new audit view", "description": "In a world where transparency is paramount, creating personalized audit views empowers organizations to tailor how they monitor their operations. This endpoint allows you to define and save custom views, enriching your insight into the complex dance of human and AI interactions.", "operationId": "createAuditView", "tags": [ "Audit", "Views" ], "x-code-hash": "c8a072c5980921e3", "x-generated-at": "2026-04-14T23:32:58.164Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the audit view." }, "owner_passport_id": { "type": "string", "description": "Passport ID of the owner creating this view." }, "filter_config": { "type": "object", "description": "Custom configuration for filtering the audit data.", "additionalProperties": true } }, "required": [ "name", "owner_passport_id" ] }, "examples": { "creating_audit_view_for_invoices": { "summary": "Creating Audit View for Invoices", "description": "An example where the 'acme' organization creates a view to track invoice processing audits.", "value": { "name": "Invoice Processing", "owner_passport_id": "passport:acme:12345", "filter_config": { "status": "processed", "priority": "high" } } } } } } }, "responses": { "201": { "description": "Audit view successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "view_id": { "type": "string", "description": "Unique identifier for the created audit view." } } }, "examples": { "default": { "summary": "Example", "value": { "view_id": "aview:001122334455" } } } } } }, "400": { "description": "Invalid request due to missing fields or incorrect JSON format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Missing fields", "status": 400, "detail": "orgDid query param, name, owner_passport_id required." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Authentication required to access this resource." } } } } } }, "403": { "description": "Forbidden: You lack permission to create audit views.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/permission", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create audit views." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource does not exist." } } } } } }, "500": { "description": "Internal Server Error: Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/server", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/bundles": { "post": { "summary": "Create a new evidence bundle", "description": "Embark on a journey to safeguard truth with this endpoint, which crafts cryptographic evidence bundles from decision data. Harness the power of provenance tracking to ensure every decision within an organization is both transparent and verifiable.", "operationId": "postAuditEvidenceBundle", "tags": [ "Audit", "Evidence" ], "x-code-hash": "260c62d9d17a3304", "x-generated-at": "2026-04-14T23:33:15.333Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_ids": { "type": "array", "items": { "type": "string" }, "description": "List of decision IDs to include in the bundle." }, "format": { "type": "string", "description": "The format of the evidence bundle, defaulting to 'ops'." }, "generated_by": { "type": "string", "description": "The DID of the entity generating the bundle. Defaults to the organization DID if not provided." } }, "required": [ "decision_ids" ] }, "examples": { "bundle_creation_with_decision_ids": { "summary": "Bundle creation with decision IDs", "description": "An example of creating an evidence bundle with specified decision IDs.", "value": { "decision_ids": [ "dec123", "dec456" ], "format": "ops", "generated_by": "did:example:generator" } } } } } }, "responses": { "201": { "description": "The evidence bundle was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle_id": { "type": "string", "description": "The unique identifier of the newly created evidence bundle." }, "merkle_root": { "type": "string", "description": "The Merkle root of the evidence bundle." }, "signing_key_id": { "type": "string", "description": "The identifier of the key used to sign the bundle." }, "signature": { "type": "string", "description": "The cryptographic signature of the bundle." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the bundle was created." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request is invalid due to missing or malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed due to missing or invalid fields.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" }, { "field": "body", "code": "INVALID_JSON", "message": "Body must be JSON", "expected": "object", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this endpoint. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create evidence bundles. Contact your administrator for access." } } } } } }, "404": { "description": "The specified resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found. Verify the URL and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/audit/workbench/templates": { "post": { "summary": "Create a recurring Workbench investigation template", "description": "In the intricate dance of human and AI collaboration, maintaining oversight is crucial. This endpoint allows you to save configurations for recurring investigations within the Workbench, ensuring consistent monitoring and analysis. By setting entry points and filters, you can automate the oversight process, harnessing the power of data to drive informed decisions.", "operationId": "createWorkbenchTemplate", "tags": [ "Audit", "ControlPlane" ], "x-code-hash": "d11cd9ed617c7e14", "x-generated-at": "2026-04-14T23:33:33.075Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A unique name for the investigation template." }, "owner_passport_id": { "type": "string", "description": "The Passport ID of the template owner." }, "entry_point_type": { "type": "string", "description": "The type of entry point for the investigation." }, "filter_config": { "type": "object", "additionalProperties": true, "description": "A JSON object detailing filter configurations." }, "investigation_mode": { "type": "string", "description": "The mode of investigation, defaults to 'ops'." } }, "required": [ "name", "owner_passport_id", "entry_point_type" ] }, "examples": { "standard_investigation_template": { "summary": "Standard Investigation Template", "description": "A typical configuration for a compliance audit.", "value": { "name": "Compliance Audit Q1", "owner_passport_id": "passport:12345", "entry_point_type": "financial", "filter_config": { "department": "finance", "quarter": "Q1" }, "investigation_mode": "ops" } } } } } }, "responses": { "201": { "description": "The template was successfully created with a unique ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template_id": { "type": "string", "description": "The unique identifier for the created template." } } }, "examples": { "default": { "summary": "Example", "value": { "template_id": "wbtpl-1234567890" } } } } } }, "400": { "description": "Invalid or missing fields in the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication credentials were missing or incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "The user does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "summary": "Retrieve audit templates for user", "description": "Uncover a treasure trove of audit workbench templates tailored for a specific user within an organization. This endpoint empowers organizations to seamlessly track and manage their audit templates, ensuring efficiency and compliance through precise task orchestration.", "operationId": "getAuditWorkbenchTemplates", "tags": [ "Audit", "Workbench" ], "x-code-hash": "2895008b5936e7c5", "x-generated-at": "2026-04-14T23:32:26.684Z", "responses": { "200": { "description": "Successfully retrieves a list of audit workbench templates, with pagination support to navigate large datasets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "templateId": { "type": "string" }, "templateName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } } }, "examples": { "paginated_audit_templates": { "summary": "Paginated audit templates", "value": { "data": [ { "templateId": "tmpl_12345", "templateName": "Quarterly Financial Audit", "createdAt": "2023-10-11T08:45:30Z" }, { "templateId": "tmpl_12346", "templateName": "Annual Compliance Review", "createdAt": "2023-10-10T14:12:00Z" } ], "limit": 10, "cursorField": "createdAt", "hasMore": true } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_parameters": { "summary": "Missing Parameters", "value": { "type": "https://humanprotocol.org/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "orgDid and ownerPassportId are required", "errors": [ { "field": "orgDid|ownerPassportId", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid and ownerPassportId are required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://humanprotocol.org/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are required." } } } } } }, "403": { "description": "Forbidden access when the user does not have permission to view the requested templates.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://humanprotocol.org/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these templates." } } } } } }, "404": { "description": "Not Found when the specified templates do not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "templates_not_found": { "summary": "Templates Not Found", "value": { "type": "https://humanprotocol.org/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested templates were not found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "https://humanprotocol.org/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/audit/decisions/:id": { "get": { "summary": "Retrieve audit decision details by ID", "description": "Dive into the history of an organization's decision-making process by fetching detailed records of audit decisions. This endpoint reveals the intricacies of decision provenance, ensuring transparency and accountability in AI-assisted operations.", "operationId": "getAuditDecisionById", "tags": [ "Audit", "Decisions" ], "x-code-hash": "d8b98bc761a1d2e2", "x-generated-at": "2026-04-13T19:57:50.109Z", "responses": { "200": { "description": "Successfully retrieved the audit decision details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the decision." }, "title": { "type": "string", "description": "The title of the decision." }, "workflow_id": { "type": "string", "description": "Associated workflow identifier." }, "org_did": { "type": "string", "description": "DID of the organization." }, "decision_type": { "type": "string", "description": "The type of decision made." }, "status": { "type": "string", "description": "Current status of the decision." }, "risk_level": { "type": "string", "description": "Risk level associated with the decision." }, "policy_checks": { "type": "array", "items": { "type": "object" }, "description": "List of policy checks performed." }, "escalation_occurred": { "type": "boolean", "description": "Indicates if escalation occurred." }, "override_occurred": { "type": "boolean", "description": "Indicates if override occurred." }, "provenance_chain_id": { "type": "string", "description": "Provenance chain identifier." }, "actors": { "type": "array", "items": { "type": "object" }, "description": "List of actors involved in the decision." }, "graph_execution_id": { "type": "string", "description": "Graph execution identifier." }, "policy_version_snapshot": { "type": "string", "description": "Snapshot of the policy version." }, "integrity_status": { "type": "string", "description": "Integrity status of the decision." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp." } } }, "examples": { "detailed_decision_example": { "summary": "Detailed Decision Example", "description": "Shows a complete audit decision for organization 'acme'.", "value": { "id": "dec123", "title": "Invoice Review", "workflow_id": "wf456", "org_did": "did:human:acme", "decision_type": "approval", "status": "completed", "risk_level": "low", "policy_checks": [], "escalation_occurred": false, "override_occurred": false, "provenance_chain_id": "chain789", "actors": [], "graph_execution_id": "exec101", "policy_version_snapshot": "v1.0", "integrity_status": "verified", "created_at": "2023-10-02T14:48:00Z", "updated_at": "2023-10-02T15:00:00Z" } } } } } }, "400": { "description": "Malformed request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_error": { "summary": "Missing orgDid Error", "description": "Error returned when orgDid parameter is missing.", "value": { "type": "https://haio.run/errors/validation-error", "title": "Validation Failed", "status": 400, "detail": "orgDid is required and must be a string.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "404": { "description": "Decision not found with the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "decision_not_found_example": { "summary": "Decision Not Found Example", "description": "Error when decision ID doesn't exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Not found", "status": 404, "detail": "Decision not found." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "Unexpected server error.", "value": { "type": "https://haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/decisions": { "get": { "summary": "Retrieve audit decisions with flexible filtering", "description": "Explore the audit decisions made within your organization, leveraging powerful filters to navigate complex data. This endpoint is your window into the decision-making process, enabling transparency and compliance by surfacing the 'who,' 'what,' and 'why' behind each decision. By understanding these decisions, organizations can better orchestrate their human and AI resources, ensuring decisions align with their strategic goals.", "operationId": "getAuditDecisions_1", "tags": [ "Audit", "Compliance" ], "x-code-hash": "52a9f287a1f3371e", "x-generated-at": "2026-04-14T23:28:54.141Z", "responses": { "200": { "description": "A successful response contains a paginated list of audit decisions filtered according to the query parameters. Each decision provides insight into decision types, risk levels, and workflow associations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "workflow_id": { "type": "string" }, "org_did": { "type": "string" }, "decision_type": { "type": "string" }, "status": { "type": "string" }, "risk_level": { "type": "string" }, "confidence_at_decision": { "type": "number" }, "policy_checks": { "type": "array", "items": { "type": "object" } }, "escalation_occurred": { "type": "boolean" }, "override_occurred": { "type": "boolean" }, "outcome_narrative": { "type": "string" }, "provenance_chain_id": { "type": "string" }, "source_event_hashes": { "type": "array", "items": { "type": "string" } }, "policy_version_snapshot": { "type": "string" }, "integrity_status": { "type": "string" }, "actors": { "type": "array", "items": { "type": "object" } }, "graph_execution_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursor": { "type": "string" }, "hasMore": { "type": "boolean" }, "redacted_count": { "type": "integer" }, "redacted_reason": { "type": "string" } }, "required": [ "data", "limit", "cursor", "hasMore", "redacted_count", "redacted_reason" ] }, "examples": { "acme_corp's_audit_decision_retrieval": { "summary": "Acme Corp's audit decision retrieval", "description": "Acme Corp requests to view recent audit decisions, filtered by risk level and status.", "value": { "data": [ { "id": "decision123", "title": "Payment Approval", "workflow_id": "workflow789", "org_did": "did:example:acme", "decision_type": "automatic", "status": "approved", "risk_level": "low", "confidence_at_decision": 0.98, "policy_checks": [], "escalation_occurred": false, "override_occurred": false, "outcome_narrative": "Decision aligns with policy.", "provenance_chain_id": "chain456", "source_event_hashes": [ "hash123", "hash456" ], "policy_version_snapshot": "v1.2.3", "integrity_status": "intact", "actors": [], "graph_execution_id": "exec987", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T12:00:00Z" } ], "limit": 10, "cursor": "2023-10-02T12:00:00Z", "hasMore": false, "redacted_count": 0, "redacted_reason": "" } } } } } }, "400": { "description": "The request was malformed, typically due to missing required query parameters or invalid cursor values.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication failed, possibly due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Access to the requested resource is forbidden, often due to invalid or expired audit grant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/control-plane/audit/grants/:id": { "patch": { "summary": "Revoke an Audit Grant by ID", "description": "In the realm of audit management, control is paramount. This endpoint allows administrators to revoke an existing audit grant, ensuring that outdated or erroneous permissions are swiftly nullified. By invoking this, you secure the integrity of your audit processes when certain grants are no longer valid or necessary.", "operationId": "revokeAuditGrant", "tags": [ "Audit", "Control" ], "x-code-hash": "07531d17b83b47dd", "x-generated-at": "2026-04-14T23:31:51.674Z", "responses": { "200": { "description": "Audit grant successfully revoked or already revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "description": "The unique identifier of the audit grant" }, "revoked": { "type": "boolean", "description": "Indicates if the grant was revoked in this operation" }, "already_revoked": { "type": "boolean", "description": "Indicates if the grant was already revoked prior to this operation" }, "revoked_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the grant was revoked" } }, "required": [ "grant_id", "revoked" ] }, "examples": { "already_revoked_grant": { "summary": "Already Revoked Grant", "description": "This example shows a grant that was already revoked.", "value": { "grant_id": "123abc", "revoked": false, "already_revoked": true, "revoked_at": "2023-01-15T08:30:00Z" } } } } } }, "400": { "description": "Invalid request due to missing parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid": { "summary": "Missing orgDid", "description": "The request is missing the required orgDid.", "value": { "type": "https://haio.run/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "orgDid is required", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "description": "The user does not have valid authentication.", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Invalid authentication credentials provided." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have the required scope to revoke an audit grant.", "value": { "type": "https://haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Revoking audit grants requires audit:admin or cloud:admin:global." } } } } } }, "404": { "description": "Audit grant not found for the specified ID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "grant_not_found": { "summary": "Grant Not Found", "description": "The audit grant with the specified ID does not exist.", "value": { "type": "https://haio.run/errors/not-found", "title": "Grant not found", "status": 404, "detail": "No audit grant with this id for the given org.", "code": "AUDIT_GRANT_NOT_FOUND" } } } } } }, "500": { "description": "Internal server error during grant revocation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred while processing the request.", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/control-plane/audit/access-log": { "get": { "summary": "Retrieve organization's audit access log", "description": "Explore the intricate dance of responsibility and transparency with our audit access log, where organizational oversight meets accountability. This endpoint empowers audit administrators to meticulously track who accessed what and when, ensuring that every digital interaction is recorded for posterity.", "operationId": "getAccessLog", "tags": [ "Audit", "Access Control" ], "x-code-hash": "6a28f6fe1e3c1d2f", "x-generated-at": "2026-04-14T23:32:07.828Z", "responses": { "200": { "description": "Successfully retrieved the audit access log entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "grantee_passport_id": { "type": "string" }, "grant_id": { "type": [ "string", "null" ] }, "org_did": { "type": "string" }, "query_scope": { "type": "string" }, "accessed_at": { "type": "string", "format": "date-time" } } } }, "limit": { "type": "integer" }, "cursorField": { "type": "string" }, "hasMore": { "type": "boolean" } } }, "examples": { "successful_retrieval": { "summary": "Successful retrieval", "value": { "data": [ { "id": "123456", "grantee_passport_id": "passport:12345", "grant_id": "grant:67890", "org_did": "did:org:acme", "query_scope": "read:all", "accessed_at": "2023-10-05T14:48:00Z" } ], "limit": 10, "cursorField": "accessed_at", "hasMore": false } } } } } }, "400": { "description": "Bad request due to validation errors", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_parameter": { "summary": "Missing orgDid parameter", "value": { "type": "https://example.com/probs/required-query-param", "title": "Required Query Parameter Missing", "status": 400, "detail": "The 'orgDid' query parameter is required.", "errors": [ { "field": "orgDid", "code": "REQUIRED_QUERY_PARAM", "message": "orgDid is required", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid credentials", "value": { "type": "https://example.com/probs/invalid-credentials", "title": "Invalid Credentials", "status": 401, "detail": "Authentication credentials were not provided or are invalid. Please ensure your request includes valid credentials." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "value": { "type": "https://example.com/probs/insufficient-permissions", "title": "Insufficient Permissions", "status": 403, "detail": "Reading audit access log requires audit:admin or cloud:admin:global. Ensure you have the necessary permissions." } } } } } }, "500": { "description": "Internal Server Error due to unforeseen issues", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/intent": { "post": { "summary": "Create and route a new intent", "description": "This endpoint breathes life into your HUMAN platform by capturing and shaping user intents for task orchestration. With a blend of AI and human oversight, it transforms raw inputs into actionable intents, ensuring each task is routed with precision and safety.", "operationId": "createIntent", "tags": [ "Intent Management", "AI Orchestration" ], "x-code-hash": "530eb45c8050c010", "x-generated-at": "2026-04-26T23:18:46.563Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "raw_input": { "type": "string", "description": "The unprocessed text representing the user's intent" }, "source_surface": { "type": "string", "enum": [ "companion", "control_plane", "workflow_designer", "agent_builder" ], "description": "The interface from which the intent originated" }, "modality": { "type": "string", "enum": [ "text", "voice", "image", "document", "form", "mixed", "template" ], "description": "The format of the input data" }, "template_id": { "type": "string", "description": "Optional ID for a specific template if applicable" } }, "required": [ "raw_input" ] }, "examples": { "text-based_intent_from_control_plane": { "summary": "Text-based Intent from Control Plane", "description": "Illustrates a basic text intent submitted from the control plane interface.", "value": { "raw_input": "Process the latest invoices for approval", "source_surface": "control_plane", "modality": "text", "template_id": "invoice-template-001" } } } } } }, "responses": { "200": { "description": "The intent was successfully created and routed", "content": { "application/json": { "schema": { "type": "object", "properties": { "intent_id": { "type": "string", "description": "Unique identifier for the created intent" }, "status": { "type": "string", "description": "Current status of the routing process" } } }, "examples": { "default": { "summary": "Example", "value": { "intent_id": "intent-123456", "status": "routing_in_progress" } } } } } }, "400": { "description": "Bad Request due to missing or invalid fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/validation", "title": "Invalid request parameters", "status": 400, "detail": "The request body is missing required fields", "errors": [ { "field": "raw_input", "code": "REQUIRED_FIELD_MISSING", "message": "raw_input is required", "expected": "string", "received": "missing" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication", "title": "Authentication Required", "status": 401, "detail": "Authentication required to create an intent. Please ensure you're logged in and try again." } } } } } }, "403": { "description": "Forbidden, not enough permissions to create intents", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create intents in this organization. Contact your administrator for access." } } } } } }, "404": { "description": "Resource not found, such as a template", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not_found", "title": "Resource Not Found", "status": 404, "detail": "The specified template_id does not exist. Please verify the template ID and try again." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "summary": "Retrieve Intent Briefs for an Organization", "description": "Delve into the orchestration of Human-AI collaboration by fetching intent briefs that guide AI interactions. This endpoint is crucial for organizations looking to monitor and enhance AI-driven workflows, by providing insights derived from the Capability Graph.", "operationId": "getIntentBriefs", "tags": [ "Intent", "Organization" ], "x-code-hash": "3319c713b7ded6a7", "x-generated-at": "2026-04-26T23:19:36.612Z", "responses": { "200": { "description": "Successfully retrieved a paginated list of intent briefs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "updated_at", "status" ] } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorFields", "hasMore" ] }, "examples": { "successful_retrieval_of_intent_briefs": { "summary": "Successful retrieval of intent briefs", "value": { "data": [ { "id": "intent123", "updated_at": "2023-10-05T12:00:00Z", "status": "active", "description": "An AI task to process invoices for Acme Corp." } ], "limit": 10, "cursorFields": [ "updated_at", "id" ], "hasMore": false } } } } } }, "400": { "description": "Invalid query parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_limit_parameter": { "summary": "Invalid limit parameter", "description": "The provided limit exceeds allowable bounds.", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid Request", "status": 400, "detail": "The 'limit' parameter must be a positive integer less than or equal to 100. Please adjust your request accordingly.", "errors": [] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_org_context": { "summary": "Missing Org context", "description": "The request lacks a valid organizational context.", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "Org context required. Please provide valid credentials associated with your organization's Passport.", "errors": [] } } } } } }, "403": { "description": "Forbidden access due to inadequate permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "description": "The user does not have sufficient permissions to access these intent briefs.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access intent briefs in this organization. Please contact your administrator to request access.", "errors": [] } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "intent_briefs_not_found": { "summary": "Intent briefs not found", "description": "No intent briefs found matching the given criteria.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "No intent briefs were found with the provided parameters. Please ensure the organization DID and status are correct.", "errors": [] } } } } } }, "500": { "description": "Internal server error while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_connection_error": { "summary": "Database connection error", "description": "An error occurred while connecting to the database.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later or contact support if the problem persists.", "errors": [] } } } } } } } } }, "/v1/intent/transcribe": { "post": { "summary": "Transcribe audio into intent brief", "description": "Transform spoken words into actionable intent briefs, enabling seamless AI orchestration. This endpoint captures and decodes audio snippets, creating structured insights that drive workflow automation.", "operationId": "transcribeAudioToIntentBrief", "tags": [ "HumanOS", "Intents" ], "x-code-hash": "0cb3fec160881c8e", "x-generated-at": "2026-04-26T23:18:57.660Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audio_base64": { "type": "string", "description": "Base64-encoded audio file to be transcribed." }, "transcript": { "type": "string", "description": "Optional pre-existing transcription of the audio." }, "source_surface": { "type": "string", "enum": [ "companion", "control_plane", "workflow_designer", "agent_builder" ], "description": "Origin surface where the request was made." } } }, "examples": { "transcribe_an_audio_note": { "summary": "Transcribe an Audio Note", "description": "Demonstrating transcription of a Base64 audio input captured from companion surface.", "value": { "audio_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA... (truncated)", "source_surface": "companion" } } } } } }, "responses": { "200": { "description": "Audio successfully transcribed into an intent brief.", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "type": "object", "description": "The structured intent brief derived from the audio." }, "needs_clarification": { "type": "boolean", "description": "Indicates if the intent requires further clarification." }, "clarification_questions": { "type": "array", "items": { "type": "string" }, "description": "Questions to clarify the intent if needed." } } }, "examples": { "default": { "summary": "Example", "value": { "brief": { "intent": "schedule_meeting", "details": { "time": "2023-10-01T10:00:00Z", "participants": [ "alice@acme.com", "bob@acme.com" ] } }, "needs_clarification": false, "clarification_questions": [] } } } } } }, "400": { "description": "Invalid request payload.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The audio_base64 field must be a valid Base64 string." } } } } } }, "401": { "description": "Authentication failure due to missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication required. Please provide valid credentials." } } } } } }, "403": { "description": "Access denied due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/access-denied", "title": "Access Denied", "status": 403, "detail": "You do not have permission to transcribe audio. Contact your administrator." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error occurred during processing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/intent/extract": { "post": { "summary": "Extract Intent from Document Text", "description": "Uncover the essence hidden within your documents by extracting intents with precision. This endpoint transforms raw text into actionable insights, seamlessly integrating human expertise with AI efficiency for enriched task management.", "operationId": "extractIntentFromDocument", "tags": [ "Intent Extraction", "Document Processing" ], "x-code-hash": "d0adf96013fb12ca", "x-generated-at": "2026-04-26T23:19:13.382Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_text": { "type": "string", "description": "The text content from which to extract intent." }, "source_surface": { "type": "string", "description": "The interface source where the document text is found.", "enum": [ "companion", "control_plane", "workflow_designer", "agent_builder" ] } }, "required": [ "document_text" ] }, "examples": { "extract_from_control_plane": { "summary": "Extract from Control Plane", "description": "Extracting intent from a document sourced from the control plane.", "value": { "document_text": "Please process the invoice for Acme Corp.", "source_surface": "control_plane" } } } } } }, "responses": { "200": { "description": "The intent was successfully extracted and stored for further processing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "type": "object", "description": "A structured representation of the extracted intent." }, "needs_clarification": { "type": "boolean", "description": "Indicates if further clarification is required." }, "clarification_questions": { "type": "array", "items": { "type": "string" }, "description": "Questions generated to clarify ambiguous intents." } } }, "examples": { "successful_extraction": { "summary": "Successful Extraction", "description": "The extraction process successfully interpreted the document's intent.", "value": { "brief": { "intent": "process_invoice", "organization": "Acme Corp" }, "needs_clarification": false, "clarification_questions": [] } } } } } }, "400": { "description": "Bad request due to missing or malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_document_text": { "summary": "Missing Document Text", "description": "The request is missing the required document_text field.", "value": { "type": "/problems/invalid-request", "title": "Invalid Request", "status": 400, "detail": "document_text is required", "errors": [ { "field": "document_text", "message": "document_text is required" } ] } } } } } }, "401": { "description": "Unauthorized due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request lacks valid authentication credentials.", "value": { "type": "/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication required" } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have the necessary permissions to perform this action.", "value": { "type": "/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "Access forbidden for this resource" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "The requested endpoint or resource could not be located.", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred causing the server to fail processing the request.", "value": { "type": "/problems/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server" } } } } } } } } }, "/v1/intent/ingest": { "post": { "summary": "Ingest multimodal intent data", "description": "This endpoint allows organizations to seamlessly ingest diverse forms of intent data—be it text, documents, or audio. By processing multimodal inputs, HUMAN enhances the efficiency of task orchestration and ensures that AI models are trained with the richest possible datasets.", "operationId": "ingestIntentData", "tags": [ "Intent", "Multimodal" ], "x-code-hash": "252cfc6ca71877a7", "x-generated-at": "2026-04-26T23:19:24.577Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "The raw text of the intent." }, "document_text": { "type": "string", "description": "A textual document representing the intent." }, "audio_base64": { "type": "string", "description": "Base64-encoded audio data." }, "source_surface": { "type": "string", "enum": [ "companion", "control_plane", "workflow_designer", "agent_builder" ], "description": "The origin of the intent submission." } }, "oneOf": [ { "required": [ "text" ] }, { "required": [ "document_text" ] }, { "required": [ "audio_base64" ] } ] }, "examples": { "text-based_intent_ingestion": { "summary": "Text-based intent ingestion", "description": "Submitting a simple text intent from the companion surface.", "value": { "text": "How to process invoices more efficiently?", "source_surface": "companion" } } } } } }, "responses": { "200": { "description": "The intent was successfully ingested and processed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "type": "object", "description": "A brief summarizing the intent data." }, "needs_clarification": { "type": "boolean", "description": "Indicates if more information is needed." }, "clarification_questions": { "type": "array", "items": { "type": "string" }, "description": "Questions to clarify the intent." } } }, "examples": { "successful_intent_processing": { "summary": "Successful intent processing", "value": { "brief": { "summary": "Intent to optimize invoice processing" }, "needs_clarification": false, "clarification_questions": [] } } } } } }, "400": { "description": "The request body is missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_required_fields": { "summary": "Missing required fields", "value": { "type": "https://api.human.com/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Provide at least one of text, document_text, or audio_base64", "errors": [ { "field": "body", "code": "REQUIRED_FIELD_MISSING", "message": "Provide at least one of text, document_text, or audio_base64", "expected": "object", "received": "empty" } ] } } } } } }, "401": { "description": "Authentication is required and was not provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication error", "value": { "type": "https://api.human.com/problems/authentication-error", "title": "Authentication Required", "status": 401, "detail": "Authentication required" } } } } } }, "403": { "description": "The user does not have permission to ingest intent data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_error": { "summary": "Permission error", "value": { "type": "https://api.human.com/problems/permission-error", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to ingest intent data" } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_error": { "summary": "Not found error", "value": { "type": "https://api.human.com/problems/not-found", "title": "Resource Not Found", "status": 404, "detail": "The resource you are looking for does not exist" } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "value": { "type": "https://api.human.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/intent/:id/lineage": { "get": { "summary": "Retrieve intent lineage details for analysis", "description": "Uncover the historical context and evolution of a specific intent within the HUMAN platform. This endpoint provides a comprehensive lineage, detailing its versions, associated resolution plans, and related artifacts. This insight is crucial for organizations aiming to audit or enhance their Human-AI orchestration strategies.", "operationId": "getIntentLineage", "tags": [ "Intent", "Lineage", "Audit" ], "x-code-hash": "30bc132b1b5dfe1b", "x-generated-at": "2026-04-26T23:19:49.716Z", "responses": { "200": { "description": "Successfully retrieves intent lineage, including versions and latest resolution plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "intent_brief": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "name": { "type": "string" } } }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "snapshot": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "resolution_plan": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "brief_version_at_compilation": { "type": "integer" }, "stale": { "type": "boolean" } } }, "scaffolded_artifacts": { "type": "array", "items": { "type": "string" } }, "execution_runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" } } } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "decided_at": { "type": "string", "format": "date-time" } } } }, "audit_event_ids": { "type": "array", "items": { "type": "string" } } } }, "examples": { "acme_corp_intent_lineage_retrieval": { "summary": "Acme Corp intent lineage retrieval", "description": "Fetching the lineage for an intent used in Acme Corp's invoice processing.", "value": { "intent_brief": { "id": "intent-123", "version": 5, "name": "Invoice Processing Intent" }, "versions": [ { "version": 1, "snapshot": "Initial setup", "created_at": "2023-01-01T10:00:00Z" }, { "version": 5, "snapshot": "Optimized for speed", "created_at": "2023-03-01T10:00:00Z" } ], "resolution_plan": { "id": "plan-456", "brief_version_at_compilation": 4, "stale": true }, "scaffolded_artifacts": [ "artifact-789" ], "execution_runs": [], "approvals": [], "audit_event_ids": [ "event-101" ] } } } } } }, "400": { "description": "Invalid request due to malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_intent_id": { "summary": "Missing intent ID", "description": "The request was made without specifying an intent ID.", "value": { "type": "/problems/invalid-parameters", "title": "Invalid parameters", "status": 400, "detail": "The request is missing required parameters.", "errors": [ { "field": "id", "message": "Intent ID is required." } ] } } } } } }, "401": { "description": "Authentication failure due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_request": { "summary": "Unauthenticated request", "description": "The request was made without valid authentication.", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Org context required. Please provide valid credentials." } } } } } }, "403": { "description": "Access denied due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "description": "The user does not have permission to view this intent lineage.", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have the necessary permissions to access this resource." } } } } } }, "404": { "description": "The specified intent was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "intent_not_found": { "summary": "Intent not found", "description": "The intent ID provided does not correspond to any existing record.", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "Intent not found. Please verify the intent ID and try again." } } } } } }, "500": { "description": "Unexpected server error when processing request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "An unexpected error occurred on the server.", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/intent/:id/audit": { "get": { "summary": "Retrieve audit trail for Intent", "description": "Explore the history of an Intent, capturing its evolutionary journey through different versions and compilations. This endpoint provides a detailed audit trail, showcasing how an Intent has been shaped and compiled over time, ensuring transparency and traceability in decision-making.", "operationId": "getIntentAudit", "tags": [ "Audit", "Intent" ], "x-code-hash": "3a24ff3dfe87ad9d", "x-generated-at": "2026-04-26T23:20:03.696Z", "responses": { "200": { "description": "Successfully retrieved the audit trail of an Intent, including its versions and resolution plans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "intent_brief_id": { "type": "string", "description": "The unique identifier of the Intent." }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer", "description": "The version number of the Intent." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when this version was created." } } } }, "compilations": { "type": "array", "items": { "type": "object", "properties": { "resolution_plan_id": { "type": "string", "description": "The unique identifier of the resolution plan." }, "brief_version_at_compilation": { "type": "integer", "description": "The version of the Intent brief at the time of compilation." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when this compilation was created." } } } }, "provenance_capabilities": { "type": "array", "items": { "type": "string" }, "description": "A list of capabilities that track the provenance of the Intent." }, "query_provenance": { "type": "object", "properties": { "post": { "type": "string", "description": "The endpoint to query provenance events." }, "hint": { "type": "string", "description": "A hint on how to filter provenance events." } } } } }, "examples": { "successful_audit_retrieval": { "summary": "Successful Audit Retrieval", "value": { "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000", "versions": [ { "version": 1, "created_at": "2023-01-01T12:00:00Z" }, { "version": 2, "created_at": "2023-02-01T12:00:00Z" } ], "compilations": [ { "resolution_plan_id": "res-001", "brief_version_at_compilation": 1, "created_at": "2023-01-15T12:00:00Z" } ], "provenance_capabilities": [ "intent.captured", "intent.shaped", "intent.compiled", "intent.provisioning", "intent.scaffolded" ], "query_provenance": { "post": "/v1/provenance/query", "hint": "Filter events by org and capability names above; resource id equals intent_brief_id where emitted." } } } } } } }, "400": { "description": "Bad Request - The request was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters did not match the expected format. Please verify your input and try again." } } } } } }, "401": { "description": "Unauthorized - Org context required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/auth-required", "title": "Unauthorized", "status": 401, "detail": "Org context required. Ensure you are authenticated and the proper headers are included." } } } } } }, "403": { "description": "Forbidden - You do not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this Intent's audit trail. Please ensure your permissions are correct." } } } } } }, "404": { "description": "Not Found - The specified Intent was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The Intent with the specified ID was not found. Please verify the ID and try again." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/intent/:id": { "patch": { "summary": "Update an existing intent brief", "description": "Refine and evolve your organization's strategic intents with precision. This endpoint allows you to update specific details of an existing intent brief, ensuring that your plans remain aligned with the latest insights and operational changes.", "operationId": "updateIntentBrief", "tags": [ "Intent Management", "Strategic Planning" ], "x-code-hash": "7f66e352eb5674aa", "x-generated-at": "2026-04-26T23:20:20.988Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "type": "object", "properties": { "title": { "type": "string" }, "clarified_objective": { "type": "string" }, "desired_outcome": { "type": "string" }, "scope": { "type": "string" }, "intent_family": { "type": "string" }, "trigger": { "type": "string" }, "actors": { "type": "object" }, "systems": { "type": "object" }, "inputs": { "type": "object" }, "outputs": { "type": "object" }, "constraints": { "type": "object" }, "assumptions": { "type": "object" }, "recommended_artifact_type": { "type": "string" }, "artifact_type_rationale": { "type": "string" }, "confidence": { "type": "object" }, "status": { "type": "string" } } } } }, "examples": { "updateintentbriefexample": { "summary": "UpdateIntentBriefExample", "description": "An example showing an update to the title and desired outcome of an intent brief.", "value": { "brief": { "title": "Streamlined Workflow Enhancement", "desired_outcome": "Improved processing efficiency by 20%" } } } } } } }, "responses": { "200": { "description": "Intent brief updated successfully, with details of the new state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "type": "object", "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "creator_did": { "type": "string" }, "title": { "type": "string" }, "clarified_objective": { "type": "string" }, "desired_outcome": { "type": "string" }, "scope": { "type": "string" }, "intent_family": { "type": "string" }, "trigger": { "type": "string" }, "actors": { "type": "object" }, "systems": { "type": "object" }, "inputs": { "type": "object" }, "outputs": { "type": "object" }, "constraints": { "type": "object" }, "assumptions": { "type": "object" }, "recommended_artifact_type": { "type": "string" }, "artifact_type_rationale": { "type": "string" }, "confidence": { "type": "object" }, "status": { "type": "string" }, "raw_input": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer" } } }, "recompile_required": { "type": "boolean" } } }, "examples": { "successfulupdateexample": { "summary": "SuccessfulUpdateExample", "description": "Response showing the updated intent brief details and compilation requirement.", "value": { "brief": { "id": "12345", "workspace_id": "acme_workspace", "creator_did": "did:human:acme_agent", "title": "Streamlined Workflow Enhancement", "clarified_objective": "Align operations with new efficiency standards", "desired_outcome": "Improved processing efficiency by 20%", "scope": "Department-wide", "intent_family": "Operational Efficiency", "trigger": "Quarterly Review", "actors": {}, "systems": {}, "inputs": {}, "outputs": {}, "constraints": {}, "assumptions": {}, "recommended_artifact_type": "Report", "artifact_type_rationale": "To document changes", "confidence": {}, "status": "In Progress", "raw_input": "Initial input data", "updated_at": "2023-10-01T12:34:56.789Z", "version": 2 }, "recompile_required": true } } } } } }, "400": { "description": "Invalid request data; could not process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication is required but was not provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Action forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The intent brief was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "A server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/intent/:id/shape": { "patch": { "summary": "Refine an intent's shape and details", "description": "This endpoint orchestrates the refinement of an intent, ensuring it aligns with the latest organizational goals and AI safety protocols. By updating an intent's shape, HUMAN ensures that AI-driven tasks remain relevant and precise, guiding both machines and their human counterparts toward success.", "operationId": "patchIntentShape", "tags": [ "Intent Management", "Human-AI Orchestration" ], "x-code-hash": "427eccef3a287402", "x-generated-at": "2026-04-27T16:24:56.558Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "utterance": { "type": "string", "description": "A user-provided follow-up statement to further clarify or refine the intent." } }, "required": [ "utterance" ] }, "examples": { "clarify_intent_with_user_follow-up": { "summary": "Clarify intent with user follow-up", "description": "Refining the intent with a user's additional input for better task accuracy.", "value": { "utterance": "Please ensure this invoice is processed with priority." } } } } } }, "responses": { "200": { "description": "The intent was successfully refined and updated with the latest details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "type": "object", "description": "The refined intent brief containing updated details.", "properties": { "title": { "type": "string" }, "clarified_objective": { "type": "string" }, "desired_outcome": { "type": "string" }, "intent_family": { "type": "string" }, "version": { "type": "integer" }, "confidence": { "type": "object" } } }, "needs_clarification": { "type": "boolean", "description": "Indicates if further clarification is required." }, "clarification_questions": { "type": "array", "items": { "type": "string" }, "description": "Questions generated to aid in further refining the intent." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Malformed request due to invalid input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-input", "title": "Malformed Request", "status": 400, "detail": "The 'utterance' field is required and must be a string.", "errors": [ "Missing required property: utterance" ] } } } } } }, "401": { "description": "Authentication is required to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Authentication credentials were not provided. Ensure you are logged in and try again." } } } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to modify this intent. Check your access rights and try again." } } } } } }, "404": { "description": "The intent was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified intent ID does not exist. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/intent/:id/compile": { "post": { "summary": "Compile AI task intent brief", "description": "This endpoint transforms a raw intent brief into an actionable resolution plan. It orchestrates AI capabilities to meet organizational needs, ensuring each intent is feasible and compliant. Imagine a team at 'acme' orchestrating invoice approvals with AI precision and human oversight.", "operationId": "compileIntentBrief", "tags": [ "Intent Management", "AI Orchestration" ], "x-code-hash": "34282d7e80d5b2e8", "x-generated-at": "2026-04-26T23:20:49.730Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "override_capability_ids": { "type": "array", "items": { "type": "string", "format": "capability://" } } } }, "examples": { "override_capabilities_example": { "summary": "Override Capabilities Example", "description": "Overrides default capabilities with specified ones for a custom AI task resolution.", "value": { "override_capability_ids": [ "capability://acme.ai.processing", "capability://acme.ai.analysis" ] } } } } } }, "responses": { "200": { "description": "Successfully compiled the intent brief into a resolution plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resolution_plan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "brief_version_at_compilation": { "type": "string" }, "stale": { "type": "boolean" }, "installed_capabilities_used": { "type": "array", "items": { "type": "string" } }, "missing_capabilities": { "type": "array", "items": { "type": "string" } }, "optional_capabilities": { "type": "array", "items": { "type": "string" } }, "recommended_path": { "type": "array", "items": { "type": "string" } }, "candidate_paths": { "type": "array", "items": { "type": "string" } }, "existing_similar_assets": { "type": "array", "items": { "type": "string" } }, "recommended_path_blocked": { "type": "boolean" }, "policy_block_reason": { "type": [ "string", "null" ] }, "policy_safe_alternative": { "type": [ "string", "null" ] }, "cost_summary": { "type": "object" }, "policy_notes": { "type": "object" }, "approval_requirements": { "type": "object" }, "explanation": { "type": "string" } } }, "brief_id": { "type": "string" } } }, "examples": { "successful_compilation": { "summary": "Successful Compilation", "description": "Compilation of an intent brief into a resolution plan for invoice processing.", "value": { "resolution_plan": { "id": "123e4567-e89b-12d3-a456-426614174000", "brief_version_at_compilation": "v1.2", "stale": false, "installed_capabilities_used": [ "capability://acme.ai.processing" ], "missing_capabilities": [], "optional_capabilities": [ "capability://acme.ai.analysis" ], "recommended_path": [ "path1", "path2" ], "candidate_paths": [ "path1", "path2" ], "existing_similar_assets": [], "recommended_path_blocked": false, "policy_block_reason": null, "policy_safe_alternative": null, "cost_summary": {}, "policy_notes": {}, "approval_requirements": {}, "explanation": "This plan optimizes resource allocation for invoice processing." }, "brief_id": "intent123" } } } } } }, "400": { "description": "Request validation error due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication error due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Permission error due to unauthorized access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found error when the intent brief does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/intent/:id/provision": { "post": { "summary": "Provision an Intent Capability Plan", "description": "Embark on the journey of orchestrating human and AI collaboration by provisioning an intent capability plan. This endpoint transforms a compiled intent into actionable tasks, ensuring safety and alignment with your organization's unique skills and permissions.", "operationId": "provisionIntentCapabilityPlan", "tags": [ "Intents", "Provisioning" ], "x-code-hash": "abce2a8932e74fef", "x-generated-at": "2026-04-27T16:25:29.006Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selected_path_label": { "type": "string", "description": "The label of the capability path selected for provisioning." } }, "required": [ "selected_path_label" ] }, "examples": { "provision_a_specific_path": { "summary": "Provision a specific path", "description": "Provisions the capability plan using a specified path label.", "value": { "selected_path_label": "fast-track-integration" } } } } } }, "responses": { "200": { "description": "The intent capability plan was successfully provisioned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provisioning_request": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the provisioning request." }, "selected_path_label": { "type": "string", "description": "The label of the capability path that was provisioned." }, "requested_installs": { "type": "array", "items": { "type": "object", "properties": { "marketplace_asset_id": { "type": "string" }, "capability_id": { "type": "string" }, "requires_explicit_approval": { "type": "boolean" } } } }, "requested_auth": { "type": "object" }, "requested_permissions": { "type": "object" }, "approval_scope": { "type": "string" }, "cost_exposure": { "type": "object" } } } } }, "examples": { "successful_provision": { "summary": "Successful Provision", "value": { "provisioning_request": { "id": "123e4567-e89b-12d3-a456-426614174000", "selected_path_label": "fast-track-integration", "requested_installs": [ { "marketplace_asset_id": "asset-001", "capability_id": "cap-123", "requires_explicit_approval": true } ], "requested_auth": {}, "requested_permissions": {}, "approval_scope": "team", "cost_exposure": {} } } } } } } }, "400": { "description": "The request was invalid. This often occurs when a required step is skipped.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "compile_required": { "summary": "Compile Required", "value": { "type": "https://haio.run/errors/validation", "title": "Compile required", "status": 400, "detail": "Call POST /v1/intent/:id/compile first." } } } } } }, "401": { "description": "Authentication failed due to missing organizational context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "org_context_required": { "summary": "Org Context Required", "value": { "type": "https://haio.run/errors/auth", "title": "Authentication Error", "status": 401, "detail": "Org context required" } } } } } }, "404": { "description": "The specified intent was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "intent_not_found": { "summary": "Intent Not Found", "value": { "type": "https://haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Intent not found" } } } } } }, "409": { "description": "The capability resolution plan is outdated and needs recompilation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "plan_stale": { "summary": "Plan Stale", "value": { "type": "https://haio.run/errors/plan-stale", "title": "Plan is stale", "status": 409, "detail": "The capability resolution plan is stale. Call POST /v1/intent/:id/compile to regenerate before provisioning." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://haio.run/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/intent/:id/scaffold": { "post": { "summary": "Generate an Intent Scaffold", "description": "This endpoint breathes life into raw intent by transforming it into a scaffold. By orchestrating organizational capabilities and aligning them with intent, it ensures a seamless path from concept to execution. It's where ideas meet structured implementation.", "operationId": "postIntentScaffold", "tags": [ "Intent", "Scaffold" ], "x-code-hash": "0fa1ed2f90174dbf", "x-generated-at": "2026-04-26T23:21:10.054Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "override_capability_ids": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "A list of capability URIs to override the default selection." } } }, "examples": { "override_capabilities_example": { "summary": "Override Capabilities Example", "description": "Overrides default capabilities with specified URIs.", "value": { "override_capability_ids": [ "capability://acme/skill/invoice-processing", "capability://acme/skill/data-entry" ] } } } } } }, "responses": { "200": { "description": "The scaffold was successfully created, providing a structured plan for the intent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scaffold": { "type": "object", "properties": { "kind": { "type": "string", "description": "The type of scaffold generated." } } } } }, "examples": { "default": { "summary": "Example", "value": { "scaffold": { "kind": "standard" } } } } } } }, "400": { "description": "The request format was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided data structure is incorrect. Ensure 'override_capability_ids' is an array of URIs.", "errors": [ "override_capability_ids must be an array of strings in URI format." ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Org context required. Please authenticate your request with valid credentials." } } } } } }, "403": { "description": "The authenticated user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the required permissions to scaffold this intent." } } } } } }, "404": { "description": "The intent specified by the ID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified intent was not found. Verify the intent ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/server-error", "title": "Server Error", "status": 500, "detail": "An internal server error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/intent/:id/simulate": { "post": { "summary": "Simulate intent execution for analysis", "description": "Dive into the future with intent simulations, allowing organizations to preview the outcomes of their strategies before they are executed. This endpoint exists to empower decision-makers, providing them insight and foresight by simulating complex scenarios using the HUMAN platform's orchestration capabilities.", "operationId": "simulateIntentExecution", "tags": [ "Intent", "Simulation" ], "x-code-hash": "f4ab9586c78dad2b", "x-generated-at": "2026-04-26T23:21:21.824Z", "responses": { "200": { "description": "Successfully simulated the intent, returning the anticipated results of the strategy without real-world execution.", "content": { "application/json": { "schema": { "type": "object", "properties": { "simulation": { "type": "object", "description": "The results of the simulated intent execution", "properties": { "outcome": { "type": "string", "description": "A narrative of the simulated outcome" }, "successRate": { "type": "number", "format": "float", "description": "The probability of success based on current data" } } } } }, "examples": { "successful_simulation": { "summary": "Successful Simulation", "description": "Simulates a strategy for the 'acme' organization to process invoices, projecting high success.", "value": { "simulation": { "outcome": "The invoice processing strategy is likely to succeed with minimal delays.", "successRate": 0.95 } } } } } } }, "400": { "description": "Bad Request - The request parameters are invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request_parameters": { "summary": "Invalid Request Parameters", "description": "The request was made with insufficient or incorrect parameters.", "value": { "type": "https://humanprotocol.org/errors/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "The 'id' parameter is required and must be a valid intent identifier.", "errors": [ "Missing 'id' parameter" ] } } } } } }, "401": { "description": "Unauthorized - Missing or invalid organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "authentication_error": { "summary": "Authentication Error", "description": "The request lacked valid authentication credentials.", "value": { "type": "https://humanprotocol.org/errors/authentication", "title": "Authentication Error", "status": 401, "detail": "Org context required for simulation. Please authenticate your request with a valid organization DID." } } } } } }, "403": { "description": "Forbidden - The organization does not have permission to simulate this intent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "The organization is not permitted to perform this simulation.", "value": { "type": "https://humanprotocol.org/errors/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have the necessary permissions to simulate this intent. Ensure your organization has the appropriate access rights." } } } } } }, "404": { "description": "Not Found - The specified intent could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "intent_not_found": { "summary": "Intent Not Found", "description": "The intent specified by the 'id' parameter was not found in the database.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Intent Not Found", "status": 404, "detail": "Intent with the specified ID does not exist. Verify the ID and try again." } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A server-side issue prevented the simulation from completing.", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try your request again later or contact support if the problem persists." } } } } } } } } }, "/v1/admin/intent-activity": { "get": { "summary": "Retrieve Intent Activity", "description": "Explore the vibrant tapestry of activities within your organization, dynamically orchestrating human-AI interactions. This endpoint exists to empower administrators by providing a window into the AI intent landscape, allowing for data-driven insights and strategic decision-making.", "operationId": "getIntentActivity", "tags": [ "Admin", "Intent Management" ], "x-code-hash": "a5e1ec4874c2983e", "x-generated-at": "2026-04-26T23:21:34.307Z", "responses": { "200": { "description": "Paginated list of intent activities successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "source_surface": { "type": "string" }, "modality": { "type": "string" }, "intent_family": { "type": "string" }, "creator_did": { "type": "string" }, "version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "status", "source_surface", "modality", "intent_family", "creator_did", "version", "created_at", "updated_at" ] } }, "limit": { "type": "integer" }, "cursorFields": { "type": "array", "items": { "type": "string" } }, "hasMore": { "type": "boolean" } }, "required": [ "data", "limit", "cursorFields", "hasMore" ] }, "examples": { "example_with_pagination": { "summary": "Example with Pagination", "description": "Retrieving the first page of intent activities for the 'acme' organization.", "value": { "data": [ { "id": "intent-abc123", "title": "Process Invoices", "status": "active", "source_surface": "web", "modality": "text", "intent_family": "finance", "creator_did": "did:human:12345", "version": "1.0", "created_at": "2023-10-01T12:00:00Z", "updated_at": "2023-10-02T12:00:00Z" } ], "limit": 10, "cursorFields": [ "updated_at", "id" ], "hasMore": false } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor": { "summary": "Invalid Cursor", "description": "Example error when cursor is malformed.", "value": { "type": "https://example.com/probs/invalid-cursor", "title": "Invalid cursor parameter", "status": 400, "detail": "The cursor provided is not valid. Ensure it is correctly formatted and try again." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "Occurs when the org_did is not provided in the request.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication required", "status": 401, "detail": "Org context (org_did) is required to access this endpoint. Please authenticate and try again." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "User does not have the required permissions to access the intent activity.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to view this data. Contact your administrator for access." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "The requested resource could not be found.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested intent activity could not be found. Verify the resource ID and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/control-plane/marketplace/capabilities": { "get": { "summary": "Retrieve active capabilities by intent family", "description": "Dive into the world of HUMAN's orchestration, where each capability is a piece in the grand puzzle of AI and human collaboration. This endpoint fetches active capabilities tailored to a specified intent family, allowing organizations to seamlessly integrate the right skills for their needs.", "operationId": "getMarketplaceCapabilities", "tags": [ "Marketplace", "Capabilities" ], "x-code-hash": "a8961f1d1f11ae10", "x-generated-at": "2026-04-26T23:21:50.032Z", "responses": { "200": { "description": "Successfully retrieved capability definitions for the specified intent family.", "content": { "application/json": { "schema": { "type": "object", "properties": { "intent_family": { "type": "string", "description": "The intent family for which capabilities are retrieved." }, "count": { "type": "integer", "description": "Number of capabilities found." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique capability identifier." }, "canonical_name": { "type": "string", "description": "The canonical name of the capability." }, "description": { "type": "string", "description": "A brief description of the capability." }, "supported_intent_families": { "type": "array", "items": { "type": "string" }, "description": "Intent families supported by this capability." }, "supported_artifact_types": { "type": "array", "items": { "type": "string" }, "description": "Artifact types that the capability supports." }, "trust_level": { "type": "string", "description": "Trust level assigned to this capability." }, "installability": { "type": "string", "description": "Installability status of the capability." }, "trigger_event_types": { "type": "array", "items": { "type": "string" }, "description": "Types of events that can trigger this capability." }, "produces_signal_kinds": { "type": "array", "items": { "type": "string" }, "description": "Signal kinds produced by this capability." }, "explain_why": { "type": "string", "description": "Explains why the capability is relevant to the provided intent family.", "nullable": true } } } } } }, "examples": { "retrieve_capabilities_for_automation": { "summary": "Retrieve capabilities for automation", "description": "Shows capabilities for the 'set_up_automation' intent family.", "value": { "intent_family": "set_up_automation", "count": 2, "data": [ { "id": "cap-automation-001", "canonical_name": "acme.auto.setup", "description": "Automates initial setup processes.", "supported_intent_families": [ "set_up_automation" ], "supported_artifact_types": [ "config", "script" ], "trust_level": "high", "installability": "self-installable", "trigger_event_types": [ "onboarding" ], "produces_signal_kinds": [ "setup_complete" ], "explain_why": "This capability_definition lists supported_intent_families including \"set_up_automation\" and is active." } ] } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_intent_family": { "summary": "Missing intent family", "description": "Error when 'intent_family' is not provided.", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid Query Parameter", "status": 400, "detail": "intent_family is required (e.g. set_up_automation, monitor_and_alert).", "errors": [ { "field": "intent_family", "code": "REQUIRED_QUERY_PARAM", "message": "intent_family is required (e.g. set_up_automation, monitor_and_alert)", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "Error when accessing without valid authentication.", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "description": "Error when user lacks necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Contact your administrator for access." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "Error when the requested resource does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found. Please check the endpoint and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "description": "Error when an unexpected condition was encountered.", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later." } } } } } } } } }, "/v1/academy/gap-analysis": { "get": { "summary": "Analyze capability gaps for target roles", "description": "The gap analysis endpoint evaluates the Learning Capability Evidence Framework (LCEF) portfolio against a specified target role or capability. By understanding these gaps, organizations can tailor training to help individuals achieve their desired roles.", "operationId": "getAcademyGapAnalysis", "tags": [ "Academy", "Analysis" ], "x-code-hash": "d59f0a09b4ff81e6", "x-generated-at": "2026-04-27T16:24:31.847Z", "responses": { "200": { "description": "Returns the capability gap summary and next steps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "target_role": { "type": "string", "nullable": true, "description": "The target role or capability being analyzed." }, "gap_summary": { "type": "object", "properties": { "weak_tier_only": { "type": "boolean", "description": "Indicates if only weak tier evidence exists (C or D tiers)." }, "portfolio": { "type": "object", "description": "Detailed portfolio analysis results." } } }, "next_best_proof": { "type": "array", "items": { "type": "object", "properties": { "evidence_class": { "type": "string", "description": "Class of evidence required next." }, "action": { "type": "string", "description": "Recommended action to close the gap." } } } } } }, "examples": { "gap_analysis_for_data_analyst_role": { "summary": "Gap Analysis for Data Analyst Role", "description": "Evaluates the gaps in a portfolio for transitioning to a Data Analyst role.", "value": { "target_role": "Data Analyst", "gap_summary": { "weak_tier_only": true, "portfolio": { "by_tier": { "A": 0, "B": 0, "C": 2, "D": 1 } } }, "next_best_proof": [ { "evidence_class": "structured_learning", "action": "complete_academy_or_import_course" }, { "evidence_class": "live_operational_proof", "action": "complete_workforce_tasks" } ] } } } } } }, "400": { "description": "Bad Request due to missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "The request is missing required parameters.", "errors": [ { "field": "passport_did", "code": "REQUIRED", "message": "passport_did query parameter required" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Invalid API key provided. Ensure your API key is correct and retry." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Check your user permissions or contact support." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found. Verify the endpoint and parameters are correct." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human.com/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Try your request again later or contact support if the issue persists." } } } } } } } } }, "/v1/evidence": { "post": { "summary": "Submit evidence for human-AI interactions", "description": "This endpoint allows you to submit evidence related to human-AI interactions, ensuring all interactions are ethically documented and traceable. By importing evidence, you maintain a transparent and accountable system where every decision can be reviewed and audited.", "operationId": "submitEvidence", "tags": [ "Human-AI Orchestration", "Evidence Management" ], "x-code-hash": "e68aa803f0986ae8", "x-generated-at": "2026-04-27T16:54:29.357Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "consent_basis": { "type": "string", "description": "The legal basis for consent to process this evidence." }, "target_passport_did": { "type": "string", "description": "Decentralized Identifier of the human subject related to the evidence." }, "evidence_details": { "type": "object", "description": "Detailed information about the evidence being submitted." } }, "required": [ "consent_basis" ] }, "examples": { "submit_evidence_for_invoice_processing": { "summary": "Submit Evidence for Invoice Processing", "description": "An example showing how to submit evidence for an AI processing an invoice.", "value": { "consent_basis": "consent", "target_passport_did": "did:human:1234abcd", "evidence_details": { "task": "invoice_processing", "timestamp": "2023-10-01T12:00:00Z", "outcome": "success", "details": "AI reviewed and approved invoice #INV-1001" } } } } } } }, "responses": { "201": { "description": "Evidence successfully submitted and recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_record": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the recorded evidence." }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of when the evidence was recorded." } } } } }, "examples": { "successful_submission": { "summary": "Successful Submission", "description": "An example of a successful evidence submission.", "value": { "evidence_record": { "id": "evid-5678efgh", "timestamp": "2023-10-01T12:05:00Z" } } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_json": { "summary": "Invalid JSON", "description": "Example of an error when the request body is not valid JSON.", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid JSON payload", "status": 400, "detail": "Request body must be a JSON object", "errors": [ { "field": "body", "code": "INVALID_JSON", "message": "Request body must be a JSON object" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing Credentials", "description": "Example of an error when authentication credentials are missing.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or invalid" } } } } } }, "403": { "description": "Forbidden access, user lacks necessary permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Example of an error when the user does not have permission.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action" } } } } } }, "404": { "description": "Resource not found, possibly an incorrect endpoint", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "endpoint_not_found": { "summary": "Endpoint Not Found", "description": "Example of an error when a resource is not found.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found" } } } } } }, "409": { "description": "Conflict error due to existing evidence for the event", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "evidence_conflict": { "summary": "Evidence Conflict", "description": "Example of a conflict when evidence for the event already exists.", "value": { "type": "https://example.com/probs/conflict", "title": "Conflict", "status": 409, "detail": "Evidence already exists for this event", "errors": [ { "existing_evidence_id": "evid-1234abcd" } ] } } } } } }, "500": { "description": "Internal server error, something went wrong on the server", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Example of a server error response.", "value": { "type": "https://example.com/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server" } } } } } } } }, "get": { "summary": "Retrieve evidence linked to a Passport", "description": "Delve into the rich tapestry of evidence associated with a given Passport. This endpoint empowers you to explore and filter evidence by class, strength, state, and outcome — revealing the provenance behind decisions and interactions within the HUMAN network.", "operationId": "getEvidence", "tags": [ "Evidence", "Passport" ], "x-code-hash": "cd66230edb362f38", "x-generated-at": "2026-04-27T16:56:09.407Z", "responses": { "200": { "description": "Successfully retrieved evidence for the specified Passport, with optional pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the evidence." }, "class": { "type": "string", "description": "The classification of the evidence." }, "strength_tier": { "type": "string", "description": "Strength tier of the evidence." }, "ingestion_state": { "type": "string", "description": "Current state of evidence ingestion." }, "verification_outcome": { "type": "string", "description": "Outcome of evidence verification." } } } }, "limit": { "type": "integer", "description": "Maximum number of items returned." }, "cursorField": { "type": "string", "description": "Field used to paginate results." }, "hasMore": { "type": "boolean", "description": "Indicates if more results are available." } } }, "examples": { "evidence_list_example": { "summary": "Evidence List Example", "description": "A list of evidence items for a specific Passport.", "value": { "data": [ { "id": "evidence123", "class": "verification", "strength_tier": "high", "ingestion_state": "processed", "verification_outcome": "approved" } ], "limit": 10, "cursorField": "id", "hasMore": false } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_did": { "summary": "Missing passport_did", "value": { "type": "https://humanprotocol.com/errors/validation", "title": "Validation Error", "status": 400, "detail": "The passport_did parameter is required.", "errors": [ { "field": "passport_did", "code": "REQUIRED", "message": "passport_did required" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://humanprotocol.com/errors/auth", "title": "Unauthorized", "status": 401, "detail": "Invalid or missing authentication token." } } } } } }, "403": { "description": "Forbidden access to the requested evidence.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://humanprotocol.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Access to this evidence is forbidden." } } } } } }, "404": { "description": "Passport not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found": { "summary": "Passport Not Found", "value": { "type": "https://humanprotocol.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "No Passport found with the specified DID." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanprotocol.com/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected server error occurred. Please try again later." } } } } } } } } }, "/v1/evidence/batch": { "post": { "summary": "Batch submit evidence for processing", "description": "Harness the collective power of data by submitting multiple evidence items in one go. This endpoint enables organizations to efficiently process evidence with AI-assured safety, ensuring each piece meets consent requirements and tracks its provenance.", "operationId": "submitEvidenceBatch", "tags": [ "Evidence", "BatchProcessing" ], "x-code-hash": "de93182248c37ac4", "x-generated-at": "2026-04-27T16:54:45.590Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "intake_event_id": { "type": "string", "description": "Unique identifier for the intake event" }, "consent_basis": { "type": "string", "description": "Basis for consent, required for processing" }, "data": { "type": "object", "description": "The evidence data, format varies per use case" } }, "required": [ "intake_event_id", "consent_basis" ] } } }, "required": [ "items" ] }, "examples": { "evidence_batch_submission": { "summary": "Evidence Batch Submission", "description": "Batch of evidence items submitted by Acme Corp for processing.", "value": { "items": [ { "intake_event_id": "evt-1234", "consent_basis": "contractual", "data": { "document_type": "invoice", "amount": 1500, "currency": "USD" } }, { "intake_event_id": "evt-5678", "consent_basis": "legitimate_interest", "data": { "document_type": "receipt", "amount": 200, "currency": "USD" } } ] } } } } } }, "responses": { "200": { "description": "Successfully processed batch of evidence items", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "intake_event_id": { "type": "string", "description": "ID of the intake event processed" }, "id": { "type": "string", "description": "Generated ID for the processed evidence item" }, "error": { "type": "string", "description": "Error message if processing failed" } } } } } }, "examples": { "default": { "summary": "Example", "value": { "results": [ { "intake_event_id": "evt-1234", "id": "rec-9876" }, { "intake_event_id": "evt-5678", "error": "consent_basis_required" } ] } } } } } }, "400": { "description": "Request validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/validation", "title": "Invalid request", "status": 400, "detail": "The request body is not valid JSON.", "errors": [ { "field": "items", "code": "REQUIRED", "message": "items array required" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "Access token is missing or invalid. Please provide a valid token." } } } } } }, "403": { "description": "Forbidden access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/evidence/intake": { "post": { "summary": "Intake new evidence into the system", "description": "In the intricate ballet of data and verification, this endpoint serves as the gatekeeper for introducing new evidence into the HUMAN ecosystem. It ensures that each piece of evidence submitted is not only accurately captured but also aligns with the necessary consent protocols, safeguarding both the integrity and privacy of the entities involved.", "operationId": "postEvidenceIntake", "tags": [ "Evidence Management", "Data Integrity" ], "x-code-hash": "6f79a950aedfeadf", "x-generated-at": "2026-04-27T16:54:59.746Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intake_event_id": { "type": "string", "description": "Unique identifier for the intake event." }, "schema_version": { "type": "string", "description": "Version of the schema used for this intake." }, "consent_basis": { "type": "string", "description": "Legal basis for data consent." } }, "required": [ "intake_event_id", "schema_version", "consent_basis" ] }, "examples": { "standard_evidence_intake": { "summary": "Standard Evidence Intake", "description": "A typical request to intake evidence with all necessary fields filled.", "value": { "intake_event_id": "evt_123456789", "schema_version": "1.0.0", "consent_basis": "informed_consent" } } } } } }, "responses": { "200": { "description": "Successfully processed the evidence intake.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_record": { "type": "object", "description": "Details of the processed evidence record." }, "created": { "type": "boolean", "description": "Indicates if the evidence was newly created." } } }, "examples": { "default": { "summary": "Example", "value": { "evidence_record": { "id": "rec_987654321", "status": "verified" }, "created": true } } } } } }, "400": { "description": "Invalid request due to missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/invalid-input", "title": "Invalid Request", "status": 400, "detail": "intake_event_id and schema_version required", "errors": [ { "field": "intake_envelope", "code": "INVALID", "message": "intake_event_id and schema_version required" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Invalid authentication credentials provided." } } } } } }, "403": { "description": "Forbidden access due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error due to an unexpected issue.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/evidence/portfolio": { "get": { "summary": "Retrieve Evidence Portfolio by Passport", "description": "Uncover the rich tapestry of skills and experiences associated with a cryptographic identity. This endpoint is your gateway to accessing a consolidated view of an individual's capabilities, woven together from their unique Passport DID.", "operationId": "getEvidencePortfolio", "tags": [ "Evidence", "Portfolio" ], "x-code-hash": "c01bf83f287cda13", "x-generated-at": "2026-04-27T16:55:12.131Z", "responses": { "200": { "description": "Successfully retrieved the evidence portfolio for the given Passport DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "portfolio": { "type": "object", "additionalProperties": { "type": "object", "properties": { "skill": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } } }, "required": [ "skill", "evidence" ] } } }, "required": [ "portfolio" ] }, "examples": { "acme_corporation_portfolio": { "summary": "Acme Corporation Portfolio", "description": "Portfolio showcasing skills and evidence for Acme Corporation's agent.", "value": { "portfolio": { "agent:1234": { "skill": "Data Analysis", "evidence": [ "project://acme/invoice-processing", "cert://acme/data-science-certification" ] } } } } } } } }, "400": { "description": "The request was malformed or missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_did": { "summary": "Missing Passport DID", "value": { "type": "/errors/validation", "title": "Invalid Request", "status": 400, "detail": "passport_did required", "errors": [ { "field": "passport_did", "code": "REQUIRED", "message": "passport_did required" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_authentication_provided": { "summary": "No Authentication Provided", "value": { "type": "/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect." } } } } } }, "403": { "description": "The client does not have access rights to the content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "/errors/notfound", "title": "Not Found", "status": 404, "detail": "The resource you are looking for does not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_failure": { "summary": "Server Failure", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/evidence/eligibility": { "get": { "summary": "Retrieve eligibility snapshot for opportunities", "description": "In the fast-paced world of human-AI collaboration, understanding your eligibility for various opportunities is crucial. This endpoint allows users to fetch the latest eligibility snapshot for a given opportunity type based on their cryptographic identity, ensuring informed decision-making and efficient task allocation.", "operationId": "getEligibilitySnapshot", "tags": [ "Eligibility", "HumanOS" ], "x-code-hash": "b7fd296df3a4bdd5", "x-generated-at": "2026-04-27T16:55:25.829Z", "responses": { "200": { "description": "Successfully retrieves the latest eligibility snapshot for the specified opportunity type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "Decentralized Identifier of the passport" }, "opportunity_type": { "type": "string", "description": "Type of opportunity evaluated" }, "eligibility_status": { "type": "string", "description": "The current eligibility status" }, "computed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the snapshot was computed" } } }, "examples": { "eligibility_for_workforce_task": { "summary": "Eligibility for workforce task", "description": "Shows eligibility status for a workforce task based on the latest snapshot.", "value": { "passport_did": "did:human:acme-john-doe", "opportunity_type": "workforce_task", "eligibility_status": "eligible", "computed_at": "2023-10-01T12:34:56Z" } } } } } }, "400": { "description": "Bad Request. The request is missing required parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_did": { "summary": "Missing passport_did", "description": "The request failed due to a missing passport_did parameter.", "value": { "type": "https://docs.humanprotocol.org/errors#missing-parameter", "title": "Bad Request", "status": 400, "detail": "passport_did required", "errors": [ { "field": "passport_did", "code": "REQUIRED", "message": "passport_did required" } ] } } } } } }, "401": { "description": "Unauthorized access. Authentication credentials are missing or invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid credentials", "description": "The request failed due to invalid authentication credentials.", "value": { "type": "https://docs.humanprotocol.org/errors#authentication-failure", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden. The user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "description": "The request failed because the user lacks necessary permissions.", "value": { "type": "https://docs.humanprotocol.org/errors#permission-denied", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not Found. No eligibility snapshot exists for the specified query.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_eligibility_snapshot": { "summary": "No eligibility snapshot", "description": "The eligibility snapshot could not be found, and the user is advised to refresh.", "value": { "type": "https://docs.humanprotocol.org/errors#not-found", "title": "Not Found", "status": 404, "detail": "No eligibility snapshot; call POST /v1/evidence/eligibility/refresh" } } } } } }, "500": { "description": "Internal Server Error. An unexpected condition occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://docs.humanprotocol.org/errors#internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/evidence/eligibility/refresh": { "post": { "summary": "Refresh Eligibility Evidence Snapshot", "description": "In the dynamic world of Human-AI collaboration, it's crucial to ensure that opportunities are matched with the right skills at the right time. This endpoint recalculates the eligibility evidence for a specific opportunity type, ensuring that your HUMAN Passport reflects the most current skill-to-task alignment and readiness for new challenges.", "operationId": "refreshEligibilityEvidenceSnapshot", "tags": [ "Eligibility", "HUMAN Protocol" ], "x-code-hash": "3ab850157c6dbd96", "x-generated-at": "2026-04-27T16:55:42.086Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "The Decentralized Identifier (DID) of the HUMAN Passport." }, "opportunity_type": { "type": "string", "description": "The type of opportunity for which to refresh eligibility.", "default": "workforce_task" } }, "required": [ "passport_did" ] }, "examples": { "refresh_workforce_task_eligibility": { "summary": "Refresh Workforce Task Eligibility", "description": "Recomputing eligibility for a workforce task using a specific passport DID.", "value": { "passport_did": "did:human:123456789abcdefghi", "opportunity_type": "workforce_task" } } } } } }, "responses": { "201": { "description": "Eligibility evidence snapshot successfully refreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "The DID of the HUMAN Passport." }, "opportunity_type": { "type": "string", "description": "Type of the opportunity." }, "computed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the eligibility was last computed." }, "eligibility_status": { "type": "string", "description": "Current eligibility status." } } }, "examples": { "successful_eligibility_refresh": { "summary": "Successful Eligibility Refresh", "value": { "passport_did": "did:human:123456789abcdefghi", "opportunity_type": "workforce_task", "computed_at": "2023-10-05T14:48:00.000Z", "eligibility_status": "eligible" } } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_did": { "summary": "Missing Passport DID", "value": { "type": "https://humanprotocol.org/errors/validation", "title": "Validation Error", "status": 400, "detail": "The request could not be processed due to validation errors.", "errors": [ { "field": "passport_did", "code": "REQUIRED", "message": "passport_did required" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "value": { "type": "https://humanprotocol.org/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Invalid authentication credentials provided." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://humanprotocol.org/errors/authorization", "title": "Forbidden", "status": 403, "detail": "You do not have permission to refresh eligibility." } } } } } }, "404": { "description": "The resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error due to unexpected circumstances.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "https://humanprotocol.org/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } } }, "/v1/evidence/audit/:routing_decision_id": { "get": { "summary": "Retrieve evidence audit by routing decision", "description": "Dive into the past decisions of our AI orchestrated tasks with this endpoint. By querying the audit trail of routing decisions, you gain insights into task assignments, ensuring transparency and accountability in AI-human collaborations.", "operationId": "getEvidenceAuditByRoutingDecisionId", "tags": [ "Audit", "HumanOS" ], "x-code-hash": "d888abdd19a75d2f", "x-generated-at": "2026-04-27T16:55:56.322Z", "responses": { "200": { "description": "Successfully retrieved the audit trail for the specified routing decision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence": { "type": "object", "description": "The payload containing the audit evidence.", "additionalProperties": true } } }, "examples": { "successful_audit_retrieval": { "summary": "Successful Audit Retrieval", "description": "An audit record showing how a task was routed for the given decision ID.", "value": { "evidence": { "task_id": "task-1234", "decision_maker": "ai-agent-42", "timestamp": "2023-11-01T13:45:30Z", "decision": "Approved by AI", "details": { "priority": "high", "assigned_to": "agent-jdoe" } } } } } } } }, "400": { "description": "The request was malformed, typically due to an invalid routing decision ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_id_format": { "summary": "Invalid ID Format", "description": "Example of an error when the routing decision ID is not in the expected format.", "value": { "type": "https://example.com/probs/invalid-id", "title": "Invalid Routing Decision ID", "status": 400, "detail": "The routing decision ID provided is not valid. Ensure it is correctly formatted and retry." } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "An error when the request lacks authentication credentials.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication Required", "status": 401, "detail": "You must be authenticated to view this resource. Please provide valid credentials." } } } } } }, "403": { "description": "You do not have permission to access this audit trail.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "An error when the user lacks the necessary permissions to view the audit.", "value": { "type": "https://example.com/probs/forbidden", "title": "Access Denied", "status": 403, "detail": "Your user role does not permit accessing this audit. Contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "The routing decision audit bundle was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "audit_not_found": { "summary": "Audit Not Found", "description": "An error when no audit data exists for the given routing decision ID.", "value": { "type": "https://example.com/probs/not-found", "title": "Routing Audit Not Found", "status": 404, "detail": "No audit record was found for the provided routing decision ID. Verify the ID and try again." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A generic error when the server encounters an unexpected condition.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/evidence/pending/:ref/claim": { "post": { "summary": "Claim Pending Evidence", "description": "Securely claim pending evidence using your cryptographic identity (Passport). This endpoint ensures evidence can only be claimed by the rightful owner, with anti-fraud measures to prevent misuse.", "operationId": "claimPendingEvidence", "tags": [ "Evidence", "Security" ], "x-code-hash": "1d31be96ff8a00ca", "x-generated-at": "2026-04-27T16:56:29.951Z", "responses": { "200": { "description": "Evidence claimed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_record": { "type": "object", "properties": { "id": { "type": "string" }, "passport_did": { "type": "string" }, "intake_envelope": { "type": "object" }, "ingestion_state": { "type": "string" } }, "required": [ "id", "passport_did", "intake_envelope", "ingestion_state" ] }, "claimed": { "type": "boolean" } }, "required": [ "evidence_record", "claimed" ] }, "examples": { "successful_claim": { "summary": "Successful Claim", "value": { "evidence_record": { "id": "ev-12345", "passport_did": "did:example:123456789abcdefghi", "intake_envelope": { "type": "invoice", "details": "Invoice for ACME Corp" }, "ingestion_state": "imported" }, "claimed": true } } } } } }, "202": { "description": "Evidence pending review due to anti-fraud measures", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending_review" ] }, "evidence_id": { "type": "string" } }, "required": [ "status", "evidence_id" ] }, "examples": { "pending_review": { "summary": "Pending Review", "value": { "status": "pending_review", "evidence_id": "ev-67890" } } } } } }, "400": { "description": "Validation error due to missing Passport subject", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_subject": { "summary": "Missing Subject", "value": { "type": "/errors/validation", "title": "Bad Request", "status": 400, "detail": "Passport subject (delegation) required to claim pending evidence", "errors": [ { "field": "delegation", "code": "SUBJECT_REQUIRED", "message": "Passport subject (delegation) required to claim pending evidence" } ] } } } } } }, "404": { "description": "Pending evidence not found or deadline passed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "evidence_not_found": { "summary": "Evidence Not Found", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Pending evidence not found" } }, "deadline_passed": { "summary": "Deadline Passed", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "Claim deadline has passed" } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/evidence/:id/disclose/verify": { "post": { "summary": "Verify Disclosed Evidence Presentation", "description": "Unveil the truth behind cryptographic evidence by verifying its disclosed claims against a BBS+ anchor. This endpoint safeguards the integrity of digital credentials, ensuring trust and transparency in decentralized identity systems.", "operationId": "verifyDisclosedEvidencePresentation", "tags": [ "IdentityVerification", "Cryptography" ], "x-code-hash": "0c3d66c5b4f483c0", "x-generated-at": "2026-04-27T16:56:44.565Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "presentation": { "type": "object", "description": "BBS+ cryptographic presentation object" }, "verifier_challenge": { "type": "string", "description": "Challenge string used by the verifier" } }, "required": [ "presentation", "verifier_challenge" ] }, "examples": { "valid_presentation_example": { "summary": "Valid Presentation Example", "description": "A complete and valid BBS+ presentation with a verifier challenge", "value": { "presentation": { "disclosedClaims": { "name": "John Doe", "age": "30" }, "proof": { "type": "BbsSignature2020", "created": "2023-10-01T12:00:00Z" } }, "verifier_challenge": "random-challenge-string" } } } } } }, "responses": { "200": { "description": "Successfully verified the disclosed evidence presentation", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "disclosed_fields": { "type": "array", "items": { "type": "string" } }, "issuer_did": { "type": "string" }, "error": { "type": "string", "nullable": true } } }, "examples": { "successful_verification": { "summary": "Successful Verification", "description": "The presentation is valid with disclosed fields", "value": { "valid": true, "disclosed_fields": [ "name", "age" ], "issuer_did": "did:example:123456789abcdefghi", "error": null } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found if no BBS+ anchor exists for the given evidence", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error due to unexpected circumstances", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/evidence/:id/disclose": { "post": { "summary": "Disclose fields from evidence record", "description": "Reveal specific fields from an evidence record, allowing verifiable claims to be shared securely. This endpoint ensures that only authorized users can disclose fields, maintaining the integrity of the evidence while facilitating trusted interactions.", "operationId": "discloseEvidenceFields", "tags": [ "Evidence", "Disclosure" ], "x-code-hash": "adcb8622b6cc00db", "x-generated-at": "2026-04-27T16:57:03.728Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disclosed_fields": { "type": "array", "items": { "type": "string" }, "description": "List of fields to disclose." }, "purpose": { "type": "string", "description": "Purpose of the disclosure." }, "requester_did": { "type": "string", "description": "DID of the entity requesting disclosure." } }, "required": [ "disclosed_fields" ] }, "examples": { "basic_disclosure_request": { "summary": "Basic Disclosure Request", "description": "Request to disclose specific fields for verification purposes.", "value": { "disclosed_fields": [ "name", "email" ], "purpose": "Verification of identity", "requester_did": "did:example:requester123" } } } } } }, "responses": { "200": { "description": "Fields disclosed successfully, returning a verifiable presentation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verifiable_presentation": { "type": "object", "description": "Generated verifiable presentation including disclosed fields." }, "verifier_challenge": { "type": "string", "description": "Challenge string for verifier." }, "disclosed_fields": { "type": "array", "items": { "type": "string" }, "description": "List of successfully disclosed fields." }, "issuer_did": { "type": "string", "description": "DID of the credential issuer." }, "evidence_record_id": { "type": "string", "description": "ID of the disclosed evidence record." }, "purpose": { "type": [ "string", "null" ], "description": "Purpose of the disclosure, if provided." }, "requester_did": { "type": [ "string", "null" ], "description": "DID of the requester, if provided." } } }, "examples": { "successful_disclosure": { "summary": "Successful Disclosure", "value": { "verifiable_presentation": { "type": "VerifiablePresentation", "proof": { "type": "BbsSignature" } }, "verifier_challenge": "SGVsbG9Xb3JsZA==", "disclosed_fields": [ "name", "email" ], "issuer_did": "did:example:issuer456", "evidence_record_id": "record789", "purpose": "Verification of identity", "requester_did": "did:example:requester123" } } } } } }, "400": { "description": "Bad request due to missing or invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access attempt by a non-holder of the evidence.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden due to lack of explicit consent for disclosure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified evidence record could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict due to pending credential issuance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/evidence/:id": { "get": { "summary": "Retrieve detailed evidence record", "description": "This endpoint unveils the story behind an evidence record by fetching its details and lifecycle events. It plays a crucial role in understanding the provenance and integrity of an evidence item, ensuring transparency and accountability within the HUMAN platform.", "operationId": "getEvidenceById", "tags": [ "Evidence", "Provenance" ], "x-code-hash": "4ad48ee30c4861df", "x-generated-at": "2026-04-27T16:57:18.027Z", "responses": { "200": { "description": "Successfully retrieved the evidence record and its lifecycle events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_record": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "object" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "id", "data", "timestamp" ] }, "evidence_lifecycle_events": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "event_id", "type", "timestamp" ] } } }, "required": [ "evidence_record", "evidence_lifecycle_events" ] }, "examples": { "evidence_retrieval_example": { "summary": "Evidence retrieval example", "description": "Example of a successful retrieval of an evidence record for an invoice processing task.", "value": { "evidence_record": { "id": "evidence-1234", "data": { "document_type": "invoice", "issuer": "acme", "recipient": "globex" }, "timestamp": "2023-10-01T12:34:56Z" }, "evidence_lifecycle_events": [ { "event_id": "event-5678", "type": "CREATED", "timestamp": "2023-10-01T12:00:00Z" }, { "event_id": "event-6789", "type": "VALIDATED", "timestamp": "2023-10-01T12:30:00Z" } ] } } } } } }, "400": { "description": "Invalid request parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_id_format": { "summary": "Invalid ID format", "description": "The provided evidence ID was not valid.", "value": { "type": "https://api.human/probs/invalid-id", "title": "Invalid ID", "status": 400, "detail": "The evidence ID 'abc' is not in the correct format. Please provide a valid ID.", "errors": [ "Invalid ID format" ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing authentication", "description": "The request was made without valid authentication credentials.", "value": { "type": "https://api.human/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided. Please include a valid token." } } } } } }, "403": { "description": "The authenticated user does not have permission to access the requested resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "description": "The user tried to access an evidence record they do not have permission to view.", "value": { "type": "https://api.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this evidence record." } } } } } }, "404": { "description": "The specified evidence record could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "evidence_not_found": { "summary": "Evidence not found", "description": "The evidence ID provided does not exist in the system.", "value": { "type": "https://api.human/probs/evidence-not-found", "title": "Evidence Not Found", "status": 404, "detail": "The evidence record with ID 'evidence-9999' could not be found. Verify the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server error", "description": "A database connection issue caused the server to fail.", "value": { "type": "https://api.human/probs/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try your request again later." } } } } } } } } }, "/v1/evidence/:id/challenge": { "post": { "summary": "Challenge Evidence with Conflict Detection", "description": "Initiate a challenge against a piece of evidence, flagging it for neutral review if an organizational conflict exists. This endpoint orchestrates the challenge, ensuring fairness and transparency in evidence handling by involving neutral parties when necessary.", "operationId": "challengeEvidence", "tags": [ "Evidence", "Challenge" ], "x-code-hash": "89329b7f829fce26", "x-generated-at": "2026-04-27T17:14:38.213Z", "responses": { "200": { "description": "The challenge was successfully initiated, and the review task was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_id": { "type": "string", "description": "The unique identifier of the challenged evidence." }, "status": { "type": "string", "description": "The current status of the evidence challenge." }, "review_task_created": { "type": "boolean", "description": "Indicates whether a review task was created." }, "conflict_detected": { "type": "boolean", "description": "Indicates if an organizational conflict was detected." }, "adjudicator_role": { "type": [ "string", "null" ], "description": "The role assigned to the adjudicator for conflict resolution." } } }, "examples": { "successful_challenge": { "summary": "Successful Challenge", "value": { "evidence_id": "12345", "status": "challenged", "review_task_created": true, "conflict_detected": true, "adjudicator_role": "compliance_reviewer" } } } } } }, "400": { "description": "Bad Request due to invalid input parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_evidence_id": { "summary": "Invalid Evidence ID", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The evidence ID provided is not valid. Please verify the ID and try again." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication_token": { "summary": "Missing Authentication Token", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to challenge evidence. Please include a valid token." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to challenge this evidence. Please contact your administrator." } } } } } }, "404": { "description": "The evidence with the specified ID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "evidence_not_found": { "summary": "Evidence Not Found", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The evidence with the provided ID does not exist. Please check the ID and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the challenge. Please try again later." } } } } } } } } }, "/v1/capabilities/batch-query": { "post": { "summary": "Batch Query Capabilities for Tasks", "description": "Unlock the potential of your enterprise by efficiently querying capabilities across multiple tasks. This endpoint orchestrates a seamless interaction between human and AI capabilities, ensuring the right skills are matched to each task. It empowers organizations to harness their full potential by dynamically leveraging a distributed ledger of skills.", "operationId": "batchQueryCapabilities", "tags": [ "Capabilities", "Task Management" ], "x-code-hash": "2ab5aee2aff42258", "x-generated-at": "2026-04-27T16:58:00.529Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "description": "Unique identifier for the organization." }, "queries": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string", "description": "Identifier for the task." }, "required_capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of required capabilities for the task." } }, "required": [ "task_id", "required_capabilities" ] }, "description": "Array of tasks with required capabilities." }, "options": { "type": "object", "properties": { "min_capability_weight": { "type": "number", "description": "Minimum confidence weight for capabilities.", "default": 0.5 }, "include_confidence": { "type": "boolean", "description": "Include confidence scores in results.", "default": true }, "include_humans": { "type": "boolean", "description": "Include human matches in results.", "default": true }, "include_agents": { "type": "boolean", "description": "Include AI agent matches in results.", "default": true }, "include_marketplace": { "type": "boolean", "description": "Include marketplace suggestions if no matches found.", "default": false }, "limit": { "type": "integer", "description": "Limit number of matches per query.", "maximum": 100, "default": 20 } } } }, "required": [ "org_id", "queries" ] }, "examples": { "acme_corp_task_query": { "summary": "Acme Corp Task Query", "description": "A query for Acme Corp to find capabilities for tasks.", "value": { "org_id": "acme-corp", "queries": [ { "task_id": "invoice-processing", "required_capabilities": [ "capability://data-entry", "capability://approval" ] } ], "options": { "min_capability_weight": 0.7, "include_confidence": true, "include_humans": true, "include_agents": true, "include_marketplace": true, "limit": 10 } } } } } } }, "responses": { "200": { "description": "Capabilities successfully queried for the provided tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string" }, "humans": { "type": "array", "items": { "type": "object" } }, "agents": { "type": "array", "items": { "type": "object" } }, "matched_count": { "type": "integer" }, "capability_gap": { "type": "number" }, "marketplace_suggestions": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "install_required": { "type": "boolean" }, "install_path": { "type": "string" }, "marketplace_url": { "type": "string" } } } }, "query": { "type": "object" } } } }, "options": { "type": "object", "properties": { "include_confidence": { "type": "boolean" }, "min_capability_weight": { "type": "number" }, "include_humans": { "type": "boolean" }, "include_agents": { "type": "boolean" }, "include_marketplace": { "type": "boolean" }, "limit": { "type": "integer" } } }, "agent_id": { "type": "string" }, "total_queries": { "type": "integer" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing or malformed fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/capabilities/match": { "post": { "summary": "Match Capabilities for Task Routing", "description": "Efficiently orchestrate tasks by matching required capabilities to available humans and agents. This endpoint leverages a sophisticated algorithm to ensure that the right skills are applied to the right tasks, enhancing productivity and ensuring AI safety.", "operationId": "postCapabilitiesMatch", "tags": [ "Capabilities", "Task Routing" ], "x-code-hash": "27cf466bb09e7221", "x-generated-at": "2026-04-27T16:58:25.659Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "required_capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of capability IDs required for the task." }, "org_id": { "type": "string", "description": "The organization ID where the task is to be routed." }, "min_confidence": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5, "description": "Minimum confidence level for matching capabilities." }, "include_humans": { "type": "boolean", "default": true, "description": "Whether to include human resources in the match." }, "include_agents": { "type": "boolean", "default": true, "description": "Whether to include AI agents in the match." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of matches to return." }, "match_strategy": { "type": "string", "enum": [ "exact", "semantic", "hybrid" ], "default": "exact", "description": "Strategy to use for matching capabilities." }, "task_description": { "type": "string", "description": "Description of the task, required if using semantic or hybrid strategy." }, "task_id": { "type": "string", "default": "inline", "description": "Unique identifier for the task." } }, "required": [ "required_capabilities", "org_id" ] }, "examples": { "basic_capability_match_request": { "summary": "Basic Capability Match Request", "description": "A request to match capabilities with a minimum confidence of 0.7 in the 'acme' organization using an exact match strategy.", "value": { "required_capabilities": [ "capability://finance/invoice-processing", "capability://hr/employee-onboarding" ], "org_id": "org_acme", "min_confidence": 0.7, "include_humans": true, "include_agents": true, "limit": 10, "match_strategy": "exact" } } } } } }, "responses": { "200": { "description": "Successfully matched capabilities with available resources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "humans": { "type": "array", "items": { "type": "string" }, "description": "List of human IDs matched to the task." }, "agents": { "type": "array", "items": { "type": "string" }, "description": "List of agent IDs matched to the task." }, "capability_gap": { "type": "boolean", "description": "Indicates if there was a capability gap that prevented a match." }, "query": { "type": "object", "description": "Echoes the query parameters used in the request." }, "matched_count": { "type": "integer", "description": "The number of total matches found." }, "match_strategy_used": { "type": "string", "description": "The strategy that was actually used to perform the match." }, "weakest_link_score": { "type": "number", "description": "Score of the weakest link in semantic matching." }, "threshold_used": { "type": "number", "description": "The threshold used for semantic matching." }, "routed": { "type": "boolean", "description": "Indicates if the task was successfully routed." }, "resolved_canonical": { "type": "array", "items": { "type": "string" }, "description": "List of resolved canonical capability IDs." }, "semantic_skipped": { "type": "boolean", "description": "Indicates if semantic matching was skipped." } }, "required": [ "humans", "agents", "capability_gap", "query", "matched_count", "match_strategy_used", "routed", "resolved_canonical" ] }, "examples": { "successful_match_example": { "summary": "Successful Match Example", "description": "An example of a successful match with humans and agents for invoice processing.", "value": { "humans": [ "human_123", "human_456" ], "agents": [ "agent_789" ], "capability_gap": false, "query": { "required_capabilities": [ "capability://finance/invoice-processing" ], "org_id": "org_acme", "min_confidence": 0.7, "limit": 10, "match_strategy": "exact" }, "matched_count": 3, "match_strategy_used": "exact", "weakest_link_score": 0.85, "threshold_used": 0.7, "routed": true, "resolved_canonical": [ "capability://finance/invoice-processing" ], "semantic_skipped": false } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_required_field": { "summary": "Missing Required Field", "description": "Example of a missing required field causing a validation error.", "value": { "type": "https://example.com/probs/invalid-parameters", "title": "Invalid request parameters", "status": 400, "detail": "One or more fields are missing or invalid.", "errors": [ { "field": "required_capabilities", "code": "REQUIRED_FIELD_MISSING", "message": "This field is required", "expected": "array of capability IDs", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "Example indicating lack of authorization to access the endpoint.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must authenticate to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Example of insufficient permissions to perform the action.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "description": "Example indicating that the specified resource could not be found.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "Example indicating an unexpected server error.", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capabilities/routing": { "get": { "summary": "Retrieve routing capabilities for tasks", "description": "Uncover the harmony between AI and human skills by identifying routing capabilities tailored to your organization's needs. This endpoint orchestrates the intricate dance of task routing by fetching a curated list of capabilities based on your specified criteria, ensuring optimal skill application and AI safety.", "operationId": "getCapabilitiesRouting", "tags": [ "Capabilities", "Routing" ], "x-code-hash": "2c1d18a98e1e63d2", "x-generated-at": "2026-04-27T16:58:48.623Z", "responses": { "200": { "description": "A list of capabilities matching the query criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "canonical_name": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "domain": { "type": "string" }, "description": { "type": "string" }, "synonyms_json": { "type": "string" }, "status": { "type": "string" }, "scope": { "type": "string" }, "org_slug": { "type": [ "string", "null" ] }, "governance_tier": { "type": "string" }, "classification": { "type": "string" }, "curator_approved": { "type": "boolean" }, "usage_count": { "type": "integer" }, "promotion_candidate": { "type": "boolean" }, "canonical_equivalent": { "type": "string" }, "version": { "type": "string" }, "examples_json": { "type": "string" }, "embedding_json": { "type": "string" }, "relationships_json": { "type": "string" }, "trend_direction": { "type": "string" }, "supply_count": { "type": "integer" }, "demand_count": { "type": "integer" }, "semantic_drift": { "type": "string" }, "metadata_json": { "type": "string" }, "promoted_from": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" }, "org_slug": { "type": [ "string", "null" ] }, "overlay": { "type": "string" } } }, "examples": { "capabilities_for_acme_corp": { "summary": "Capabilities for ACME Corp", "description": "Retrieving a list of capabilities for the 'acme' organization with specific routing needs.", "value": { "capabilities": [ { "id": "cap123", "canonical_name": "invoice-processing", "category": "finance", "subcategory": "accounting", "domain": "financial-services", "description": "Processes invoices efficiently with AI oversight.", "synonyms_json": "['invoice handling', 'billing']", "status": "active", "scope": "org", "org_slug": "acme", "governance_tier": "tier1", "classification": "restricted", "curator_approved": true, "usage_count": 150, "promotion_candidate": false, "canonical_equivalent": "cap_invoice", "version": "1.3", "examples_json": "['Example 1', 'Example 2']", "embedding_json": "{}", "relationships_json": "{}", "trend_direction": "upward", "supply_count": 75, "demand_count": 80, "semantic_drift": "stable", "metadata_json": "{}", "promoted_from": "cap_invoice_v1", "created_at": "2023-09-15T13:45:30Z", "updated_at": "2023-10-01T10:21:00Z" } ], "count": 1, "org_slug": "acme", "overlay": "canonical + org-scoped" } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_capability_ids": { "summary": "Invalid Capability IDs", "description": "The request contains invalid capability IDs.", "value": { "type": "https://api.human.com/errors/invalid-parameters", "title": "Invalid request parameters", "status": 400, "detail": "The provided capabilityIds are not valid.", "errors": [ { "field": "capabilityIds", "message": "Must be a comma-separated list of valid UUIDs." } ] } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_or_invalid_token": { "summary": "Missing or Invalid Token", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://api.human.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication token is missing or invalid. Ensure your API token is included in the request header." } } } } } }, "403": { "description": "Forbidden access to resources.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied_for_acme_org": { "summary": "Access Denied for ACME Org", "description": "User does not have permission to access this organization's capabilities.", "value": { "type": "https://api.human.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access capabilities for the 'acme' organization." } } } } } }, "404": { "description": "Resources not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_capabilities_found": { "summary": "No Capabilities Found", "description": "No capabilities match the given criteria.", "value": { "type": "https://api.human.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "No capabilities found matching the provided query parameters." } } } } } }, "500": { "description": "Internal server error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "An unexpected error prevented the processing of the request.", "value": { "type": "https://api.human.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later. Incident ID: inc_1698247200000" } } } } } } } } }, "/v1/capabilities/ontology/search": { "get": { "summary": "Search capability ontology", "description": "Dive into the depths of HUMAN's Capability Graph with this endpoint, crafted to unearth the skills and attributes hidden within our ontology. Whether you're matching precise skills or exploring broader categories, this search tool is your gateway to understanding and utilizing HUMAN's rich skill taxonomy.", "operationId": "searchCapabilityOntology", "tags": [ "Capabilities", "Ontology" ], "x-code-hash": "20d455d6eca776a1", "x-generated-at": "2026-04-27T16:59:05.576Z", "responses": { "200": { "description": "Successfully retrieved matching capabilities from the ontology.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "match_score": { "type": "number" }, "layer": { "type": "string", "enum": [ "canonical", "org", "dev-label" ] } }, "required": [ "capability_id", "name", "category", "match_score", "layer" ] } }, "total": { "type": "integer" }, "query_embedding_cached": { "type": "boolean" } }, "required": [ "results", "total", "query_embedding_cached" ] }, "examples": { "successful_search_result": { "summary": "Successful search result", "description": "A search for 'invoice processing' in the ontology.", "value": { "results": [ { "capability_id": "invoice-123", "name": "Invoice Processing", "category": "finance", "match_score": 0.89, "layer": "canonical" } ], "total": 1, "query_embedding_cached": false } } } } } }, "400": { "description": "The request was malformed or missing a required parameter.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_'q'_parameter": { "summary": "Missing 'q' parameter", "description": "The 'q' query parameter is required for ontology search.", "value": { "type": "https://example.com/probs/required-field-missing", "title": "Required field missing", "status": 400, "detail": "The 'q' query parameter is required for ontology search.", "errors": [ { "field": "q", "code": "REQUIRED_FIELD_MISSING", "message": "q query parameter is required for ontology search", "expected": "non-empty string", "received": "" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthenticated_access": { "summary": "Unauthenticated access", "description": "The user is not authenticated.", "value": { "type": "https://example.com/probs/authentication-required", "title": "Authentication Required", "status": 401, "detail": "You must authenticate to access the capability ontology search." } } } } } }, "403": { "description": "The user does not have permission to perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "description": "The user lacks permission to search the capability ontology.", "value": { "type": "https://example.com/probs/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to search the capability ontology." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "capability_not_found": { "summary": "Capability not found", "description": "The requested capability does not exist in the ontology.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The capability you are searching for does not exist." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "A problem occurred on the server side.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capabilities/ontology/canonical/:capability_id": { "get": { "summary": "Retrieve canonical capability details", "description": "In the intricate dance of human and AI collaboration, understanding the core capabilities is paramount. This endpoint reveals the canonical form of an organizational capability, ensuring clarity and consistency across the HUMAN ecosystem. By resolving to a canonical URI, it provides a solid reference point in the ever-evolving capability graph.", "operationId": "getCanonicalCapabilityDetail", "tags": [ "Capabilities", "Ontology" ], "x-code-hash": "d3f89168b183b174", "x-generated-at": "2026-04-27T16:59:20.745Z", "responses": { "200": { "description": "Successfully retrieved the canonical capability details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canonicalUri": { "type": "string", "description": "The canonical URI representing the capability." }, "description": { "type": "string", "description": "A brief description of the capability." } } }, "examples": { "successful_retrieval": { "summary": "Successful retrieval", "value": { "canonicalUri": "capability://acme/finance/invoice-processing", "description": "Processes financial invoices for Acme Corp." } } } } } }, "400": { "description": "Invalid capability_id was provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_capability_id": { "summary": "Invalid capability_id", "value": { "type": "/errors/validation", "title": "Invalid Request Parameter", "status": 400, "detail": "The 'capability_id' path parameter is invalid.", "errors": [ { "field": "capability_id", "code": "INVALID_VALUE", "message": "Invalid capability_id path parameter", "expected": "non-empty string", "received": "" } ] } } } } } }, "401": { "description": "Unauthorized access to the capability details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "value": { "type": "/errors/authentication", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "value": { "type": "/errors/permissions", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this capability." } } } } } }, "404": { "description": "Capability not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "capability_not_found": { "summary": "Capability not found", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified capability could not be found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capabilities/ontology/canonical/:capability_id/propose": { "post": { "summary": "Propose updates to a capability ontology", "description": "Engage with the HUMAN protocol by proposing canonical updates to a capability. This endpoint empowers users to enhance the system's understanding of a skill, ensuring the AI aligns closer with human expertise.", "operationId": "proposeCapabilityOntology", "tags": [ "Capabilities", "Ontology" ], "x-code-hash": "e6f1022c98583453", "x-generated-at": "2026-04-27T16:59:36.303Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the capability." }, "description": { "type": "string", "description": "A detailed explanation of the capability's function." }, "attributes": { "type": "array", "items": { "type": "string" }, "description": "List of attributes that define the capability." } }, "required": [ "name", "description" ] }, "examples": { "update_capability_name": { "summary": "Update Capability Name", "description": "Propose a new name and description for a capability.", "value": { "name": "Advanced Image Analysis", "description": "A capability for processing and interpreting complex image data.", "attributes": [ "high-resolution", "pattern-recognition", "color-analysis" ] } } } } } }, "responses": { "200": { "description": "The proposal was successfully submitted and is under review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Proposal submitted successfully." } } } } } }, "400": { "description": "Invalid input data; review the fields and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Request lacks valid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "The user does not have permission to propose changes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified capability could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/capabilities/ontology/canonical/:capability_id/promote": { "post": { "summary": "Promote capability to canonical status", "description": "Elevate an organizational capability to a canonical status, ensuring it becomes a recognized skill within the HUMAN ecosystem. This endpoint fosters standardization and interoperability by allowing organizations to formalize their unique skills for broader use.", "operationId": "promoteCapabilityToCanonical", "tags": [ "Capabilities", "Ontology" ], "x-code-hash": "f3069233c641087b", "x-generated-at": "2026-04-27T16:59:52.166Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "canonical_uri": { "type": "string", "description": "The URI that uniquely identifies the canonical form of the capability." }, "promoter_did": { "type": "string", "description": "DID of the agent promoting the capability." } }, "required": [ "canonical_uri", "promoter_did" ] }, "examples": { "promote_invoiceprocessing": { "summary": "Promote InvoiceProcessing", "description": "An example of promoting the InvoiceProcessing capability to canonical, with a specific URI and promoter DID.", "value": { "canonical_uri": "capability://acme/invoice-processing", "promoter_did": "did:example:123456789abcdefghi" } } } } } }, "responses": { "200": { "description": "The capability was successfully promoted to canonical status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_cap_id": { "type": "string", "description": "The ID of the organizational capability that was promoted." }, "status": { "type": "string", "enum": [ "promoted" ], "description": "The status of the promotion operation." }, "canonical_uri": { "type": "string", "description": "The canonical URI that was assigned to the capability." }, "deprecated_org_uri": { "type": "string", "description": "The deprecated URI of the original organizational capability." }, "provenance_event_id": { "type": "string", "description": "A unique identifier for the provenance event generated by this promotion." } } }, "examples": { "default": { "summary": "Example", "value": { "org_cap_id": "cap_67890", "status": "promoted", "canonical_uri": "capability://acme/invoice-processing", "deprecated_org_uri": "org://acme/legacy-invoice-processing", "provenance_event_id": "pe_1697043000000" } } } } } }, "400": { "description": "Bad request due to missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/invalid-request", "title": "Bad Request", "status": 400, "detail": "canonical_uri and promoter_did required", "errors": [ { "field": "body", "code": "REQUIRED_FIELD_MISSING", "message": "canonical_uri and promoter_did required", "expected": "JSON", "received": "invalid" } ] } } } } } }, "401": { "description": "Unauthorized access due to lack of delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "Insufficient permissions for global promotion" } } } } } }, "404": { "description": "Capability not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/not-found", "title": "Not Found", "status": 404, "detail": "Capability with given ID not found" } } } } } }, "500": { "description": "Internal Server Error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.human/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred, please try again later." } } } } } } } } }, "/v1/capabilities/infer/:did": { "post": { "summary": "Infer capabilities for a digital identity", "description": "Harness the power of HUMAN's Capability Graph to dynamically infer the skills associated with a digital identity, identified by its DID. This endpoint empowers organizations to efficiently manage and update the skill sets of their digital agents, ensuring they are always aligned with the latest operational needs.", "operationId": "inferCapabilitiesForDid", "tags": [ "Capabilities", "Inference" ], "x-code-hash": "49b7c087e5a3cf9b", "x-generated-at": "2026-04-27T17:00:10.620Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "description": "The organization ID to scope the capability inference." } }, "required": [ "org_id" ] }, "examples": { "acme_corp_inference_request": { "summary": "Acme Corp Inference Request", "description": "Requesting capability inference for Acme Corp's digital identity.", "value": { "org_id": "acme-corp-123" } } } } } }, "responses": { "200": { "description": "Capability inference completed successfully, returning the proposals created and updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposals_created": { "type": "integer", "description": "Number of new proposals created from inference." }, "proposals_updated": { "type": "integer", "description": "Number of existing proposals updated from inference." }, "did": { "type": "string", "description": "The DID for which the inference was performed." }, "ran_at": { "type": "string", "format": "date-time", "description": "Timestamp when the inference was executed." } } }, "examples": { "successful_inference_response": { "summary": "Successful Inference Response", "description": "The capabilities were inferred successfully for the specified DID.", "value": { "proposals_created": 5, "proposals_updated": 3, "did": "did:human:123456789abcdefghi", "ran_at": "2023-10-25T14:48:00Z" } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified DID could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/capabilities/proposals/:did": { "get": { "summary": "Retrieve capability proposals for a DID", "description": "Explore the landscape of your digital capabilities with this endpoint. By retrieving proposals associated with a Decentralized Identifier (DID), you can track the evolution of skills and knowledge as they align with your digital identity. This empowers organizations to make informed decisions about skill development and deployment.", "operationId": "getCapabilityProposalsForDid", "tags": [ "Capabilities", "Proposals" ], "x-code-hash": "242514b70e63f6f2", "x-generated-at": "2026-04-27T17:00:29.520Z", "responses": { "200": { "description": "Successfully retrieved capability proposals for the specified DID. The response includes details about each proposal, such as the capability ID, confidence level, and status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "proposal_id": { "type": "string" }, "did": { "type": "string" }, "capability_id": { "type": "string" }, "capability_name": { "type": "string" }, "confidence": { "type": "number" }, "status": { "type": "string" }, "evidence_refs": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "reviewed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "proposal_id", "did", "capability_id", "capability_name", "confidence", "status", "created_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "acme_corp's_proposals": { "summary": "ACME Corp's proposals", "description": "ACME Corp retrieves the latest 50 capability proposals for DID 'did:example:123456789abcdefghi'.", "value": { "data": [ { "proposal_id": "prop_001", "did": "did:example:123456789abcdefghi", "capability_id": "cap_123", "capability_name": "Advanced Data Analysis", "confidence": 0.87, "status": "review_pending", "evidence_refs": { "document": "doc_001" }, "created_at": "2023-10-01T12:34:56Z", "reviewed_by": null, "reviewed_at": null } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "The request was invalid. This typically occurs when the DID is missing or not in the correct format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "short_did": { "summary": "Short DID", "description": "A request failed because the provided DID was too short.", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "Invalid DID", "errors": [ { "field": "did", "code": "INVALID_VALUE", "message": "DID must be at least 3 characters long.", "expected": "string", "received": "" } ] } } } } } }, "401": { "description": "Unauthorized access. The request requires authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_token": { "summary": "Missing Token", "description": "A request failed due to a missing authentication token.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required to access this resource." } } } } } }, "403": { "description": "Forbidden. The authenticated user does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "A request was denied due to insufficient permissions.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Not Found. The specified DID does not exist or has no capability proposals.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "did_not_found": { "summary": "DID Not Found", "description": "A request was made for a non-existent DID.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified DID was not found in the system." } } } } } }, "500": { "description": "Internal Server Error. An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "A request failed due to an unexpected server error.", "value": { "type": "https://humanprotocol.org/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capabilities/proposals/:proposal_id/accept": { "post": { "summary": "Accept a Capability Proposal", "description": "In the dynamic world of Human-AI collaboration, the acceptance of capability proposals solidifies the partnership between human agents and AI systems. This endpoint empowers authorized reviewers to formally accept proposals, thereby expanding the skill set recognized within the HUMAN platform.", "operationId": "acceptCapabilityProposal", "tags": [ "Capabilities", "Proposals" ], "x-code-hash": "3b2565b04a3662ab", "x-generated-at": "2026-04-27T17:00:45.702Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewer_did": { "type": "string", "description": "The decentralized identifier of the reviewer accepting the proposal." } }, "required": [ "reviewer_did" ] }, "examples": { "standard_acceptance": { "summary": "Standard Acceptance", "description": "Acceptance of a capability proposal with a valid reviewer DID.", "value": { "reviewer_did": "did:human:example123" } } } } } }, "responses": { "200": { "description": "The proposal was successfully accepted, enhancing the HUMAN capability graph.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "The unique identifier of the accepted proposal." }, "status": { "type": "string", "enum": [ "accepted" ], "description": "The status of the proposal post-acceptance." }, "node_created": { "type": "boolean", "description": "Indicates whether a new node was created in the capability graph." }, "weight_written": { "type": "boolean", "description": "Indicates whether the weight of the capability was successfully recorded." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request due to missing or malformed request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/missing-field", "title": "Bad Request", "status": 400, "detail": "Required field 'reviewer_did' is missing.", "errors": [ { "field": "reviewer_did", "code": "REQUIRED_FIELD_MISSING", "message": "reviewer_did required", "expected": "string", "received": "" } ] } } } } } }, "401": { "description": "Authentication error indicating that delegation is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-error", "title": "Unauthorized", "status": 401, "detail": "Delegation required to accept proposals." } } } } } }, "403": { "description": "Authorization error due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authorization-error", "title": "Forbidden", "status": 403, "detail": "Insufficient permissions to accept capability proposals." } } } } } }, "404": { "description": "Proposal not found for the provided ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "Capability proposal with ID 'proposal-xyz' not found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while accepting the proposal. Please try again later." } } } } } } } } }, "/v1/capabilities/proposals/:proposal_id/reject": { "post": { "summary": "Reject a capability proposal", "description": "This endpoint allows a reviewer to reject a capability proposal, ensuring that only appropriate skills are added to the Capability Graph. By empowering reviewers to provide feedback, HUMAN maintains a high standard of trust and reliability in its network.", "operationId": "rejectCapabilityProposal", "tags": [ "Capabilities", "Proposals" ], "x-code-hash": "1030e20bef68571d", "x-generated-at": "2026-04-27T17:00:59.689Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewer_did": { "type": "string", "description": "Decentralized Identifier of the reviewer" }, "rejection_reason": { "type": "string", "description": "Reason for rejecting the proposal" } }, "required": [ "reviewer_did", "rejection_reason" ] }, "examples": { "standard_rejection": { "summary": "Standard rejection", "description": "Rejecting a proposal with a valid reason", "value": { "reviewer_did": "did:human:abc123", "rejection_reason": "Insufficient evidence of skill proficiency" } } } } } }, "responses": { "200": { "description": "The proposal was successfully rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal_id": { "type": "string", "description": "The ID of the rejected proposal" }, "status": { "type": "string", "enum": [ "rejected" ], "description": "The status of the proposal after being processed" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid input provided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/validation", "title": "Invalid Input", "status": 400, "detail": "rejection_reason and reviewer_did required", "errors": [ { "field": "rejection_reason", "code": "REQUIRED_FIELD_MISSING", "message": "rejection_reason and reviewer_did required", "expected": "string", "received": "" } ] } } } } } }, "401": { "description": "Authentication error due to missing or invalid delegation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authentication", "title": "Authentication Error", "status": 401, "detail": "Delegation required to perform this action. Please ensure you have provided the appropriate authentication details." } } } } } }, "403": { "description": "Authorization error due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/authorization", "title": "Authorization Error", "status": 403, "detail": "Insufficient permissions to reject proposal. Ensure your delegation includes the 'human_api:capabilities:write' scope." } } } } } }, "404": { "description": "Proposal not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified proposal ID does not exist in the system. Verify the proposal ID and try again." } } } } } }, "500": { "description": "Internal server error indicating an unexpected failure", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while trying to reject the proposal. Please try again later or contact support with the incident ID." } } } } } } } } }, "/v1/capabilities/ontology/:capability_id": { "get": { "summary": "Retrieve detailed capability ontology", "description": "Delve into the intricacies of a specific capability within the HUMAN ecosystem. This endpoint reveals the nuanced relationships and metadata that define a capability, providing a comprehensive view of its role and market dynamics. It's the key to unlocking how capabilities interconnect and evolve in response to market demands.", "operationId": "getCapabilityOntologyDetail", "tags": [ "Capabilities", "Ontology" ], "x-code-hash": "f5f8825367f386d3", "x-generated-at": "2026-04-27T17:01:17.258Z", "responses": { "200": { "description": "Successfully retrieved the capability ontology details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the capability." }, "canonical_name": { "type": "string", "description": "The canonical name of the capability." }, "category": { "type": "string", "description": "High-level category of the capability." }, "subcategory": { "type": "string", "description": "Subcategory within the broader category." }, "domain": { "type": "string", "description": "The domain this capability belongs to." }, "description": { "type": "string", "description": "A detailed description of the capability." }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "from_capability_id": { "type": "string", "description": "ID of the originating capability in the relationship." }, "to_capability_id": { "type": "string", "description": "ID of the target capability in the relationship." }, "relationship_type": { "type": "string", "description": "Type of the relationship." }, "strength": { "type": "number", "description": "Strength of the relationship, indicating influence or dependency." } } } }, "metadata": { "type": "object", "description": "Additional metadata associated with the capability.", "properties": { "trend_direction": { "type": "string", "description": "The current trend direction of the capability." }, "supply_count": { "type": "integer", "description": "Current supply count of the capability." }, "demand_count": { "type": "integer", "description": "Current demand count of the capability." }, "usage_count": { "type": "integer", "description": "Current usage count of the capability." } } } }, "required": [ "id", "canonical_name", "category", "description" ] }, "examples": { "acme_corp's_ai_negotiation_capability": { "summary": "Acme Corp's AI Negotiation Capability", "description": "An example highlighting a capability used by Acme Corp to enhance AI negotiation skills.", "value": { "id": "cap_ai_negotiation", "canonical_name": "AI Negotiation", "category": "AI Skills", "subcategory": "Negotiation", "domain": "Artificial Intelligence", "description": "Enables AI systems to effectively negotiate agreements.", "relationships": [ { "from_capability_id": "cap_ai_negotiation", "to_capability_id": "cap_ai_language_processing", "relationship_type": "depends_on", "strength": 0.85 } ], "metadata": { "trend_direction": "upward", "supply_count": 120, "demand_count": 300, "usage_count": 250 } } } } } } }, "400": { "description": "Invalid request due to malformed capability_id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_capability_id_example": { "summary": "Invalid Capability ID Example", "description": "An example of a request that failed due to an invalid capability_id.", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-request", "title": "Invalid Capability ID", "status": 400, "detail": "The provided capability_id parameter was invalid. Expected a non-empty string.", "errors": [ { "field": "capability_id", "code": "INVALID_VALUE", "message": "Invalid capability_id path parameter", "expected": "non-empty string", "received": "" } ] } } } } } }, "404": { "description": "Capability not found for the given ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "non-existent_capability_example": { "summary": "Non-existent Capability Example", "description": "An example where the capability ID does not exist in the database.", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Capability Not Found", "status": 404, "detail": "No capability found for the given ID." } } } } } }, "500": { "description": "Internal server error when retrieving capability details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An example where an unexpected server error occurs.", "value": { "type": "https://docs.humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/capabilities/definitions": { "get": { "summary": "Retrieve capability definitions list", "description": "Uncover the breadth of skills tracked within the HUMAN ecosystem. This endpoint offers a window into the capabilities that define our dynamic landscape, with filters to cater to your specific interests—be it canonical, organizational, or a blend of both.", "operationId": "getCapabilitiesDefinitions", "tags": [ "Capabilities", "Definitions" ], "x-code-hash": "1ec01c5bd18bb31c", "x-generated-at": "2026-04-27T17:01:42.964Z", "responses": { "200": { "description": "A list of capability definitions successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "definitions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "canonical_name": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "domain": { "type": "string" }, "description": { "type": "string" }, "synonyms_json": { "type": "string" }, "status": { "type": "string" }, "scope": { "type": "string" }, "org_slug": { "type": "string", "nullable": true }, "governance_tier": { "type": "string" }, "classification": { "type": "string" }, "curator_approved": { "type": "boolean" }, "usage_count": { "type": "integer" }, "promotion_candidate": { "type": "boolean" }, "canonical_equivalent": { "type": "string", "nullable": true }, "version": { "type": "integer" }, "examples_json": { "type": "string" }, "embedding_json": { "type": "string" }, "relationships_json": { "type": "string" }, "trend_direction": { "type": "string" }, "supply_count": { "type": "integer" }, "demand_count": { "type": "integer" }, "semantic_drift": { "type": "string" }, "metadata_json": { "type": "string" }, "promoted_from": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "canonical_name", "status", "scope", "created_at", "updated_at" ] } }, "count": { "type": "integer" } }, "required": [ "definitions", "count" ] }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "value": { "definitions": [ { "id": "capability-001", "canonical_name": "invoice_processing", "category": "finance", "subcategory": "accounts_payable", "domain": "acme", "description": "Processes and verifies invoices for payment.", "synonyms_json": "['invoice approval', 'billing management']", "status": "active", "scope": "canonical", "org_slug": null, "governance_tier": "standard", "classification": "trusted", "curator_approved": true, "usage_count": 1500, "promotion_candidate": false, "canonical_equivalent": null, "version": 3, "examples_json": "[]", "embedding_json": "{}", "relationships_json": "{}", "trend_direction": "upward", "supply_count": 1200, "demand_count": 900, "semantic_drift": "stable", "metadata_json": "{}", "promoted_from": null, "created_at": "2023-10-15T12:00:00Z", "updated_at": "2023-10-15T12:00:00Z" } ], "count": 1 } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_scope_value": { "summary": "Invalid Scope Value", "value": { "type": "https://humanprotocol.org/api/error/invalid-request", "title": "Invalid request parameters.", "status": 400, "detail": "One or more request parameters are invalid.", "errors": [ { "field": "scope", "code": "INVALID_VALUE", "message": "Scope must be canonical, org, or all", "expected": "canonical, org, all", "received": "global" } ] } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "value": { "type": "https://humanprotocol.org/api/error/unauthorized", "title": "Unauthorized access.", "status": 401, "detail": "Authentication is required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "value": { "type": "https://humanprotocol.org/api/error/forbidden", "title": "Forbidden access.", "status": 403, "detail": "You do not have the necessary permissions to access this resource." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "capability_not_found": { "summary": "Capability Not Found", "value": { "type": "https://humanprotocol.org/api/error/not-found", "title": "Resource not found.", "status": 404, "detail": "The requested capability definition could not be found." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "https://humanprotocol.org/api/error/internal-server-error", "title": "Internal server error.", "status": 500, "detail": "An unexpected error occurred on the server." } } } } } } } }, "post": { "summary": "Create a new capability definition", "description": "Crafting a new capability is like sculpting the future of your organization. This endpoint empowers you to define the skills and tasks your AI can perform, embedding them into the HUMAN ecosystem. Use it to expand your capabilities and push the boundaries of what’s possible.", "operationId": "createCapabilityDefinition", "tags": [ "Capabilities", "HUMAN" ], "x-code-hash": "bd77528164f1c3c2", "x-generated-at": "2026-04-27T17:01:56.985Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the capability" }, "scope": { "type": "string", "description": "The scope of the capability, e.g., 'canonical' or 'custom'" }, "status": { "type": "string", "description": "The status of the capability, e.g., 'active' or 'inactive'" } }, "required": [ "id", "scope", "status" ] }, "examples": { "basic_capability_definition": { "summary": "Basic Capability Definition", "description": "Creating a custom capability for invoice processing", "value": { "id": "capability_12345", "scope": "custom", "status": "active" } } } } } }, "responses": { "201": { "description": "The capability definition was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the created capability" }, "scope": { "type": "string", "description": "The scope of the newly created capability" }, "status": { "type": "string", "description": "The status of the newly created capability" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid capability definition provided", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Authentication required to create a capability", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Insufficient permissions for creating a canonical capability", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "Server error occurred while creating capability", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/capabilities/definitions/import": { "post": { "summary": "Import capability definitions into HUMAN", "description": "Effortlessly expand your HUMAN capabilities by importing definitions. This endpoint empowers organizations to seamlessly introduce new capability structures, ensuring that your AI-human collaborations remain cutting-edge and adaptable. Whether you're avoiding conflicts or overwriting existing entries, this tool is designed to enhance your capability graph with ease.", "operationId": "importCapabilityDefinitions", "tags": [ "Capabilities", "Import" ], "x-code-hash": "761735ea6628d741", "x-generated-at": "2026-04-27T17:02:15.356Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definitions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the capability" }, "name": { "type": "string", "description": "Name of the capability" }, "description": { "type": "string", "description": "Detailed description of what the capability entails" } }, "required": [ "id", "name" ] }, "description": "Array of capability definitions to be imported" }, "conflict_strategy": { "type": "string", "enum": [ "skip", "overwrite", "fail" ], "description": "Strategy to handle conflicts with existing definitions" }, "scope": { "type": "string", "enum": [ "canonical", "org" ], "description": "Scope of the import operation" } }, "required": [ "definitions" ] }, "examples": { "basic_import_example": { "summary": "Basic Import Example", "description": "Example showing a typical import with conflict resolution strategy", "value": { "definitions": [ { "id": "cap_001", "name": "Data Processing", "description": "Processes incoming data streams for analysis." } ], "conflict_strategy": "overwrite", "scope": "org" } } } } } }, "responses": { "200": { "description": "Capability definitions successfully imported", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported_count": { "type": "integer", "description": "Number of definitions successfully imported" }, "skipped_count": { "type": "integer", "description": "Number of definitions skipped due to conflicts" }, "imported": { "type": "integer", "description": "Alias for imported_count" }, "skipped": { "type": "integer", "description": "Alias for skipped_count" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Index of the definition in the request" }, "error": { "type": "string", "description": "Error message for the failed import" } } }, "description": "List of errors encountered during import" } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad request due to validation errors", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Insufficient permissions for the requested operation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "Internal server error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/capabilities/definitions/:id/promote": { "post": { "summary": "Promote a Capability Definition", "description": "Elevate an organizational capability to a canonical level, ensuring its availability for broader use across the HUMAN platform. This action requires careful authorization and is recorded for provenance.", "operationId": "promoteCapabilityDefinition", "tags": [ "Capabilities", "Promotion" ], "x-code-hash": "e0972b77bbf0f27e", "x-generated-at": "2026-04-27T17:02:31.553Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "canonicalId": { "type": "string", "description": "The canonical ID for the capability to promote" }, "justification": { "type": "string", "description": "Reason for promoting this capability" }, "approvedBy": { "type": "string", "description": "Passport DID of the approving authority" } }, "required": [ "canonicalId", "approvedBy" ] }, "examples": { "promote_invoice_processing_capability": { "summary": "Promote Invoice Processing Capability", "description": "Promoting an 'Invoice Processing' capability to canonical status for broader ecosystem use.", "value": { "canonicalId": "cap_123456", "justification": "High demand across multiple organizations", "approvedBy": "did:human:1234abcd" } } } } } }, "responses": { "200": { "description": "The capability definition was successfully promoted to canonical status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_capability_id": { "type": "string", "description": "Original ID of the organizational capability" }, "canonical_capability_id": { "type": "string", "description": "New canonical ID of the promoted capability" }, "status": { "type": "string", "enum": [ "promoted" ], "description": "The status of the promotion process" } } }, "examples": { "default": { "summary": "Example", "value": { "org_capability_id": "org_cap_7890", "canonical_capability_id": "cap_123456", "status": "promoted" } } } } } }, "400": { "description": "Invalid request due to missing or malformed parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body is missing required fields or has invalid values.", "errors": [ { "field": "canonicalId", "code": "REQUIRED_FIELD_MISSING", "message": "canonicalId is required", "expected": "canonical capability ID", "received": "undefined" } ] } } } } } }, "401": { "description": "Authentication failure due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation required. Please provide valid delegation credentials." } } } } } }, "403": { "description": "Authorization failure due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/authorization-error", "title": "Authorization Error", "status": 403, "detail": "Insufficient permissions to promote capabilities. Ensure the delegation includes 'human_api:capabilities:promote'." } } } } } }, "404": { "description": "The specified capability definition was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "Capability definition with ID 'org_cap_7890' not found." } } } } } }, "500": { "description": "Internal server error during capability promotion.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://docs.humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while promoting the capability. Please try again later." } } } } } } } } }, "/v1/capabilities/definitions/:id": { "delete": { "summary": "Safely remove capability definition", "description": "This endpoint allows you to delete a capability definition when it is safe to do so. It ensures that no active nodes or grants are referencing the definition, maintaining the integrity of the system. Explore the dynamics of capability management as you streamline your organization's skills graph.", "operationId": "deleteCapabilityDefinition", "tags": [ "Capability Management", "Security" ], "x-code-hash": "2ae2c5a141a9db1c", "x-generated-at": "2026-04-27T17:02:49.245Z", "responses": { "200": { "description": "The capability definition was successfully deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "The ID of the deleted capability definition." }, "deleted": { "type": "boolean", "description": "Indicates deletion success." }, "deleted_at": { "type": "string", "format": "date-time", "description": "Timestamp when the capability definition was deleted." } } }, "examples": { "successful_deletion": { "summary": "Successful deletion", "description": "A capability definition removed from the system successfully.", "value": { "capability_id": "def456", "deleted": true, "deleted_at": "2023-10-14T08:42:00Z" } } } } } }, "400": { "description": "The request was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_id": { "summary": "Invalid ID", "description": "The ID provided was invalid.", "value": { "type": "https://human.example.com/probs/invalid-id", "title": "Invalid definition ID", "status": 400, "detail": "The definition ID is invalid. Please provide a non-empty capability definition ID.", "errors": [ { "field": "id", "code": "INVALID_VALUE", "message": "Invalid definition id", "expected": "non-empty capability definition id", "received": "" } ] } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "description": "Delegation was not provided in the request.", "value": { "type": "https://human.example.com/probs/unauthorized", "title": "Delegation required", "status": 401, "detail": "Delegation is required to authenticate the request. Please include a valid delegation token." } } } } } }, "403": { "description": "Forbidden action due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_canonical_deletion": { "summary": "Forbidden canonical deletion", "description": "Attempt to delete a canonical capability without proper permissions.", "value": { "type": "https://human.example.com/probs/forbidden", "title": "Insufficient permissions", "status": 403, "detail": "You lack the necessary permissions to delete canonical definitions. Ensure you have 'human_api:capabilities:create:canonical' scope." } } } } } }, "404": { "description": "The specified capability definition was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "definition_not_found": { "summary": "Definition not found", "description": "The capability definition ID does not exist.", "value": { "type": "https://human.example.com/probs/not-found", "title": "Capability definition not found", "status": 404, "detail": "No capability definition found with the specified ID. Verify the ID and try again." } } } } } }, "409": { "description": "Conflict due to existing references.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "conflict_due_to_references": { "summary": "Conflict due to references", "description": "Cannot delete due to existing nodes and grants.", "value": { "type": "https://human.example.com/probs/conflict", "title": "Deletion conflict", "status": 409, "detail": "Cannot delete capability definition while capability_nodes or capability_grants still reference it.", "errors": { "capability_id": "def456", "references": { "capability_nodes": 2, "capability_grants": 1 } } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "An error occurred during processing.", "value": { "type": "https://human.example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/capabilities/packages": { "get": { "summary": "Retrieve available ontology packages", "description": "Dive into the world of HUMAN's ontology packages, where AI capabilities are meticulously organized and tracked. This endpoint offers a window into the published skill sets, empowering you to explore, evaluate, and integrate them seamlessly into your workflow.", "operationId": "getOntologyPackages_1", "tags": [ "Ontology", "Capabilities" ], "x-code-hash": "06cf91bd5ab084c6", "x-generated-at": "2026-04-27T17:03:07.114Z", "responses": { "200": { "description": "Successfully retrieved ontology packages with details such as version, publisher, and scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "packages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "publisher": { "type": "object", "properties": { "did": { "type": "string" }, "name": { "type": "string" } } }, "name": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string" }, "license": { "type": "string" }, "capability_count": { "type": "integer" }, "status": { "type": "string" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "count": { "type": "integer" } } }, "examples": { "ontology_package_retrieval": { "summary": "Ontology Package Retrieval", "description": "Fetching a list of ontology packages published by Acme Corp.", "value": { "packages": [ { "id": "pkg-001", "version": "1.0.0", "publisher": { "did": "did:example:acme", "name": "Acme Corp" }, "name": "Invoice Processing", "description": "A package that enables invoice data extraction and processing.", "scope": "org", "license": "MIT", "capability_count": 5, "status": "published", "published_at": "2023-10-05T14:48:00.000Z" } ], "count": 1 } } } } } }, "400": { "description": "Bad request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-query", "title": "Invalid query parameter", "status": 400, "detail": "The parameter 'scope' must be either 'canonical' or 'org'.", "errors": [ "scope" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication", "title": "Unauthorized", "status": 401, "detail": "You must authenticate with a valid Passport to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/insufficient-permissions", "title": "Forbidden", "status": 403, "detail": "Your current Passport does not have the required capabilities to access this resource." } } } } } }, "404": { "description": "Ontology packages not found due to incorrect path.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested ontology packages could not be located." } } } } } }, "500": { "description": "Internal server error during ontology package retrieval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while retrieving ontology packages. Please try again later." } } } } } } } } }, "/v1/capabilities/packages/:id/:version": { "get": { "summary": "Retrieve specific capability package version", "description": "Delve into the rich tapestry of skills by fetching a specific version of a capability package. This endpoint is your gateway to understanding the evolution and offerings of a package within the HUMAN ecosystem, providing both provenance and potential.", "operationId": "getCapabilitiesPackageVersion", "tags": [ "Capabilities", "Packages" ], "x-code-hash": "551358b704ed21d8", "x-generated-at": "2026-04-27T17:03:33.309Z", "responses": { "200": { "description": "The capability package was successfully retrieved, revealing its details and history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the package" }, "version": { "type": "string", "description": "Version of the package" }, "publisher": { "type": "object", "properties": { "did": { "type": "string", "description": "DID of the publisher" }, "name": { "type": "string", "description": "Name of the publisher" } } }, "name": { "type": "string", "description": "Name of the capability package" }, "description": { "type": "string", "description": "Detailed description of the package capabilities" }, "scope": { "type": "string", "description": "Scope of the package" }, "license": { "type": "string", "description": "License under which the package is distributed" }, "pricing": { "type": [ "object", "null" ], "properties": { "amount": { "type": "number", "description": "Price amount" }, "currency": { "type": "string", "description": "Currency code" }, "billing_period": { "type": "string", "description": "Billing period" } }, "nullable": true }, "capability_count": { "type": "integer", "description": "Number of capabilities included in the package" }, "status": { "type": "string", "description": "Current status of the package" }, "changelog": { "type": [ "string", "null" ], "description": "Changelog of the package", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp of the package" }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Publication timestamp of the package", "nullable": true } } }, "examples": { "successful_retrieval": { "summary": "Successful Retrieval", "description": "Retrieving the 'acme-invoice-processor' package version 1.2.0", "value": { "id": "acme-invoice-processor", "version": "1.2.0", "publisher": { "did": "did:human:123456789abcdefghi", "name": "Acme Corp" }, "name": "Invoice Processor", "description": "A powerful tool for processing and automating invoice workflows.", "scope": "enterprise", "license": "MIT", "pricing": { "amount": 49.99, "currency": "USD", "billing_period": "monthly" }, "capability_count": 15, "status": "active", "changelog": "Added new OCR feature for faster invoice scanning.", "created_at": "2023-08-10T14:48:00Z", "published_at": "2023-09-01T10:00:00Z" } } } } } }, "400": { "description": "Invalid request due to malformed ID or version parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_parameters": { "summary": "Malformed Parameters", "description": "Occurs when the ID is improperly formatted.", "value": { "type": "/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The provided ID or version format is incorrect." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_auth_token": { "summary": "Missing Auth Token", "description": "Occurs when no authentication token is provided.", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication token is missing or invalid." } } } } } }, "403": { "description": "Forbidden access when the user lacks permission to view the package.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access Denied", "description": "Occurs when a user tries to access a restricted package.", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested package version was not found in the system.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "package_not_found": { "summary": "Package Not Found", "description": "Occurs when the specified package version does not exist.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The package with ID 'acme-invoice-processor' and version '1.2.0' was not found." } } } } } }, "500": { "description": "Internal server error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "Occurs when an unhandled exception is thrown.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An internal error occurred. Please try your request again or contact support if the issue persists." } } } } } } } } }, "/v1/capabilities/proofs": { "post": { "summary": "Generate a Capability Proof", "description": "Unlock the potential of your digital identity by generating a cryptographic proof of capabilities tied to your Passport. This endpoint ensures active capability grants, empowering secure and verifiable interactions across the HUMAN platform.", "operationId": "postCapabilityProofs", "tags": [ "Capabilities", "Security" ], "x-code-hash": "37d323d02281a207", "x-generated-at": "2026-04-27T17:03:57.398Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "Passport decentralized identifier (DID)" }, "capabilities": { "type": "array", "items": { "type": "string", "description": "Capability ID" }, "description": "List of capability identifiers to prove" }, "proof_type": { "type": "string", "description": "Type of proof, defaults to 'attestation'", "default": "attestation" }, "valid_for": { "type": "integer", "description": "Duration in seconds for which the proof is valid" } }, "required": [ "did", "capabilities" ] }, "examples": { "typical_capability_proof_request": { "summary": "Typical Capability Proof Request", "description": "Requesting a proof for specific capabilities linked to a Passport DID.", "value": { "did": "did:human:acme:12345", "capabilities": [ "capability://task.read", "capability://invoice.approve" ], "proof_type": "attestation", "valid_for": 3600 } } } } } }, "responses": { "201": { "description": "Capability proof successfully created, detailing the proof data and verification URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proof_id": { "type": "string", "description": "Unique identifier for the generated proof" }, "proof_data": { "type": "string", "description": "Encoded data representing the capability proof" }, "capabilities_proven": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "ID of the capability proven" }, "weight_range": { "type": "string", "description": "Confidence interval for the capability" }, "confidence": { "type": "number", "description": "Confidence level of the capability grant" } } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of proof creation" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when proof expires, or null if it does not expire" }, "verification_url": { "type": "string", "format": "uri", "description": "URL to verify the proof" } } }, "examples": { "successful_proof_creation": { "summary": "Successful Proof Creation", "description": "Proof created for a user's capabilities with a verification link.", "value": { "proof_id": "proof_67890", "proof_data": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...", "capabilities_proven": [ { "capability_id": "capability://task.read", "weight_range": "90-100", "confidence": 95 }, { "capability_id": "capability://invoice.approve", "weight_range": "80-90", "confidence": 85 } ], "created_at": "2023-10-26T15:30:00Z", "expires_at": "2023-10-26T16:30:00Z", "verification_url": "https://verify.human.xyz/proofs/proof_67890" } } } } } }, "400": { "description": "Bad Request due to missing or invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_did_and_capabilities": { "summary": "Missing DID and Capabilities", "description": "Request failed due to missing DID and capabilities fields.", "value": { "type": "https://human.xyz/errors/validation", "title": "Validation Error", "status": 400, "detail": "One or more fields are invalid.", "errors": [ { "field": "did", "code": "REQUIRED_FIELD_MISSING", "message": "DID is required", "expected": "Passport DID", "received": "undefined" }, { "field": "capabilities", "code": "REQUIRED_FIELD_MISSING", "message": "capabilities array is required", "expected": "array of capability IDs", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_credentials": { "summary": "Invalid Credentials", "description": "The request was made with invalid authentication credentials.", "value": { "type": "https://human.xyz/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Invalid authentication credentials provided." } } } } } }, "403": { "description": "Forbidden action due to lack of permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have permission to perform this action.", "value": { "type": "https://human.xyz/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create capability proofs." } } } } } }, "404": { "description": "Not Found when a resource is inaccessible.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "did_not_found": { "summary": "DID Not Found", "description": "The specified DID does not exist or is inaccessible.", "value": { "type": "https://human.xyz/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified DID does not exist." } } } } } }, "500": { "description": "Internal server error due to unexpected issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server error occurred while processing the request.", "value": { "type": "https://human.xyz/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capabilities/proofs/verify": { "post": { "summary": "Verify Capability Proofs for Authorization", "description": "In the HUMAN protocol, verifying capability proofs is essential for ensuring that agents possess the necessary skills to execute a task. This endpoint authenticates the validity of a submitted proof, safeguarding against expired, inactive, or mismatched data, and ensuring trust in the orchestration process.", "operationId": "verifyCapabilityProofs", "tags": [ "Capabilities", "Verification" ], "x-code-hash": "975356336114ff94", "x-generated-at": "2026-04-27T17:04:20.910Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proof_id": { "type": "string", "description": "The unique identifier for the capability proof." }, "proof_data": { "type": "string", "description": "The cryptographic data associated with the capability proof." } }, "required": [ "proof_id", "proof_data" ] }, "examples": { "verify_capability_for_invoice_processing": { "summary": "Verify Capability for Invoice Processing", "description": "Validates that an agent from 'acme' organization has the verified capability to process invoices.", "value": { "proof_id": "proof-12345", "proof_data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } }, "responses": { "200": { "description": "The capability proof is successfully verified, confirming the agent's skills.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Indicates whether the proof is valid." }, "did": { "type": "string", "description": "Decentralized Identifier (DID) of the agent whose proof was verified." }, "capabilities_verified": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "The unique identifier of the verified capability." }, "meets_threshold": { "type": "boolean", "description": "Indicates if the capability meets the required confidence threshold." }, "verified_weight": { "type": "string", "description": "The confidence level of the verified capability." } } } }, "verified_at": { "type": "string", "format": "date-time", "description": "The timestamp when the proof was verified." }, "trust_score": { "type": "number", "description": "Trust score computed based on the verified capabilities." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request due to missing or malformed proof data.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "Capability proof not found for the given identifier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "Internal server error due to unexpected issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/capabilities/search": { "get": { "summary": "Search for Capability Grants by Skills", "description": "Unleash the potential of your human and AI workforce by discovering capability grants that match specific skills and criteria. This endpoint allows you to find the right skill sets by filtering through various parameters, ensuring you connect with the most suitable capabilities for your needs.", "operationId": "getCapabilitiesSearch", "tags": [ "Capabilities", "Search" ], "x-code-hash": "c76291d206b5d732", "x-generated-at": "2026-04-27T17:04:43.761Z", "responses": { "200": { "description": "A list of capability grants matching the search criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "passport_did": { "type": "string" }, "capability_id": { "type": "string" }, "confidence": { "type": "number" }, "granted_at": { "type": "string", "format": "date-time" }, "capability": { "type": "object", "properties": { "id": { "type": "string" }, "canonical_name": { "type": "string" }, "domain": { "type": "string" }, "category": { "type": "string" } } } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "meta": { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "string" } }, "sort": { "type": "string" }, "pagination": { "type": "object", "properties": { "mode": { "type": "string" }, "order": { "type": "string" } } }, "applied_filters": { "type": "object", "properties": { "min_weight": { "type": "number" }, "domains_in": { "type": "array", "items": { "type": "string" } }, "experience_years__gte": { "type": [ "number", "null" ] } } } } } } }, "examples": { "acme_corp_skill_search": { "summary": "Acme Corp Skill Search", "description": "Acme Corp is looking for AI capabilities in data processing with a minimum confidence weight.", "value": { "data": [ { "passport_did": "did:human:123456789abcdef", "capability_id": "cap-001", "confidence": 0.95, "granted_at": "2023-10-01T15:20:00Z", "capability": { "id": "cap-def-001", "canonical_name": "Data Processing", "domain": "AI", "category": "Data Science" } } ], "has_more": false, "next_cursor": null, "meta": { "skills": [ "data-processing" ], "sort": "-weight,granted_at", "pagination": { "mode": "keyset", "order": "confidence_desc,granted_at_desc,passport_did_desc,capability_id_desc" }, "applied_filters": { "min_weight": 0.8, "domains_in": [ "AI" ], "experience_years__gte": 2 } } } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found error for resources that could not be located.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/capabilities/evidence/credential": { "post": { "summary": "Submit verifiable credential evidence", "description": "This endpoint empowers organizations to submit evidence of capabilities through verifiable credentials, establishing trust in a world where humans and AI collaborate seamlessly. It ensures that each capability is backed by cryptographic proof, enhancing the trustworthiness of skill attestations.", "operationId": "submitCredentialEvidence", "tags": [ "Capabilities", "Evidence" ], "x-code-hash": "efbcd3003e503a47", "x-generated-at": "2026-04-27T17:05:10.133Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "The decentralized identifier for the passport, serving as the canonical identity." }, "credential_id": { "type": "string", "description": "The unique identifier of the verifiable credential being submitted." }, "capabilities_attested": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "The identifier of the capability being attested." }, "attestation_level": { "type": "string", "description": "Optional heuristic level of attestation for the capability." } }, "required": [ "capability_id" ] }, "description": "An array of capabilities being attested, each with an optional attestation level." } }, "required": [ "passport_did", "credential_id", "capabilities_attested" ] }, "examples": { "submit_capability_evidence_for_employee_skills": { "summary": "Submit Capability Evidence for Employee Skills", "description": "An organization 'acme' submits a credential that attests to an employee's skills in data analysis and project management.", "value": { "passport_did": "did:example:123456789abcdefghi", "credential_id": "cred-123456", "capabilities_attested": [ { "capability_id": "data_analysis", "attestation_level": "high" }, { "capability_id": "project_management" } ] } } } } } }, "responses": { "201": { "description": "The evidence was successfully recorded, verifying the capabilities attested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_id": { "type": "string", "description": "Identifier for the evidence submission." }, "status": { "type": "string", "description": "The status of the submission." }, "verification_status": { "type": "string", "description": "Indicates whether the credential was fully or partially verified." }, "passport_did": { "type": "string", "description": "The DID of the passport associated with the submission." }, "credential_id": { "type": "string", "description": "The ID of the credential submitted." }, "capabilities_updated": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "ID of the capability that was updated." }, "new_weight": { "type": "number", "description": "The new confidence weight assigned to the capability." }, "confidence": { "type": "number", "description": "The blended confidence score for the capability." }, "grant_id": { "type": "string", "description": "Unique identifier for the capability grant." } } } }, "recorded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the evidence was recorded." } } }, "examples": { "default": { "summary": "Example", "value": { "evidence_id": "cgcr-987654", "status": "accepted", "verification_status": "verified", "passport_did": "did:example:123456789abcdefghi", "credential_id": "cred-123456", "capabilities_updated": [ { "capability_id": "data_analysis", "new_weight": 0.95, "confidence": 0.95, "grant_id": "cgev-123456" }, { "capability_id": "project_management", "new_weight": 0.85, "confidence": 0.85, "grant_id": "cgev-654321" } ], "recorded_at": "2023-10-11T12:34:56Z" } } } } } }, "400": { "description": "The request was malformed or contained invalid data. Check the error messages for specific fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/validation", "title": "Invalid Request", "status": 400, "detail": "The request contains invalid fields.", "errors": [ { "field": "credential_id", "code": "REQUIRED_FIELD_MISSING", "message": "credential_id is required", "expected": "non-empty string", "received": "''" } ] } } } } } }, "401": { "description": "Authentication is required to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "No valid authentication credentials provided. Please log in and try again." } } } } } }, "403": { "description": "The credential issuer is not allowlisted for capability evidence submission.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/forbidden", "title": "Issuer not allowlisted", "status": 403, "detail": "The credential issuer's DID is not on the allowlist. Update the allowlist to include this issuer." } } } } } }, "404": { "description": "The specified credential ID does not correspond to any known attestation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/not-found", "title": "Credential not found", "status": 404, "detail": "No attestation stored for credential_id 'cred-123456'. Issue or register the VC before submitting capability evidence." } } } } } }, "500": { "description": "An unexpected error occurred on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/capabilities/evidence/training": { "post": { "summary": "Submit Capability Training Evidence", "description": "This endpoint is a gateway to empower learners by formalizing their educational milestones into recognized capabilities. By submitting evidence of training completion, you unlock new doors for skill acknowledgment within the HUMAN network, propelling your journey of continuous growth.", "operationId": "postCapabilityTrainingEvidence", "tags": [ "Capabilities", "Training" ], "x-code-hash": "4b8bdaa38e55d85d", "x-generated-at": "2026-04-27T17:05:45.755Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "The Digital Identity (DID) of the learner's passport." }, "course_id": { "type": "string", "description": "Identifier for the completed course." }, "completion_date": { "type": "string", "format": "date-time", "description": "Date when the course was completed, formatted as ISO 8601." }, "assessment_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score reflecting learner's performance, ranging from 0 to 1." }, "capabilities_learned": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "Identifier for the learned capability." }, "proficiency_level": { "type": "string", "description": "Optional proficiency level attained." } }, "required": [ "capability_id" ] }, "description": "List of capabilities acquired from the course." } }, "required": [ "passport_did", "course_id", "completion_date", "assessment_score", "capabilities_learned" ] }, "examples": { "successful_training_evidence_submission": { "summary": "Successful Training Evidence Submission", "description": "A complete request showing how a learner's training completion can be submitted.", "value": { "passport_did": "did:human:123456789abcdefghi", "course_id": "course-2023-xyz", "completion_date": "2023-10-15T10:00:00Z", "assessment_score": 0.85, "capabilities_learned": [ { "capability_id": "cap-1234", "proficiency_level": "intermediate" } ] } } } } } }, "responses": { "201": { "description": "Evidence submission accepted, capabilities updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_id": { "type": "string", "description": "Unique identifier for the submitted evidence." }, "status": { "type": "string", "enum": [ "accepted" ], "description": "Status of the submission." }, "passport_did": { "type": "string", "description": "DID of the learner's passport." }, "course_id": { "type": "string", "description": "ID of the completed course." }, "completion_date": { "type": "string", "format": "date-time", "description": "ISO 8601 formatted completion date." }, "assessment_score": { "type": "number", "description": "Learner's assessment score." }, "capabilities_updated": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "ID of the updated capability." }, "new_weight": { "type": "number", "description": "New confidence weight for the capability." }, "confidence": { "type": "number", "description": "Confidence score for the capability update." }, "grant_id": { "type": "string", "description": "Unique ID for the capability grant." }, "growth_pathway": { "type": "string", "description": "Growth pathway derived from proficiency." } } }, "description": "Array of capabilities that were updated as a result of this submission." }, "recorded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the evidence was recorded." } } }, "examples": { "default": { "summary": "Example", "value": { "evidence_id": "cgtr-20231015100000", "status": "accepted", "passport_did": "did:human:123456789abcdefghi", "course_id": "course-2023-xyz", "completion_date": "2023-10-15T10:00:00Z", "assessment_score": 0.85, "capabilities_updated": [ { "capability_id": "cap-1234", "new_weight": 0.85, "confidence": 0.85, "grant_id": "cgev-20231015100001", "growth_pathway": "intermediate" } ], "recorded_at": "2023-10-15T10:05:00Z" } } } } } }, "400": { "description": "Bad Request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request was invalid due to missing fields.", "errors": [ { "field": "passport_did", "code": "REQUIRED_FIELD_MISSING", "message": "passport_did is required (or did per kb/97)", "expected": "string (DID)", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access to the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "The request requires user authentication. Please provide valid authorization credentials." } } } } } }, "403": { "description": "Forbidden, permission denied to access this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Check your access rights or contact support." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found on this server. It might have been removed, or you may be using an incorrect URL." } } } } } }, "500": { "description": "Internal Server Error, an unexpected condition was encountered.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human-protocol.org/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "The server encountered an internal error and could not complete your request. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/capabilities/evidence": { "post": { "summary": "Record evidence for capability grant", "description": "Submit evidence to validate a capability grant in the HUMAN ecosystem. This endpoint empowers organizations to substantiate their skill claims with trusted data, ensuring integrity in a collaborative workflow.", "operationId": "postCapabilitiesEvidence", "tags": [ "Capability Graph", "Evidence Submission" ], "x-code-hash": "6c003433b6553306", "x-generated-at": "2026-04-27T17:06:03.123Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "The decentralized identifier (DID) of the passport." }, "capability_id": { "type": "string", "description": "Identifier of the capability being evidenced." }, "evidence": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of the evidence, e.g., 'manual'." }, "description": { "type": "string", "description": "Narrative or details about the evidence." }, "reference_uri": { "type": "string", "description": "Optional URI linking to external reference for the evidence." } }, "required": [ "type" ] } }, "required": [ "passport_did", "capability_id", "evidence" ] }, "examples": { "basic_evidence_submission": { "summary": "Basic Evidence Submission", "description": "Submits evidence for a skill grant with manual verification.", "value": { "passport_did": "did:human:123456789abcdefghi", "capability_id": "capability://acme/coding", "evidence": { "type": "manual", "description": "Completed a code review session with a senior developer.", "reference_uri": "https://acme.com/evidence/123" } } } } } } }, "responses": { "201": { "description": "Evidence recorded successfully, creating a new capability grant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "description": "Unique identifier for the capability grant." }, "passport_did": { "type": "string", "description": "The DID of the passport associated with the grant." }, "capability_id": { "type": "string", "description": "The ID of the capability being granted." }, "status": { "type": "string", "description": "Status of the grant, typically 'active'." }, "recorded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the evidence was recorded." } } }, "examples": { "default": { "summary": "Example", "value": { "grant_id": "cgev_987654321abcdefghi", "passport_did": "did:human:123456789abcdefghi", "capability_id": "capability://acme/coding", "status": "active", "recorded_at": "2023-10-12T07:20:50.52Z" } } } } } }, "400": { "description": "Bad Request due to missing or invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/problem/validation-error", "title": "Validation Error", "status": 400, "detail": "One or more fields are invalid.", "errors": [ { "field": "passport_did", "code": "REQUIRED_FIELD_MISSING", "message": "passport_did is required", "expected": "string (DID)", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/problem/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials are missing or invalid." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/problem/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Not Found due to invalid capability ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/problem/not-found", "title": "Not Found", "status": 404, "detail": "Capability ID not found or invalid." } } } } } }, "500": { "description": "Internal Server Error due to unexpected failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://human.com/problem/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/capabilities/growth/:did": { "get": { "summary": "Retrieve monthly capability growth data", "description": "Explore the trajectory of a specific capability over time to understand patterns and make informed decisions. This endpoint provides a historical view of capability grants, helping organizations track their evolution and assess future trends.", "operationId": "getCapabilityGrowth", "tags": [ "Capabilities", "Analytics" ], "x-code-hash": "55e8e6971e48dd1e", "x-generated-at": "2026-04-27T17:06:20.771Z", "responses": { "200": { "description": "Successfully retrieved monthly growth data for the specified capability.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized Identifier for the capability owner" }, "capability_id": { "type": "string", "description": "Unique identifier for the capability being analyzed" }, "timeframe": { "type": "string", "description": "The timeframe over which growth is analyzed" }, "data_points": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the data point" }, "weight": { "type": "number", "description": "Confidence weight of the capability at the time" }, "evidence_count": { "type": "integer", "description": "Cumulative number of grants" } } } }, "trend": { "type": "string", "description": "Current trend of the capability growth" }, "growth_rate": { "type": "string", "description": "Growth rate comparison with previous period" }, "weight_source": { "type": "string", "description": "Source of the weight calculation" }, "projection": { "type": "object", "properties": { "weight_in_30d": { "type": "number", "description": "Projected weight in 30 days" }, "confidence": { "type": "number", "description": "Confidence level of the growth projection" } } } } }, "examples": { "successful_growth_data_retrieval": { "summary": "Successful growth data retrieval", "description": "Retrieving growth data for capability 'invoice-processing' for DID 'did:example:acme123'.", "value": { "did": "did:example:acme123", "capability_id": "invoice-processing", "timeframe": "90d", "data_points": [ { "timestamp": "2023-07-01T00:00:00Z", "weight": 0.8, "evidence_count": 5 }, { "timestamp": "2023-08-01T00:00:00Z", "weight": 0.85, "evidence_count": 10 } ], "trend": "improving", "growth_rate": "+5.88% vs prior weight", "weight_source": "capability_node_weights", "projection": { "weight_in_30d": 0.87, "confidence": 0.95 } } } } } } }, "400": { "description": "Bad request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_did": { "summary": "Invalid DID", "description": "The provided DID is invalid.", "value": { "type": "/problems/invalid-parameter", "title": "Invalid Request Parameters", "status": 400, "detail": "One or more request parameters are invalid.", "errors": [ { "field": "did", "code": "INVALID_VALUE", "message": "Invalid DID parameter", "expected": "non-empty string", "received": "" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authentication": { "summary": "Missing Authentication", "description": "The request is missing valid authentication credentials.", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Missing or invalid authentication token." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied": { "summary": "Permission Denied", "description": "The user does not have permission to access this capability.", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found for the given DID or capability ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "capability_not_found": { "summary": "Capability Not Found", "description": "No capability found for the given DID.", "value": { "type": "/problems/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "No capability matching the provided identifiers was found." } } } } } }, "500": { "description": "Internal server error due to an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_error": { "summary": "Internal Error", "description": "An unexpected error occurred on the server.", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/capabilities/recommendations/:did": { "get": { "summary": "Retrieve skill growth recommendations", "description": "Unlock the potential of your digital identity by exploring tailored skill pathways. This endpoint guides you through suggested capabilities based on your current skill set, helping you navigate the ever-evolving landscape of human and AI symbiosis.", "operationId": "getCapabilitiesRecommendations", "tags": [ "Capabilities", "Recommendations" ], "x-code-hash": "b5f2ba0aa57b4215", "x-generated-at": "2026-04-27T17:06:40.060Z", "responses": { "200": { "description": "Successfully retrieved capability recommendations", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "Decentralized identifier for which recommendations are made" }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "Unique identifier of the capability" }, "capability_name": { "type": "string", "description": "Human-readable name of the capability" }, "confidence": { "type": "number", "description": "Confidence level in the recommendation" } }, "required": [ "capability_id", "capability_name", "confidence" ] } } }, "required": [ "did", "recommendations" ] }, "examples": { "acme_corp's_employee_recommendation": { "summary": "Acme Corp's Employee Recommendation", "description": "Acme Corp employee with DID 'did:human:1234' receives skill recommendations to enhance their digital toolkit.", "value": { "did": "did:human:1234", "recommendations": [ { "capability_id": "cap-001", "capability_name": "Data Analysis", "confidence": 0.85 }, { "capability_id": "cap-002", "capability_name": "Machine Learning", "confidence": 0.8 } ] } } } } } }, "400": { "description": "Invalid request due to malformed DID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_did_example": { "summary": "Invalid DID Example", "description": "The request failed because the DID was improperly formatted, showing how to correct the input.", "value": { "type": "https://humanprotocol.org/errors/invalid-parameter", "title": "Invalid Parameter", "status": 400, "detail": "Invalid DID parameter", "errors": [ { "field": "did", "code": "INVALID_VALUE", "message": "Invalid DID parameter" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization_header": { "summary": "Missing Authorization Header", "description": "The request is unauthorized due to the absence of a valid authorization header.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization header is missing or invalid" } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions_example": { "summary": "Insufficient Permissions Example", "description": "The request is forbidden because the user lacks the necessary permissions to access this resource.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these recommendations" } } } } } }, "404": { "description": "Resource not found for the given DID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "did_not_found_example": { "summary": "DID Not Found Example", "description": "The specified DID does not correspond to any known user, illustrating a 404 error.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "No recommendations found for the provided DID" } } } } } }, "500": { "description": "Internal server error occurred while processing the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An unexpected error occurred on the server, preventing the request from being completed.", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An internal error occurred while retrieving recommendations" } } } } } } } } }, "/v1/capabilities/profiles/:did": { "get": { "summary": "Retrieve active capabilities for a Passport DID", "description": "Uncover the skills and capabilities associated with a given Passport's DID. This endpoint helps you understand the active capabilities granted to an AI or human agent, providing insight into their skillset within the HUMAN platform.", "operationId": "getCapabilitiesProfileByDid", "tags": [ "Capabilities", "Passport" ], "x-code-hash": "db1f551b4aa86668", "x-generated-at": "2026-04-27T17:07:02.899Z", "responses": { "200": { "description": "Returns a list of active capabilities for the specified Passport DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "The unique decentralized identifier for the Passport." }, "grant_count": { "type": "integer", "description": "The number of active capabilities granted to the Passport." }, "grants": { "type": "array", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "The unique identifier of the capability." }, "confidence": { "type": [ "number", "null" ], "description": "The confidence level of the capability, if available." }, "granted_at": { "type": "string", "format": "date-time", "description": "The timestamp when the capability was granted." }, "status": { "type": "string", "description": "The current status of the capability." }, "capability": { "type": "object", "properties": { "canonical_name": { "type": "string", "description": "The canonical name of the capability." }, "domain": { "type": [ "string", "null" ], "description": "The domain related to this capability, if applicable." }, "category": { "type": "string", "description": "The category under which this capability falls." } } } } } } } }, "examples": { "successful_retrieval_of_capabilities": { "summary": "Successful Retrieval of Capabilities", "description": "An example showing the retrieval of active capabilities for a given DID.", "value": { "passport_did": "did:human:1234abcd", "grant_count": 2, "grants": [ { "capability_id": "cap:invoice-processing", "confidence": 0.95, "granted_at": "2023-11-01T12:00:00Z", "status": "active", "capability": { "canonical_name": "Invoice Processing", "domain": "finance", "category": "processing" } }, { "capability_id": "cap:data-analysis", "confidence": null, "granted_at": "2023-10-15T08:30:00Z", "status": "active", "capability": { "canonical_name": "Data Analysis", "domain": "analytics", "category": "research" } } ] } } } } } }, "400": { "description": "Invalid request due to malformed DID parameter.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_did": { "summary": "Invalid DID", "description": "Example where the DID is invalid due to being too short.", "value": { "type": "https://example.com/probs/invalid-did", "title": "Invalid Request Parameter", "status": 400, "detail": "The DID parameter is invalid; it must be a non-empty string.", "errors": [ { "field": "did", "code": "INVALID_VALUE", "message": "Invalid DID parameter", "expected": "non-empty string", "received": "" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing Credentials", "description": "Example where the request is missing authorization credentials.", "value": { "type": "https://example.com/probs/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization credentials are missing or invalid. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Example where the user does not have permission to access the requested resource.", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource. Please contact your administrator." } } } } } }, "404": { "description": "The specified Passport DID was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "did_not_found": { "summary": "DID Not Found", "description": "Example where the specified DID does not exist in the system.", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified Passport DID could not be found. Please verify the DID and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "Example showing a generic server error.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later. Incident ID: inc_1698765432" } } } } } } } } }, "/v1/capabilities/query": { "post": { "summary": "Query capabilities with complex filters", "description": "This endpoint empowers users to query the HUMAN Capability Graph using intricate filters, enabling the discovery of skill sets that match specific criteria. It provides flexibility for large filter sets, ensuring precision and depth in capability matching.", "operationId": "queryCapabilitiesWithFilters", "tags": [ "Capabilities", "Search" ], "x-code-hash": "d82638f05fdc3581", "x-generated-at": "2026-04-27T17:07:25.965Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ], "description": "A list of skills or a comma-separated string of skills to filter by." }, "limit": { "type": "integer", "description": "Maximum number of results to return." }, "cursor": { "type": "string", "description": "Opaque cursor for paginating results." }, "min_weight": { "type": "number", "description": "Minimum confidence weight for filtering capabilities." }, "domains__in": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ], "description": "A list or comma-separated string of domains to filter within." }, "sort": { "type": "string", "description": "Field(s) to sort results by." }, "experience_years__gte": { "type": "string", "description": "Minimum years of experience for filtering." } }, "required": [ "skills" ] }, "examples": { "query_by_skills_and_domain": { "summary": "Query by skills and domain", "description": "This example queries capabilities by specifying a list of skills and a domain.", "value": { "skills": [ "AI", "machine learning" ], "min_weight": 0.8, "domains__in": "technology", "limit": 10, "sort": "-weight" } } } } } }, "responses": { "200": { "description": "Successfully retrieved capabilities that match the specified filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "passport_did": { "type": "string" }, "capability_id": { "type": "string" }, "confidence": { "type": "number" }, "granted_at": { "type": "string", "format": "date-time" }, "capability": { "type": "object", "properties": { "id": { "type": "string" }, "canonical_name": { "type": "string" }, "domain": { "type": "string" }, "category": { "type": "string" } } } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "string" } }, "sort": { "type": "string" }, "pagination": { "type": "object", "properties": { "mode": { "type": "string" }, "order": { "type": "string" } } } } } } }, "examples": { "successful_capability_query": { "summary": "Successful capability query", "value": { "data": [ { "passport_did": "did:human:12345", "capability_id": "cap-001", "confidence": 0.9, "granted_at": "2023-10-01T12:00:00Z", "capability": { "id": "def-001", "canonical_name": "AI Research", "domain": "technology", "category": "research" } } ], "has_more": false, "next_cursor": null, "meta": { "skills": [ "AI", "machine learning" ], "sort": "-weight", "pagination": { "mode": "keyset", "order": "confidence_desc,granted_at_desc,passport_did_desc,capability_id_desc" } } } } } } } }, "400": { "description": "Invalid request due to missing or incorrect fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_skills_field": { "summary": "Missing skills field", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request body has missing or invalid fields.", "errors": [ { "field": "skills", "code": "REQUIRED_FIELD_MISSING", "message": "skills array or comma-separated string is required", "expected": "string[] or string", "received": "null" } ] } } } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized access", "value": { "type": "https://example.com/probs/authentication-required", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "The user does not have the necessary permissions for the resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The specified resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capability-graph/analysts": { "get": { "summary": "Retrieve Capability Graph Analysts", "description": "Dive into the realm of HUMAN's Capability Graph and discover the analysts who orchestrate skills with unmatched precision. This endpoint illuminates the human talents that partner with AI to seamlessly integrate capabilities across the platform, ensuring tasks are expertly routed and executed.", "operationId": "getCapabilityGraphAnalysts", "tags": [ "CapabilityGraph", "Analysts" ], "x-code-hash": "4483cc926ada963e", "x-generated-at": "2026-04-27T17:07:41.232Z", "responses": { "200": { "description": "A list of analysts within the Capability Graph.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "analystId": { "type": "string", "description": "The unique identifier for the analyst." }, "name": { "type": "string", "description": "Full name of the analyst." }, "skills": { "type": "array", "items": { "type": "string" }, "description": "List of skills associated with the analyst." }, "orgId": { "type": "string", "description": "The organization ID the analyst belongs to." } }, "required": [ "analystId", "name", "skills", "orgId" ] } }, "examples": { "default": { "summary": "Example", "value": [ { "analystId": "analyst-123", "name": "Jane Doe", "skills": [ "data analysis", "machine learning" ], "orgId": "acme-001" }, { "analystId": "analyst-456", "name": "John Smith", "skills": [ "project management", "AI orchestration" ], "orgId": "acme-002" } ] } } } } }, "400": { "description": "Bad Request - Invalid parameters supplied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanapi.example.com/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The provided query parameters are not valid. Please check the parameter names and values." } } } } } }, "401": { "description": "Unauthorized - Authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanapi.example.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required. Please provide a valid Passport token." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanapi.example.com/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource." } } } } } }, "404": { "description": "Not Found - Resource does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanapi.example.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found on the server." } } } } } }, "500": { "description": "Internal Server Error - Contact support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanapi.example.com/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please contact support for assistance." } } } } } } } } }, "/v1/capability-graph/evidence/cross-border": { "post": { "summary": "Submit cross-border capability evidence", "description": "In the interconnected world of HUMAN, demonstrating skills across borders is crucial. This endpoint allows agents to submit evidence of their capabilities, verified internationally, to enhance their global reputation and unlock new opportunities. It's about breaking barriers and building a universal profile.", "operationId": "postCrossBorderEvidence", "tags": [ "Capabilities", "Global" ], "x-code-hash": "3a5d3db51d803af4", "x-generated-at": "2026-04-27T17:07:56.660Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Unique identifier for the agent submitting evidence" }, "evidenceType": { "type": "string", "description": "Type of evidence being submitted", "enum": [ "certification", "work-sample", "testimonial" ] }, "evidenceData": { "type": "object", "description": "Detailed data of the evidence", "properties": { "document": { "type": "string", "format": "uri", "description": "URI to the document verifying the capability" }, "description": { "type": "string", "description": "Brief description of the evidence and its significance" } }, "required": [ "document", "description" ] } }, "required": [ "agentId", "evidenceType", "evidenceData" ] }, "examples": { "certification_evidence": { "summary": "Certification Evidence", "description": "An agent submits a certification as evidence", "value": { "agentId": "agent-12345", "evidenceType": "certification", "evidenceData": { "document": "https://evidence-storage.org/docs/agent-12345-cert.pdf", "description": "ISO 9001:2015 certification for quality management systems." } } } } } } }, "responses": { "200": { "description": "Evidence successfully submitted and verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates successful processing of evidence" }, "message": { "type": "string", "description": "Confirmation message with details" } }, "required": [ "success", "message" ] }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request format or missing data", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request payload is malformed or missing required fields.", "errors": [ "The 'agentId' field is required." ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/authentication-error", "title": "Unauthorized", "status": 401, "detail": "You must authenticate yourself to submit evidence." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to submit evidence for this agent." } } } } } }, "404": { "description": "Agent not found in the system", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The specified agent ID does not exist." } } } } } }, "500": { "description": "Internal server error during evidence submission", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/capability-graph/grant": { "post": { "summary": "Grant Capability to an Identity", "description": "This endpoint empowers identities by granting them specific capabilities, enhancing their skill set within the HUMAN ecosystem. By allowing tailored access, it enables efficient task orchestration and fine-grained control over what each identity can accomplish.", "operationId": "postCapabilityGrant", "tags": [ "Capability", "Graph" ], "x-code-hash": "9c2ab47f213324b5", "x-generated-at": "2026-04-27T17:08:09.584Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identityDid": { "type": "string", "description": "Decentralized Identifier of the identity receiving the capability." }, "capabilityUri": { "type": "string", "format": "uri", "description": "The URI of the capability being granted." }, "issuerDid": { "type": "string", "description": "Decentralized Identifier of the issuer granting the capability." } }, "required": [ "identityDid", "capabilityUri", "issuerDid" ] }, "examples": { "grant_capability_to_agent": { "summary": "Grant capability to agent", "description": "Grant the 'invoice.processing' capability to an identity.", "value": { "identityDid": "did:human:acme-agent-123", "capabilityUri": "capability://acme/invoice.processing", "issuerDid": "did:human:acme-org-issuer" } } } } } }, "responses": { "200": { "description": "Capability successfully granted to the identity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message of the successful grant." }, "grantId": { "type": "string", "description": "Unique identifier of the capability grant operation." } } }, "examples": { "default": { "summary": "Example", "value": { "message": "Capability 'invoice.processing' granted to did:human:acme-agent-123.", "grantId": "grant-xyz-789" } } } } } }, "400": { "description": "The request was invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The 'capabilityUri' is missing or malformed." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/auth-required", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "Permission denied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/permission-denied", "title": "Forbidden", "status": 403, "detail": "The issuer DID does not have permission to grant this capability." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified identity DID does not exist." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capability-graph/:grantId": { "delete": { "summary": "Remove a Capability Grant by ID", "description": "This endpoint allows you to delete a specific capability grant from the Capability Graph, effectively revoking a granted skill or permission. It's like removing a key from a keyring, ensuring that access is only available to those who truly need it, enhancing security and clarity in your orchestrated operations.", "operationId": "handleDeleteCapabilityGrant", "tags": [ "Capability Graph", "Access Management" ], "x-code-hash": "839902b4f335b35e", "x-generated-at": "2026-04-27T17:08:21.870Z", "responses": { "200": { "description": "Capability grant successfully removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Capability grant successfully deleted." } } }, "examples": { "successful_deletion": { "summary": "Successful Deletion", "description": "Indicates successful removal of the capability grant.", "value": { "message": "Capability grant successfully deleted." } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_grant_id": { "summary": "Invalid Grant ID", "description": "Occurs when the provided grantId is not a valid UUID.", "value": { "type": "/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The grantId parameter must be a valid UUID." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing Credentials", "description": "Occurs when the request lacks valid authentication credentials.", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication is required and has failed or has not yet been provided." } } } } } }, "403": { "description": "Forbidden operation due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "Occurs when the user tries to delete a grant they don't have rights to.", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to delete this capability grant." } } } } } }, "404": { "description": "The specified capability grant could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "grant_not_found": { "summary": "Grant Not Found", "description": "Occurs when the grantId does not correspond to any existing grant.", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The capability grant with the specified ID does not exist." } } } } } }, "500": { "description": "Internal Server Error indicating a failure within the service.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "Occurs when the server encounters an unexpected condition.", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capability-graph/verify": { "post": { "summary": "Verify capabilities within the graph", "description": "In the realm of human-AI collaboration, knowing who can do what is crucial. This endpoint verifies whether a specific capability exists within an agent's graph, ensuring tasks are routed to the right human or AI. By validating capabilities, we maintain trust and accuracy in AI-driven workflows.", "operationId": "handlePostCapabilityVerify", "tags": [ "Capabilities", "Verification" ], "x-code-hash": "eb46804666a2736d", "x-generated-at": "2026-04-27T17:08:35.534Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "The unique identifier for the agent whose capabilities are being verified." }, "capabilityId": { "type": "string", "description": "The unique identifier of the capability to be verified." } }, "required": [ "agentId", "capabilityId" ] }, "examples": { "verify_capability_for_data_processing": { "summary": "Verify Capability for Data Processing", "description": "This example checks if the 'data-processing' capability exists for agent 'agent-123'.", "value": { "agentId": "agent-123", "capabilityId": "data-processing" } } } } } }, "responses": { "200": { "description": "The capability has been successfully verified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "Indicates if the capability is verified." }, "message": { "type": "string", "description": "A message providing additional context about the verification result." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request - The request is malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The capability ID is missing or invalid." } } } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must be authenticated to verify capabilities." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to verify this capability." } } } } } }, "404": { "description": "Not Found - The specified capability or agent could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/not-found", "title": "Not Found", "status": 404, "detail": "The agent ID or capability ID does not exist." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/capability-graph/:passportId/:capabilityId/explain": { "get": { "summary": "Retrieve Capability Explanation", "description": "This endpoint unveils the hidden potential within a specific capability by providing a detailed explanation. It's the key to understanding how a capability ties into an individual's skill set, enabling more strategic task routing and efficient skill utilization within the HUMAN platform.", "operationId": "getCapabilityExplain", "tags": [ "CapabilityGraph", "HumanAIOrchestration" ], "x-code-hash": "4d6045a33974b691", "x-generated-at": "2026-04-27T17:08:49.029Z", "responses": { "200": { "description": "Successfully retrieved the explanation for the specified capability.", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilityId": { "type": "string", "description": "The unique identifier of the capability." }, "explanation": { "$ref": "#/components/schemas/LearningExplainMetadata" }, "linkedSkills": { "type": "array", "items": { "type": "string" }, "description": "List of skills linked to the capability." } }, "required": [ "capabilityId", "explanation" ] }, "examples": { "basic_capability_explanation": { "summary": "Basic Capability Explanation", "description": "An explanation for the capability associated with a specific Passport.", "value": { "capabilityId": "capability://12345", "explanation": { "details": "This capability enhances data processing efficiency.", "origin": "Derived from prior tasks involving data categorization." }, "linkedSkills": [ "data-analysis", "task-management" ] } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_capability_id_format": { "summary": "Invalid Capability ID Format", "value": { "type": "https://example.com/probs/invalid-format", "title": "Invalid Capability ID", "status": 400, "detail": "The capability ID provided is not in the correct format. Ensure it follows the pattern 'capability://'." } } } } } }, "401": { "description": "Authentication failure due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://example.com/probs/auth-failure", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were not provided or are invalid. Please provide valid credentials to access this endpoint." } } } } } }, "403": { "description": "Access denied due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://example.com/probs/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this capability explanation. Please contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "The specified capability or passport was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "capability_not_found": { "summary": "Capability Not Found", "value": { "type": "https://example.com/probs/not-found", "title": "Not Found", "status": 404, "detail": "The capability or passport ID specified does not exist. Verify the IDs and try again." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://example.com/probs/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/capability-graph/:passportId": { "get": { "summary": "Retrieve Capability Graph for a Passport", "description": "Explore the vast landscape of skills associated with a given Passport ID within the HUMAN ecosystem. This endpoint unveils the intricate web of capabilities that an identity can wield, offering insights into their potential interactions within the network.", "operationId": "handleGetCapabilityGraph", "tags": [ "Capabilities", "Identity" ], "x-code-hash": "569f05b37fd08926", "x-generated-at": "2026-04-27T17:09:12.973Z", "responses": { "200": { "description": "Successfully retrieved the capability graph for the specified Passport ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passportId": { "type": "string", "description": "The unique identifier for the Passport." }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the capability." }, "name": { "type": "string", "description": "The name of the capability." }, "description": { "type": "string", "description": "A brief description of what the capability allows." }, "level": { "type": "integer", "description": "The proficiency level of the capability." } }, "required": [ "id", "name", "description", "level" ] } } }, "required": [ "passportId", "capabilities" ] }, "examples": { "capability_graph_example": { "summary": "Capability Graph Example", "description": "An example response showing the capabilities of a Passport ID.", "value": { "passportId": "passport-12345", "capabilities": [ { "id": "capability-6789", "name": "Data Analysis", "description": "Ability to analyze and interpret complex datasets.", "level": 3 }, { "id": "capability-9876", "name": "Project Management", "description": "Skills in leading and managing projects to completion.", "level": 4 } ] } } } } } }, "400": { "description": "Malformed request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_parameter_example": { "summary": "Invalid Parameter Example", "description": "Example of a response when the Passport ID is malformed.", "value": { "type": "https://humanprotocol.org/errors/invalid-parameters", "title": "Invalid Request Parameters", "status": 400, "detail": "The Passport ID provided does not conform to expected format. Please ensure the ID is correct and try again." } } } } } }, "401": { "description": "Unauthorized request due to invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "Example of a response when access is denied due to invalid credentials.", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Access denied. Please check your credentials and ensure you have the correct permissions to access this resource." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Example of a response when the user does not have permission to access the resource.", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource. Please contact your administrator if you believe this is an error." } } } } } }, "404": { "description": "Passport not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_not_found_example": { "summary": "Passport Not Found Example", "description": "Example of a response when the Passport ID is not found.", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Passport Not Found", "status": 404, "detail": "The Passport ID you requested does not exist. Please verify the ID and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "Example of a response when an unexpected error occurs.", "value": { "type": "https://humanprotocol.org/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error has occurred on the server. Please try your request again later or contact support if the issue persists." } } } } } } } } }, "/v1/evidence/:id/challenge/resolve": { "post": { "summary": "Resolve evidence challenge outcome", "description": "This endpoint empowers administrators to decisively resolve challenges against evidence entries. By either dismissing or upholding the evidence challenge, it ensures integrity and trust in the Human-AI orchestration process.", "operationId": "resolveEvidenceChallenge", "tags": [ "Evidence", "Challenge Resolution" ], "x-code-hash": "f9441b5a3881ec39", "x-generated-at": "2026-04-27T17:14:25.264Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "dismiss", "uphold" ], "description": "The decision to either 'dismiss' (restore evidence) or 'uphold' (revoke evidence)." } }, "required": [ "decision" ] }, "examples": { "dismiss_example": { "summary": "Dismiss Example", "description": "A decision to dismiss the challenge, restoring the evidence to its verified state.", "value": { "decision": "dismiss" } } } } } }, "responses": { "200": { "description": "The challenge was resolved successfully, with the evidence either restored or revoked based on the decision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_id": { "type": "string", "description": "The unique identifier of the evidence." }, "verification_outcome": { "type": "string", "description": "The outcome of the verification process." }, "decision": { "type": "string", "enum": [ "dismiss", "uphold" ], "description": "The decision made for this challenge resolution." } }, "required": [ "evidence_id", "verification_outcome", "decision" ] }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The request was invalid due to an incorrect decision value.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "404": { "description": "The specified evidence could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "409": { "description": "The evidence is not currently in a state that can be resolved.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example" } } } } } } } }, "/v1/companion/chat": { "post": { "summary": "Initiate a companion chat session", "description": "Engage with the HUMAN platform's companion AI to facilitate seamless conversations. This endpoint is an essential part of creating interactive experiences where AI assists human users by understanding context and responding in real-time. It ensures the AI is informed by past interactions and current context, making it a valuable tool for dynamic user engagement.", "operationId": "initiateCompanionChat", "tags": [ "Communication", "AI" ], "x-code-hash": "2a32b86ce8708b11", "x-generated-at": "2026-04-30T23:11:00.797Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The message to send to the companion AI." }, "session_id": { "type": "string", "description": "An optional identifier for the chat session to maintain context." }, "history": { "type": "array", "items": { "type": "string" }, "description": "Optional array of previous messages for context continuity." }, "context": { "type": "object", "description": "Additional contextual information to enhance AI understanding." } }, "required": [ "message" ] }, "examples": { "starting_a_chat_with_context": { "summary": "Starting a chat with context", "description": "Use this example to initiate a chat while passing previous conversation history and session ID.", "value": { "message": "How do I process invoices?", "session_id": "session-abc123", "history": [ "What is the status of my last invoice?", "You can review it in the dashboard." ], "context": { "department": "finance" } } } } } } }, "responses": { "200": { "description": "Companion chat successfully initiated and returns the AI's response or event stream.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "description": "Identifier for the ongoing task." }, "trace_id": { "type": "string", "description": "Trace identifier for debugging and tracking." }, "result": { "type": "object", "properties": { "text": { "type": "string", "description": "AI's textual response." }, "content": { "type": "string", "description": "Additional content from AI." }, "structured": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "data": { "type": "object" } } } } } } } }, "examples": { "ai_response_example": { "summary": "AI response example", "description": "An example response where the AI provides guidance on invoice processing.", "value": { "task_id": "task-xyz456", "trace_id": "trace-789xyz", "result": { "text": "To process invoices, navigate to the billing section.", "content": "Ensure all necessary fields are completed before submission.", "structured": [ { "type": "instruction", "data": { "step": "Open billing dashboard", "action": "Click 'Submit'" } } ] } } } } } } }, "400": { "description": "The request could not be processed due to malformed JSON.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_json_format": { "summary": "Invalid JSON format", "description": "Occurs when the JSON structure is incorrect.", "value": { "type": "https://api.haio.run/errors/invalid-body", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing delegation token", "description": "Occurs when the required delegation token is not provided.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required.", "errors": [] } } } } } }, "403": { "description": "Forbidden access when the user lacks necessary permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden access", "description": "The user does not have permission to access this endpoint.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource.", "errors": [] } } } } } }, "404": { "description": "Resource not found, indicating an incorrect endpoint or resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource not found", "description": "The endpoint or resource could not be located.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found on this server.", "errors": [] } } } } } }, "500": { "description": "Internal server error indicating an unexpected condition.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "A general error occurred on the server.", "value": { "type": "https://api.haio.run/errors/internal-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later.", "errors": [] } } } } } } } } }, "/v1/companion/kb/search": { "get": { "summary": "Delegation-scoped KB search with access control", "description": "Embark on a quest through the HUMAN knowledge base, where access is determined by the cryptographic credentials you hold. This endpoint allows users to conduct a full-text search, unveiling documents their delegation token permits, ensuring both security and precision in knowledge retrieval.", "operationId": "getCompanionKbSearch", "tags": [ "KnowledgeBase", "Search" ], "x-code-hash": "54cb7089fc5330e6", "x-generated-at": "2026-04-28T20:02:36.628Z", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query string matched against KB document titles, summaries, and content.", "schema": { "type": "string", "minLength": 1 }, "example": "capability graph design" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return. Capped at 50 regardless of the value supplied.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "example": 20 }, { "name": "classification", "in": "query", "required": false, "description": "Override the access ceiling for ExternalPartner-scoped tokens. Tokens that already hold kb:read:internal scope receive Internal access and this parameter is ignored.", "schema": { "type": "string", "enum": [ "ExternalPartner", "Public" ] } } ], "responses": { "200": { "description": "Successful search returns relevant documents within access scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "path": { "type": "string" }, "classification": { "type": "string" }, "governanceTier": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "snippet": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer" }, "query": { "type": "string" }, "classification_ceiling": { "type": "string" } } }, "examples": { "successful_search_for_public_documents": { "summary": "Successful Search for Public Documents", "value": { "results": [ { "id": "doc123", "title": "AI Ethics Guidelines", "path": "/docs/ai-ethics", "classification": "Public", "governanceTier": "General", "summary": "Guidelines on ethical AI development.", "snippet": "This document outlines the principles of ethical AI..." } ], "total": 1, "query": "AI ethics", "classification_ceiling": "Public" } } } } } }, "400": { "description": "Invalid request due to missing query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_query_parameter": { "summary": "Missing Query Parameter", "value": { "type": "https://api.haio.run/errors/validation", "title": "Invalid Request", "status": 400, "detail": "The query parameter 'q' is required.", "errors": [ { "field": "q", "code": "REQUIRED_FIELD_MISSING", "message": "q (query string) is required.", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_request": { "summary": "Unauthorized Request", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with kb:read:public scope is required." } } } } } }, "500": { "description": "Internal server error during search operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_during_search": { "summary": "Server Error During Search", "value": { "type": "https://api.haio.run/errors/internal", "title": "KB Search Error", "status": 500, "detail": "An unexpected error occurred while searching the knowledge base." } } } } } } } } }, "/v1/mcp-sessions": { "get": { "summary": "Retrieve active MCP sessions", "description": "Discover the active and valid sessions for your cryptographic identity with this endpoint. It's designed to empower organizations, like Acme Corp, by listing ongoing sessions securely linked to a Passport, ensuring transparency and control over session activity.", "operationId": "getMcpSessions", "tags": [ "Sessions", "Identity" ], "x-code-hash": "59c44766581bf68a", "x-generated-at": "2026-04-30T22:45:43.362Z", "responses": { "200": { "description": "A list of active sessions for the authenticated Passport", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique session identifier" }, "passport_id": { "type": "string", "description": "Passport ID associated with the session" }, "org_did": { "type": "string", "description": "Organization DID" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted to this session" }, "client_name": { "type": "string", "description": "Name of the client application" }, "plan_tier": { "type": "string", "description": "Subscription tier of the client" }, "created_at": { "type": "string", "format": "date-time", "description": "Session creation timestamp" }, "last_used_at": { "type": "string", "format": "date-time", "description": "Last usage timestamp" }, "expires_at": { "type": "string", "format": "date-time", "description": "Session expiration timestamp" } } } }, "has_more": { "type": "boolean", "description": "Indicates if more sessions are available" }, "next_cursor": { "type": "string", "description": "Cursor for fetching the next page of sessions" } } }, "examples": { "successful_session_retrieval": { "summary": "Successful session retrieval", "description": "An example response showing active sessions for a Passport.", "value": { "sessions": [ { "id": "session123", "passport_id": "passport456", "org_did": "did:example:acme", "scopes": [ "read", "write" ], "client_name": "AcmeClientApp", "plan_tier": "premium", "created_at": "2023-10-01T12:00:00Z", "last_used_at": "2023-10-10T12:00:00Z", "expires_at": "2023-11-01T12:00:00Z" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Invalid request due to malformed cursor", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_cursor_error": { "summary": "Malformed Cursor Error", "description": "Occurs when the cursor parameter is improperly formatted.", "value": { "type": "https://api.haio.run/errors/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The cursor value is malformed or expired. Omit the cursor to restart from the beginning." } } } } } }, "401": { "description": "Unauthorized access due to missing delegation token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_error": { "summary": "Unauthorized Access Error", "description": "Triggered when the request lacks a valid delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation token required to list MCP sessions." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_error": { "summary": "Forbidden Access Error", "description": "Occurs when the user does not have the necessary permissions.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these sessions." } } } } } }, "404": { "description": "Sessions not found for the given Passport", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "sessions_not_found_error": { "summary": "Sessions Not Found Error", "description": "Triggered when no sessions are found for the requested Passport ID.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No active sessions found for the provided Passport ID." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "Occurs when the server encounters an unexpected condition.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/mcp-sessions/register": { "post": { "summary": "Register or update MCP session details", "description": "This endpoint allows internal components of the HUMAN platform to register or update sessions for multi-capability processing (MCP). By managing session lifecycles, it ensures seamless orchestration of tasks across human and AI agents under secure conditions.", "operationId": "registerMcpSession", "tags": [ "Sessions", "Security" ], "x-code-hash": "4a01381ffc6d51a2", "x-generated-at": "2026-04-29T22:10:02.303Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique identifier for the session" }, "passport_id": { "type": "string", "description": "Cryptographic identity of the agent" }, "org_did": { "type": "string", "description": "Decentralized identifier for the organization" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "List of permissions granted to the session" }, "client_name": { "type": "string", "description": "Name of the client creating the session" }, "plan_tier": { "type": [ "string", "null" ], "description": "Service plan tier (if applicable)" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration timestamp for the session" } }, "required": [ "session_id", "passport_id", "org_did", "expires_at" ] }, "examples": { "standard_registration": { "summary": "Standard Registration", "description": "Registers a session for the 'acme' organization with specific scopes and a premium plan tier.", "value": { "session_id": "session_12345", "passport_id": "passport_abcde", "org_did": "did:humanos:acme", "scopes": [ "read", "write" ], "client_name": "Acme Client", "plan_tier": "premium", "expires_at": "2023-12-31T23:59:59Z" } } } } } }, "responses": { "200": { "description": "The session has been successfully registered or updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "examples": { "default": { "summary": "Example", "value": { "ok": true } } } } } }, "400": { "description": "Invalid input JSON provided. Ensure the request body is correct and all required fields are present.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/invalid-body", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "session_id", "code": "REQUIRED_FIELD_MISSING", "message": "session_id is required.", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access without a valid token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "You must provide a valid authorization token." } } } } } }, "403": { "description": "Forbidden access due to missing internal API token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Internal API token required." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The session you are looking for does not exist." } } } } } }, "500": { "description": "An internal server error occurred. Please try again later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/mcp-sessions/:id": { "delete": { "summary": "Revoke an MCP session by ID", "description": "In the ever-evolving landscape of AI-driven tasks, sessions are the lifeline of task processing. This endpoint allows authorized users to revoke a session, ensuring that outdated or unauthorized sessions don't linger, maintaining the integrity and security of our Human-AI orchestration.", "operationId": "revokeMcpSession", "tags": [ "Session Management", "Security" ], "x-code-hash": "c8be7d772f40e240", "x-generated-at": "2026-04-29T22:10:15.173Z", "responses": { "204": { "description": "The session was successfully revoked, ensuring no further tasks are processed under this session.", "content": { "application/json": { "schema": { "type": "null" } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_credentials": { "summary": "Missing Credentials", "description": "Attempting to revoke a session without proper credentials.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation token or internal token required." } } } } } }, "404": { "description": "The session ID you are trying to revoke does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "non-existent_session_id": { "summary": "Non-existent Session ID", "description": "Trying to revoke a session with an ID that doesn't exist.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No session found with ID '12345'." } } } } } }, "500": { "description": "An unexpected error occurred during the revocation process.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "A system-level issue preventing session revocation.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/kb/get": { "get": { "summary": "Retrieve Knowledge Base Document by ID", "description": "Dive into the rich tapestry of knowledge stored within the HUMAN platform. This endpoint allows you to fetch a specific Knowledge Base document, unlocking the power of collective insights. Whether you're an AI seeking guidance or a human exploring new realms, retrieving this document can be your compass.", "operationId": "getKbDocumentById", "tags": [ "KnowledgeBase", "DocumentRetrieval" ], "x-code-hash": "d6495c440e511637", "x-generated-at": "2026-04-29T22:10:42.259Z", "responses": { "200": { "description": "Successfully retrieved the Knowledge Base document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the document" }, "title": { "type": "string", "description": "Title of the document" }, "path": { "type": "string", "description": "Path to the document in the KB" }, "classification": { "type": "string", "description": "Document classification level" }, "governance_tier": { "type": "string", "description": "Governance tier of the document" }, "summary": { "type": [ "string", "null" ], "description": "Brief summary of the document" }, "content": { "type": "string", "description": "Full content of the document" }, "last_updated": { "type": [ "string", "null" ], "description": "Timestamp of the last update" } }, "required": [ "id", "title", "path", "classification", "content" ] }, "examples": { "retrieve_kb_document": { "summary": "Retrieve KB Document", "description": "The document about AI safety protocols.", "value": { "id": "kb-123", "title": "Understanding AI Safety", "path": "/docs/ai-safety", "classification": "Public", "governance_tier": "Tier 1", "summary": "An overview of protocols ensuring safe AI deployment.", "content": "The content delves into various AI safety protocols...", "last_updated": "2023-10-12T14:22:00Z" } } } } } }, "400": { "description": "Malformed request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_id_error": { "summary": "Missing ID Error", "description": "The request was missing the required 'id' parameter.", "value": { "type": "https://api.haio.run/errors/validation", "title": "Validation Error", "status": 400, "detail": "Request validation failed.", "errors": [ { "field": "id", "code": "REQUIRED_FIELD_MISSING", "message": "id (KB doc id) is required.", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_token_error": { "summary": "Missing Token Error", "description": "The request did not include a valid delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with kb:read:public scope is required." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "permission_denied_error": { "summary": "Permission Denied Error", "description": "The user does not have the necessary permissions to access the document.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this document." } } } } } }, "404": { "description": "Document not found with the provided ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "document_not_found_error": { "summary": "Document Not Found Error", "description": "The specified document ID does not correspond to any existing document.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The KB document with the specified ID does not exist." } } } } } }, "500": { "description": "An unexpected error occurred while attempting to fetch the document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "An error occurred within the server while processing the request.", "value": { "type": "https://api.haio.run/errors/internal", "title": "KB Fetch Error", "status": 500, "detail": "An unexpected error occurred while fetching the KB document." } } } } } } } } }, "/v1/companion/kb/list": { "get": { "summary": "Retrieve accessible knowledge base documents", "description": "Unleash the full potential of your organization's knowledge by accessing documents curated to your session's security clearance. This endpoint provides a tailored list of knowledge base entries, ensuring that every piece of information you view aligns with your classification tier, be it public or internal. Harnessing the HUMAN protocol, it empowers MCP resource listings with precision and safety.", "operationId": "getCompanionKbList", "tags": [ "KnowledgeBase", "AccessControl" ], "x-code-hash": "068bda9ca6da9beb", "x-generated-at": "2026-04-29T22:10:51.304Z", "responses": { "200": { "description": "Successfully retrieved the list of accessible knowledge base documents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the document" }, "title": { "type": "string", "description": "Title of the document" }, "path": { "type": "string", "description": "Path to the document" }, "classification": { "type": "string", "description": "Classification level of the document" }, "summary": { "type": [ "string", "null" ], "description": "Brief summary of the document" } }, "required": [ "id", "title", "path", "classification" ] } }, "total": { "type": "integer", "description": "Total number of documents retrieved" }, "classification_ceiling": { "type": "string", "description": "Maximum classification level accessible" } }, "required": [ "items", "total", "classification_ceiling" ] }, "examples": { "acme_internal_documents": { "summary": "Acme Internal Documents", "description": "Shows retrieval of internal documents for Acme Corp.", "value": { "items": [ { "id": "doc-123", "title": "Acme Financial Report 2022", "path": "/acme/reports/financial-2022.pdf", "classification": "Internal", "summary": "An overview of Acme Corp's financial performance in 2022." }, { "id": "doc-456", "title": "Acme Employee Handbook", "path": "/acme/resources/handbook.pdf", "classification": "Internal", "summary": null } ], "total": 2, "classification_ceiling": "Internal" } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "description": "Error due to missing delegation token in the request.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with kb:read:public scope is required." } } } } } }, "500": { "description": "Internal server error while retrieving knowledge base documents.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "General server error due to unforeseen issues.", "value": { "type": "https://api.haio.run/errors/internal", "title": "KB List Error", "status": 500, "detail": "An unexpected error occurred while processing the knowledge base list." } } } } } } } } }, "/v1/openapi/schemas": { "get": { "summary": "Retrieve all available schemas list", "description": "Dive into the intricacies of schema orchestration with this endpoint, which unveils a comprehensive list of schemas available within the HUMAN platform. Explore the structural backbone that powers the seamless Human-AI collaboration, providing you the keys to unlock deeper integrations.", "operationId": "getOpenApiSchemas", "tags": [ "Schemas", "Integration" ], "x-code-hash": "ea52f71cc504dbbe", "x-generated-at": "2026-04-29T22:11:05.830Z", "responses": { "200": { "description": "Successfully retrieved a sorted list of available schemas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the schema." } }, "required": [ "name" ] } }, "total": { "type": "integer", "description": "The total number of schemas available." } }, "required": [ "items", "total" ] }, "examples": { "retrieveschemasexample": { "summary": "RetrieveSchemasExample", "description": "An example response showing the list of schema names available on the platform.", "value": { "items": [ { "name": "CapabilityGraphSchema" }, { "name": "HumanOSSchema" }, { "name": "PassportSchema" } ], "total": 3 } } } } } }, "400": { "description": "Bad request due to malformed syntax or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "badrequestexample": { "summary": "BadRequestExample", "description": "An example response for a malformed request.", "value": { "type": "https://api.haio.run/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The request could not be understood by the server due to malformed syntax." } } } } } }, "401": { "description": "Authorization required to access schemas.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorizedexample": { "summary": "UnauthorizedExample", "description": "An example response for a request made without a valid delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token is required to read schemas." } } } } } }, "403": { "description": "Access to the resource is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbiddenexample": { "summary": "ForbiddenExample", "description": "An example response when the user does not have permission to access the schemas.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "notfoundexample": { "summary": "NotFoundExample", "description": "An example response for a request to a non-existent endpoint.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "servererrorexample": { "summary": "ServerErrorExample", "description": "An example response when the server encounters an unexpected condition.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } } }, "/v1/openapi/schemas/:name": { "get": { "summary": "Retrieve a Schema by Name", "description": "Uncover the intricacies of your data structures by retrieving a specific schema by its name. This endpoint empowers you to understand and validate the data models your HUMAN platform relies on, ensuring seamless integration and operation.", "operationId": "getSchemaByName", "tags": [ "Schemas", "Data Models" ], "x-code-hash": "d790ed6d197fe4bb", "x-generated-at": "2026-04-29T22:11:16.982Z", "responses": { "200": { "description": "Successfully retrieves the requested schema with its name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the schema" }, "schema": { "type": "object", "description": "The detailed schema definition" } }, "required": [ "name", "schema" ] }, "examples": { "successful_schema_retrieval": { "summary": "Successful Schema Retrieval", "description": "Acme Corporation retrieves their invoice schema for validation.", "value": { "name": "invoiceSchema", "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "invoiceId", "amount" ] } } } } } } }, "401": { "description": "Unauthorized access due to missing delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "description": "A request without a delegation token is made, resulting in an unauthorized error.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token is required to read schemas." } } } } } }, "404": { "description": "Schema not found for the given name.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "schema_not_found": { "summary": "Schema Not Found", "description": "An attempt to retrieve a non-existent schema results in a not found error.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The schema with the given name does not exist." } } } } } }, "500": { "description": "Internal server error encountered while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "An internal server error occurs, indicating a problem with processing the request.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/passports/principals": { "get": { "summary": "Retrieve Active Principals for Passport", "description": "Uncover the identities your passport can embody, from personal to organizational alignments. This endpoint reveals all active principals linked to the authenticated passport, allowing you to navigate your roles with clarity.", "operationId": "getPrincipalsForPassport", "tags": [ "Passports", "Identity" ], "x-code-hash": "47fd2a34fe03b187", "x-generated-at": "2026-04-29T22:11:32.953Z", "responses": { "200": { "description": "Successfully retrieved all principals the authenticated passport can act as.", "content": { "application/json": { "schema": { "type": "object", "properties": { "principals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Decentralized Identifier (DID) of the principal." }, "kind": { "type": "string", "description": "Type of principal, either 'personal' or 'org'." }, "label": { "type": "string", "description": "Human-readable label for the principal." }, "display_name": { "type": "string", "description": "Display name of the principal, possibly enhanced with context." }, "accent_token": { "type": "string", "description": "Visual accent token for UI differentiation, default for organizations." } }, "required": [ "id", "kind", "label", "display_name" ] } }, "active_principal_id": { "type": "string", "description": "The DID of the principal currently active or 'personal' by default." } }, "required": [ "principals", "active_principal_id" ] }, "examples": { "acme_corp_principal_retrieval": { "summary": "Acme Corp Principal Retrieval", "description": "Retrieve principals for a passport linked to personal identity and Acme Corp.", "value": { "principals": [ { "id": "did:human:passport:123456789abcdef", "kind": "personal", "label": "You personally", "display_name": "John Doe (personal)" }, { "id": "did:org:acmecorp", "kind": "org", "label": "Acme Corporation", "display_name": "Acme Corporation", "accent_token": "hsl(240 80% 60%)" } ], "active_principal_id": "did:human:passport:123456789abcdef" } } } } } }, "400": { "description": "Bad Request due to client error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_request_example": { "summary": "Invalid Request Example", "description": "Illustrates a malformed request.", "value": { "type": "https://example.com/probs/bad-request", "title": "Invalid parameters", "status": 400, "detail": "The request parameters were invalid. Ensure all required parameters are present and correctly formatted." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_example": { "summary": "Unauthorized Example", "description": "Access attempt without valid authentication.", "value": { "type": "https://example.com/probs/auth-required", "title": "Authentication required", "status": 401, "detail": "You must authenticate to access this resource. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_example": { "summary": "Forbidden Example", "description": "Attempt to access a resource without necessary permissions.", "value": { "type": "https://example.com/probs/forbidden", "title": "Access forbidden", "status": 403, "detail": "You do not have permission to access this resource. Verify your access rights." } } } } } }, "404": { "description": "Resource not found, possibly due to an incorrect route or missing entity.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "not_found_example": { "summary": "Not Found Example", "description": "Indicates that the requested resource was not found.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource not found", "status": 404, "detail": "The requested principal was not found. Check the DID and try again." } } } } } }, "500": { "description": "Internal server error due to unforeseen issues.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "A generic server error encounter.", "value": { "type": "https://example.com/probs/server-error", "title": "Internal server error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the problem persists." } } } } } } } } }, "/v1/passports/delegations": { "get": { "summary": "Retrieve delegation grants for a passport", "description": "Explore the cryptographic relationships that bind humans and AI by retrieving delegation grants for your authenticated passport. This endpoint allows you to track the web of trust and capabilities extended and received, helping to ensure that every interaction is secure and verifiable.", "operationId": "getPassportDelegations", "tags": [ "Passports", "Delegations" ], "x-code-hash": "aaf6ff9718ff77dd", "x-generated-at": "2026-04-29T22:11:53.123Z", "responses": { "200": { "description": "A successful retrieval of delegation grants, providing insight into the active, expired, or revoked permissions for the authenticated passport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "delegation_id": { "type": "string" }, "to": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "package": { "type": "string", "nullable": true }, "minted_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "risk_ceiling": { "type": "string" }, "ledger_event_id": { "type": "string", "nullable": true }, "status": { "type": "string" } } } }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "examples": { "active_delegations_for_acme_corp": { "summary": "Active Delegations for Acme Corp", "description": "Retrieve active delegation grants, showcasing the permissions Acme Corp has granted to various agents.", "value": { "data": [ { "delegation_id": "dlg_123456", "to": "Agent Jane Doe", "scopes": [ "read", "write" ], "package": "acme_package", "minted_at": "2023-01-15T08:00:00Z", "expires_at": "2023-12-31T23:59:59Z", "revoked_at": null, "risk_ceiling": "medium", "ledger_event_id": "ledger_67890", "status": "active" } ], "limit": 20, "hasMore": false } } } } } }, "400": { "description": "Bad Request due to invalid query parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized access due to missing or invalid passport authentication.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden access due to lack of required scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found when no delegations exist for the given filters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error due to an unexpected issue on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/companion/preferences": { "get": { "summary": "Retrieve personalized companion preferences", "description": "Unveil a world tailored to your preferences by fetching your companion settings. This endpoint is your gateway to understanding how HUMAN customizes interactions, ensuring a seamless and personal experience orchestrated with AI precision.", "operationId": "getCompanionPreferences", "tags": [ "Companion", "Preferences" ], "x-code-hash": "b3e623ae6049cfae", "x-generated-at": "2026-04-29T22:12:10.230Z", "responses": { "200": { "description": "Successfully retrieved user preferences for the companion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_display_name": { "type": "string", "description": "The display name associated with the user's Passport." }, "avatar_url": { "type": "string", "format": "uri", "description": "The URL to the user's avatar image." }, "email": { "type": "string", "format": "email", "description": "The user's email address." }, "preferred_language": { "type": "string", "description": "The user's preferred language for communications." } }, "required": [ "passport_display_name", "avatar_url", "email", "preferred_language" ] }, "examples": { "acme_corp_user_preferences": { "summary": "Acme Corp User Preferences", "description": "An example of a user's companion preferences within Acme Corp.", "value": { "passport_display_name": "John Doe", "avatar_url": "https://avatars.human.com/johndoe.jpg", "email": "john.doe@acme.com", "preferred_language": "en-US" } } } } } }, "400": { "description": "Bad request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_request_example": { "summary": "Malformed Request Example", "description": "Example response for a malformed request.", "value": { "type": "https://api.haio.run/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The request could not be understood or was missing required parameters.", "errors": [ "Invalid query parameter 'xyz'" ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access_example": { "summary": "Unauthorized Access Example", "description": "Example response when a valid token is not provided.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "Example response for a forbidden access attempt.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Access to this resource is forbidden for your role." } } } } } }, "404": { "description": "Resource not found response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found_example": { "summary": "Resource Not Found Example", "description": "Example response when the requested resource is not found.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested preferences were not found." } } } } } }, "500": { "description": "Internal server error response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error_example": { "summary": "Internal Server Error Example", "description": "Example response for an unexpected server error.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "put": { "summary": "Update Companion Preferences", "description": "Tailor your AI companion to your liking by updating its preferences. This endpoint allows you to set the tone, formality, and other attributes of your companion, ensuring it aligns with your personal or organizational style.", "operationId": "updateCompanionPreferences", "tags": [ "Preferences", "Companion" ], "x-code-hash": "785def0bfd74467d", "x-generated-at": "2026-04-29T22:12:33.627Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": [ "string", "null" ], "description": "Unique identifier for the companion" }, "humor_level": { "type": "string", "enum": [ "none", "low", "medium", "high" ], "description": "Humor intensity" }, "formality": { "type": "string", "enum": [ "informal", "formal" ], "description": "Formality level of interactions" }, "verbosity": { "type": "string", "enum": [ "concise", "detailed" ], "description": "Preferred verbosity of responses" }, "domain_context": { "type": [ "string", "null" ], "description": "Domain-specific context for interactions" }, "custom_instructions": { "type": [ "string", "null" ], "description": "Custom instructions for the companion" }, "starter_mode": { "type": [ "string", "null" ], "enum": [ "beginner", "intermediate", "advanced" ], "description": "Starter mode of the companion" }, "onboarding_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when onboarding started" }, "onboarding_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when onboarding completed" }, "onboarding_steps_completed": { "type": "array", "items": { "type": "string" }, "description": "Steps completed in onboarding" }, "first_artifact_delivered": { "type": [ "string", "null" ], "description": "Timestamp of first artifact delivery" }, "workflow_activations": { "type": "array", "items": { "type": "string" }, "description": "Activated workflows" }, "academy_opens": { "type": "array", "items": { "type": "string" }, "description": "Academy opens" }, "reentry_hint_delivered": { "type": "boolean", "description": "Reentry hint status" } } }, "examples": { "update_humor_and_formality": { "summary": "Update Humor and Formality", "description": "Sets humor to medium and formality to informal for a more casual interaction style.", "value": { "handle": "chatbot123", "humor_level": "medium", "formality": "informal" } } } } } }, "responses": { "200": { "description": "Preferences successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string" }, "humor_level": { "type": "string" }, "formality": { "type": "string" }, "verbosity": { "type": "string" }, "domain_context": { "type": [ "string", "null" ] }, "custom_instructions": { "type": [ "string", "null" ] }, "starter_mode": { "type": [ "string", "null" ] }, "onboarding_started_at": { "type": [ "string", "null" ], "format": "date-time" }, "onboarding_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "onboarding_steps_completed": { "type": "array", "items": { "type": "string" } }, "first_artifact_delivered": { "type": [ "string", "null" ] }, "workflow_activations": { "type": "array", "items": { "type": "string" } }, "academy_opens": { "type": "array", "items": { "type": "string" } }, "reentry_hint_delivered": { "type": "boolean" }, "passport_display_name": { "type": "string" }, "avatar_url": { "type": "string" }, "email": { "type": "string" }, "preferred_language": { "type": "string" } } }, "examples": { "default": { "summary": "Example", "value": { "handle": "chatbot123", "humor_level": "medium", "formality": "informal", "verbosity": "detailed", "domain_context": null, "custom_instructions": null, "starter_mode": "intermediate", "onboarding_started_at": "2023-10-01T12:00:00Z", "onboarding_completed_at": "2023-10-02T12:00:00Z", "onboarding_steps_completed": [ "step1", "step2" ], "first_artifact_delivered": "2023-10-03T12:00:00Z", "workflow_activations": [ "workflow1", "workflow2" ], "academy_opens": [], "reentry_hint_delivered": true, "passport_display_name": "John Doe", "avatar_url": "https://example.com/avatar.jpg", "email": "john.doe@example.com", "preferred_language": "en" } } } } } }, "400": { "description": "Invalid JSON or validation errors", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "Validation failed for one or more fields.", "errors": [ { "field": "humor_level", "code": "INVALID_VALUE", "message": "humor_level must be one of: none, low, medium, high", "expected": "none|low|medium|high", "received": "extreme" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "403": { "description": "Forbidden due to organizational policy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/forbidden-org-policy", "title": "Org policy forbids change", "status": 422, "detail": "Changing humor_level is restricted by your organization.", "field": "humor_level" } } } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested companion was not found." } } } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "summary": "Remove AI Companion Preferences", "description": "Erase your AI Companion's memory to start afresh. This endpoint ensures that explicit preferences, inferred signals, and persistent memories are wiped, giving your AI a clean slate to better serve your evolving needs.", "operationId": "deleteCompanionPreferences", "tags": [ "AI Companion", "User Preferences" ], "x-code-hash": "38c82bf5f6041b12", "x-generated-at": "2026-04-29T22:12:44.087Z", "responses": { "200": { "description": "Successfully cleared all AI Companion preferences and memory.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "cleared": { "type": "object", "properties": { "preferences": { "type": "boolean", "example": true }, "signals": { "type": "integer", "example": 5 }, "inferred_memory": { "type": "integer", "example": 3 } } } } }, "examples": { "default": { "summary": "Example", "value": { "ok": true, "cleared": { "preferences": true, "signals": 5, "inferred_memory": 3 } } } } } } }, "401": { "description": "Authentication failed due to missing or invalid token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "500": { "description": "Internal server error encountered while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while trying to clear preferences." } } } } } } } } }, "/v1/companion/preferences/users/:passportDid": { "delete": { "summary": "Remove user preferences by Passport DID", "description": "This endpoint allows an organization to wipe user preferences using a Passport DID, ensuring compliance with privacy requests or resets. It's a crucial part of maintaining user autonomy and organizational data integrity.", "operationId": "deleteUserPreferencesByPassportDid", "tags": [ "User Management", "Preferences" ], "x-code-hash": "1ba19b9b0645c55f", "x-generated-at": "2026-04-29T22:12:59.977Z", "responses": { "200": { "description": "Successfully removed user preferences and signals", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "target_passport_did": { "type": "string" }, "cleared": { "type": "object", "properties": { "preferences": { "type": "boolean" }, "signals": { "type": "boolean" }, "inferred_memory": { "type": "integer" } } }, "reset_by": { "type": "string" } } }, "examples": { "successful_removal": { "summary": "Successful Removal", "description": "User preferences and signals were successfully cleared for the given Passport DID.", "value": { "ok": true, "target_passport_did": "did:human:123456", "cleared": { "preferences": true, "signals": true, "inferred_memory": 0 }, "reset_by": "did:human:654321" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_passport_did": { "summary": "Missing Passport DID", "description": "The request was missing the required Passport DID parameter.", "value": { "type": "https://api.haio.run/errors/validation", "title": "Validation Error", "status": 400, "detail": "The request is invalid due to missing fields.", "errors": [ { "field": "passportDid", "code": "REQUIRED_FIELD_MISSING", "message": "passportDid is required.", "expected": "string", "received": "undefined" } ] } } } } } }, "403": { "description": "Forbidden due to missing organizational context or permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_permissions": { "summary": "Missing Permissions", "description": "The organization lacks the necessary permissions to perform this action.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Org context with org:settings:write is required." } } } } } }, "404": { "description": "Not Found when the specified Passport DID does not exist", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "passport_did_not_found": { "summary": "Passport DID Not Found", "description": "The specified Passport DID could not be found in the system.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The Passport DID does not correspond to any existing user." } } } } } }, "500": { "description": "Internal Server Error due to unforeseen circumstances", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request." } } } } } } } } }, "/v1/companion/preferences/org-defaults": { "get": { "summary": "Retrieve organizational preference defaults", "description": "Discover the foundational preferences that guide your organization's operations within the HUMAN platform. This endpoint reveals the default settings, ensuring that your orchestration processes are aligned and consistent. It's crucial for maintaining a seamless integration of AI and human workflows.", "operationId": "getOrgDefaults", "tags": [ "Organization", "Preferences" ], "x-code-hash": "1e63438de29f2283", "x-generated-at": "2026-04-29T22:13:12.849Z", "responses": { "200": { "description": "Successfully retrieved the organization's default preferences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_did": { "type": "string", "description": "The Decentralized Identifier (DID) of the organization." }, "preferences": { "type": "object", "description": "Key-value pairs representing the organization's default settings.", "additionalProperties": { "type": "string" } } }, "required": [ "org_did" ] }, "examples": { "acme_corp_defaults": { "summary": "Acme Corp Defaults", "description": "Example of Acme Corp's default preferences for task routing.", "value": { "org_did": "did:human:org:acme", "preferences": { "taskTimeout": "60s", "priorityLevel": "high" } } } } } } }, "403": { "description": "The client does not have permission to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "An organization context is required but missing.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Org context is required to read org defaults." } } } } } }, "404": { "description": "The requested organization's defaults were not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "defaults_not_found": { "summary": "Defaults Not Found", "description": "The organization's defaults could not be located.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested organization's defaults do not exist." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "A server-side error prevented the retrieval of defaults.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An error occurred while processing your request. Please try again later." } } } } } } } }, "put": { "summary": "Update organization default preferences", "description": "This endpoint allows organizations to customize their AI companion's interaction style by setting default preferences. Tailor the formality, humor, and verbosity to ensure the AI aligns with your company's culture and communication norms.", "operationId": "updateOrgDefaultPreferences", "tags": [ "Organization", "Preferences" ], "x-code-hash": "cca57ec5b18db12d", "x-generated-at": "2026-04-29T22:14:16.522Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enforce_formality": { "type": [ "string", "null" ], "description": "The level of formality to enforce." }, "enforce_humor_off": { "type": [ "boolean", "null" ], "description": "Whether to enforce humor to be off." }, "enforce_language": { "type": [ "string", "null" ], "description": "The language to enforce for communications." }, "default_formality": { "type": [ "string", "null" ], "description": "The default formality level for interactions." }, "default_humor_level": { "type": [ "string", "null" ], "description": "The default humor level to apply." }, "default_verbosity": { "type": [ "string", "null" ], "description": "The default verbosity of responses." }, "org_instructions": { "type": [ "string", "null" ], "description": "Custom instructions specific to the organization." } } }, "examples": { "set_default_preferences": { "summary": "Set Default Preferences", "description": "This example sets a formal communication style with no humor and English language.", "value": { "enforce_formality": "formal", "enforce_humor_off": true, "enforce_language": "en", "default_formality": "formal", "default_humor_level": null, "default_verbosity": "concise", "org_instructions": "Always use formal greetings." } } } } } }, "responses": { "200": { "description": "The organization's default preferences were successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enforce_formality": { "type": [ "string", "null" ] }, "enforce_humor_off": { "type": [ "boolean", "null" ] }, "enforce_language": { "type": [ "string", "null" ] }, "default_formality": { "type": [ "string", "null" ] }, "default_humor_level": { "type": [ "string", "null" ] }, "default_verbosity": { "type": [ "string", "null" ] }, "org_instructions": { "type": [ "string", "null" ] } } }, "examples": { "updated_preferences": { "summary": "Updated Preferences", "description": "The response after successfully updating preferences.", "value": { "enforce_formality": "formal", "enforce_humor_off": true, "enforce_language": "en", "default_formality": "formal", "default_humor_level": null, "default_verbosity": "concise", "org_instructions": "Always use formal greetings." } } } } } }, "400": { "description": "The request body is not valid JSON.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_json": { "summary": "Invalid JSON", "description": "The JSON request body was malformed.", "value": { "type": "https://api.haio.run/errors/invalid-body", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization": { "summary": "Missing Authorization", "description": "The request lacks valid authentication credentials.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authorization credentials are required to access this resource." } } } } } }, "403": { "description": "Forbidden access due to lack of organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "description": "The request was made without an organization context.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Org context is required to write org defaults." } } } } } }, "404": { "description": "The resource was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "The specified resource could not be located.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/preferences/observe": { "post": { "summary": "Record Turn-Level Conversation Patterns", "description": "This endpoint allows the HUMAN Companion agent to observe and record conversational patterns between users and AI assistants, capturing the essence of human-AI interaction. By analyzing these patterns, the system enhances its understanding, enabling more personalized and context-aware responses in future interactions.", "operationId": "postCompanionPreferencesObserve", "tags": [ "Companion", "Preferences" ], "x-code-hash": "1df92a1e303e1de6", "x-generated-at": "2026-04-29T22:13:29.438Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_text": { "type": "string", "description": "The text input by the user." }, "assistant_text": { "type": "string", "description": "The response generated by the AI assistant." }, "turn_id": { "type": "string", "description": "A unique identifier for the conversation turn." } }, "required": [ "user_text", "assistant_text" ] }, "examples": { "sample_user_and_assistant_interaction": { "summary": "Sample User and Assistant Interaction", "description": "Captures a user's query and assistant's response in a turn.", "value": { "user_text": "What's the weather like today?", "assistant_text": "It's sunny and 75 degrees.", "turn_id": "turn_1698771202931" } } } } } }, "responses": { "200": { "description": "The operation was successful, and the conversation patterns were recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Indicates successful recording." }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "pattern": { "type": "string", "description": "The detected pattern from the conversation." }, "confidence": { "type": "number", "description": "Confidence level of the pattern detection." } } } } } }, "examples": { "default": { "summary": "Example", "value": { "ok": true, "recorded": [ { "pattern": "weather inquiry", "confidence": 0.95 } ] } } } } } }, "400": { "description": "The request was malformed or contained invalid JSON.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/invalid-body", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/preferences/pending": { "get": { "summary": "Retrieve pending user preferences", "description": "Uncover the hidden preferences waiting to enhance your conversation experience. This endpoint helps users explore personalized settings that have yet to be confirmed, ensuring their interactions are tailored to their unique style. The magic lies in uncovering what your AI companion has learned about your preferences, fostering a more engaging dialogue.", "operationId": "getPendingPreferences", "tags": [ "Companion", "Preferences" ], "x-code-hash": "97593207dfb533d9", "x-generated-at": "2026-04-29T22:13:41.480Z", "responses": { "200": { "description": "Successfully retrieved pending preferences for the user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the pending preference." }, "pattern": { "type": "string", "description": "Pattern representing the pending preference." }, "confidence": { "type": "number", "description": "Confidence score of the preference suggestion." }, "consistent_turns": { "type": "integer", "description": "Number of consistent interactions leading to this preference." } }, "nullable": true } } }, "examples": { "pending_preferences_example": { "summary": "Pending Preferences Example", "description": "Illustrates a typical response with a pending preference suggestion.", "value": { "pending": { "id": "pref123", "pattern": "increase_verbosity", "confidence": 0.85, "consistent_turns": 5 } } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_error": { "summary": "Unauthorized Error", "description": "Occurs when a required delegation token is missing.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "500": { "description": "Internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "description": "An unexpected server error occurred.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/preferences/ack": { "post": { "summary": "Acknowledge companion preferences signal", "description": "This endpoint acknowledges a specific signal related to companion preferences, allowing the system to either save or skip the action based on user input. It's a crucial touchpoint for ensuring user preferences are respected in the orchestration of human and AI interactions.", "operationId": "acknowledgeCompanionPreferences", "tags": [ "Companion", "Preferences" ], "x-code-hash": "af078da724e06f50", "x-generated-at": "2026-04-29T22:13:58.998Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signal_id": { "type": "string", "description": "The unique identifier for the signal." }, "action": { "type": "string", "enum": [ "save", "skip" ], "description": "Action to perform on the signal, either 'save' or 'skip'." } }, "required": [ "signal_id", "action" ] }, "examples": { "acknowledge_save_action": { "summary": "Acknowledge Save Action", "description": "An example where the user acknowledges a signal with the 'save' action.", "value": { "signal_id": "abc123", "action": "save" } } } } } }, "responses": { "200": { "description": "The signal was successfully acknowledged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Indicates the successful processing of the request." }, "signal": { "type": "object", "description": "Details of the acknowledged signal." } } }, "examples": { "successful_acknowledgment": { "summary": "Successful Acknowledgment", "description": "The response on successfully acknowledging a signal with 'save'.", "value": { "ok": true, "signal": { "signal_id": "abc123", "status": "saved" } } } } } } }, "400": { "description": "The request body is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "The request is unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/companion/topics": { "get": { "summary": "Retrieve curated companion discussion topics", "description": "Explore a diverse array of conversation starters designed to enhance interactions between humans and AI. This endpoint empowers users to engage with the HUMAN platform by providing dynamic and contextually relevant topics tailored to their interests. Whether you're a developer or an end-user, these topics help you unlock the full potential of AI interactions, fostering creativity and collaboration.", "operationId": "getCompanionTopics", "tags": [ "Companion", "Topics" ], "x-code-hash": "b0529fd8625ca1cc", "x-generated-at": "2026-04-30T22:46:10.320Z", "responses": { "200": { "description": "A list of companion topics successfully retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the topic." }, "title": { "type": "string", "description": "Title of the companion topic." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the topic was created." } } } }, "limit": { "type": "integer", "description": "The maximum number of topics returned." }, "cursorFields": { "type": "array", "items": { "type": "string" }, "description": "Fields used for pagination." }, "hasMore": { "type": "boolean", "description": "Indicator if more topics are available." } } }, "examples": { "successful_topic_retrieval": { "summary": "Successful Topic Retrieval", "description": "A user retrieves a list of topics for a seamless companion experience.", "value": { "data": [ { "id": "topic-123", "title": "AI and Human Collaboration", "created_at": "2023-10-01T12:00:00Z" }, { "id": "topic-456", "title": "Future of AI Ethics", "created_at": "2023-10-02T15:30:00Z" } ], "limit": 50, "cursorFields": [ "created_at", "id" ], "hasMore": true } } } } } }, "400": { "description": "Invalid cursor or pagination parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor_error": { "summary": "Invalid Cursor Error", "description": "Occurs when the provided cursor is malformed or expired.", "value": { "type": "https://api.haio.run/errors/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The cursor value is malformed or expired. Omit the cursor to restart from the beginning." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "Occurs when the user does not provide a valid delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "description": "Occurs when the user has a valid token but lacks the necessary permissions.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these topics. Please check your credentials and permissions." } } } } } }, "404": { "description": "Requested resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "description": "Occurs when the specified topics do not exist.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested topics could not be found. Please verify the endpoint and try again." } } } } } }, "500": { "description": "Internal server error while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Occurs due to an unexpected condition on the server.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } }, "post": { "summary": "Create or Update Companion Topics", "description": "This endpoint allows you to create or update topics associated with a user's companion profile. By harnessing the power of categorization, it enables a richer, more personalized interaction between humans and AI. Elevate your user experience by tailoring interactions based on the topics that matter most.", "operationId": "createOrUpdateCompanionTopics", "tags": [ "Companion", "Topics" ], "x-code-hash": "fb4afb6b27fcc603", "x-generated-at": "2026-04-29T22:15:01.308Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "interest", "preference", "skill" ] }, "value": { "type": "string", "minLength": 1 }, "display_label": { "type": "string" }, "source": { "type": "string", "enum": [ "onboarding", "user_input", "system_generated" ] } }, "required": [ "category", "value" ] } } }, "required": [ "topics" ] }, "examples": { "basic_topics_example": { "summary": "Basic Topics Example", "description": "Adding topics related to a user's interests and preferences.", "value": { "topics": [ { "category": "interest", "value": "machine learning", "display_label": "Machine Learning Enthusiast", "source": "user_input" }, { "category": "preference", "value": "dark mode", "source": "onboarding" } ] } } } } } }, "responses": { "201": { "description": "The topics were successfully created or updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "value": { "type": "string" }, "display_label": { "type": "string" }, "source": { "type": "string" } } } } } }, "examples": { "default": { "summary": "Example", "value": { "data": [ { "category": "interest", "value": "machine learning", "display_label": "Machine Learning Enthusiast", "source": "user_input" }, { "category": "preference", "value": "dark mode", "display_label": "dark mode", "source": "onboarding" } ] } } } } } }, "400": { "description": "Invalid request due to malformed JSON or validation errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/validation", "title": "Validation Error", "status": 400, "detail": "One or more fields failed validation.", "errors": [ { "field": "topics[0].category", "code": "INVALID_VALUE", "message": "category must be one of: interest, preference, skill", "expected": "interest|preference|skill", "received": "hobby" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/topics/:id": { "delete": { "summary": "Remove a companion chat topic", "description": "Effortlessly retire a conversation topic and make room for new ideas in your chat. This endpoint ensures only authorized users can manage topics, preserving the integrity of your discussions.", "operationId": "deleteCompanionTopic", "tags": [ "Chat", "Companion" ], "x-code-hash": "404320a3c86127eb", "x-generated-at": "2026-04-29T22:15:17.498Z", "responses": { "200": { "description": "Successfully deleted the specified chat topic.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Indicates the operation was successful." }, "topic_id": { "type": "string", "description": "The ID of the deleted chat topic." } } }, "examples": { "successful_deletion": { "summary": "Successful deletion", "description": "The chat topic with ID 'topic123' was successfully deleted.", "value": { "ok": true, "topic_id": "topic123" } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_topic_id": { "summary": "Invalid Topic ID", "description": "An incorrect format for the topic ID was provided.", "value": { "type": "https://api.haio.run/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The provided topic ID is invalid." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_token": { "summary": "Missing Token", "description": "The request did not include a valid delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "403": { "description": "Forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "insufficient_permissions": { "summary": "Insufficient Permissions", "description": "The user does not have the necessary permissions to delete the topic.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to delete this topic." } } } } } }, "404": { "description": "Not Found if the topic does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "topic_not_found": { "summary": "Topic Not Found", "description": "The specified topic ID does not exist.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested topic ID topic123 was not found." } } } } } }, "500": { "description": "Internal Server Error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_error": { "summary": "Unexpected Error", "description": "A server error occurred, preventing the deletion.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/control-plane/extensions": { "get": { "summary": "Retrieve Available Extensions for Navigation", "description": "Discover the universe of extensions tailored to your organization's needs, filtered by navigation scope. This endpoint opens the door to a curated selection of tools, enhancing your organization's capabilities with precision.", "operationId": "getControlPlaneExtensions", "tags": [ "Extensions", "Control Plane" ], "x-code-hash": "98e1228e7ba6f9b9", "x-generated-at": "2026-04-29T22:15:39.633Z", "responses": { "200": { "description": "A list of available extensions matching the specified navigation scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "extensions": { "type": "array", "items": { "type": "object", "properties": { "installation_id": { "type": "string", "example": "inst-12345" }, "asset_id": { "type": "string", "example": "asset-67890" }, "asset_name": { "type": "string", "example": "AI Companion" }, "nav_scope": { "type": "string", "example": "companion_panel" }, "tools": { "type": "array", "items": { "type": "string", "example": "tool-abc" } } } } } } }, "examples": { "successful_retrieval_of_extensions": { "summary": "Successful retrieval of extensions", "description": "A user from the 'acme' organization retrieves extensions related to the 'companion_panel' navigation scope.", "value": { "extensions": [ { "installation_id": "inst-12345", "asset_id": "asset-67890", "asset_name": "AI Companion", "nav_scope": "companion_panel", "tools": [ "tool-abc", "tool-def" ] } ] } } } } } }, "400": { "description": "Bad Request - Validation errors in input parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_nav_scope_parameter": { "summary": "Missing nav_scope parameter", "description": "The request failed because the 'nav_scope' parameter was not provided.", "value": { "type": "https://example.com/probs/validation-error", "title": "Validation Error", "status": 400, "detail": "The nav_scope query parameter is required.", "errors": [ { "field": "nav_scope", "code": "REQUIRED_FIELD_MISSING", "message": "nav_scope query parameter is required.", "expected": "string (e.g. companion_panel)", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized - Authentication required to access this resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "description": "The request failed due to missing authentication delegation.", "value": { "type": "https://example.com/probs/authentication-error", "title": "Authentication Error", "status": 401, "detail": "Delegation required" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions to access this resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_orgdid_in_delegation": { "summary": "Missing orgDid in delegation", "description": "The request was forbidden as the required orgDid was not present in the delegation.", "value": { "type": "https://example.com/probs/authorization-error", "title": "Authorization Error", "status": 403, "detail": "Delegation must include orgDid for this endpoint" } } } } } }, "404": { "description": "Not Found - The requested resource could not be found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "nonexistent_resource": { "summary": "Nonexistent resource", "description": "The request attempted to access a resource that does not exist.", "value": { "type": "https://example.com/probs/not-found", "title": "Resource Not Found", "status": 404, "detail": "Requested resource does not exist" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "value": { "type": "https://example.com/probs/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/billing/limits": { "get": { "summary": "Retrieve billing limits for your organization", "description": "Discover the financial boundaries of your organization's AI orchestration with HUMAN. This endpoint reveals your session and daily API rate limits, compute markup, and plan tier caps, helping you manage costs and maximize efficiency. Whether you're a startup on a 'free' plan or an enterprise seeking limitless potential, understanding these limits is crucial for strategic planning.", "operationId": "getBillingLimits", "tags": [ "Billing", "Limits" ], "x-code-hash": "8497e9adb644cf1c", "x-generated-at": "2026-04-29T22:15:57.304Z", "responses": { "200": { "description": "Returns the current billing limits and configuration for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_rate_limit_per_session_per_min": { "type": "integer", "description": "The maximum number of requests allowed per session per minute." }, "api_rate_limit_per_org_per_day": { "type": "integer", "description": "The maximum number of API requests allowed per organization per day." }, "compute_markup_pct": { "type": "number", "description": "The percentage markup applied to compute costs." }, "compute_warning_threshold_pct": { "type": "integer", "description": "Threshold percentage at which a warning is issued before reaching compute limits." }, "plan_tier_caps": { "type": "object", "properties": { "free": { "type": "object", "properties": { "compute_usd": { "type": "integer", "nullable": true } } }, "pro": { "type": "object", "properties": { "compute_usd": { "type": "integer", "nullable": true } } }, "business": { "type": "object", "properties": { "compute_usd": { "type": "integer", "nullable": true } } }, "enterprise": { "type": "object", "properties": { "compute_usd": { "type": "integer", "nullable": true } } } } }, "org_did": { "type": "string", "nullable": true, "description": "The decentralized identifier for the organization." } } }, "examples": { "standard_organization_limits": { "summary": "Standard Organization Limits", "value": { "mcp_rate_limit_per_session_per_min": 20, "api_rate_limit_per_org_per_day": 100000, "compute_markup_pct": 0, "compute_warning_threshold_pct": 80, "plan_tier_caps": { "free": { "compute_usd": 5 }, "pro": { "compute_usd": 50 }, "business": { "compute_usd": 500 }, "enterprise": { "compute_usd": null } }, "org_did": "did:human:acme-org-1234" } } } } } }, "400": { "description": "Bad Request due to invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The request parameters are invalid. Please review the API documentation and ensure all required parameters are correct." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication credentials were missing or incorrect. Make sure your API key is valid and retry." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have the necessary permissions to access this resource. Contact your administrator for access." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource could not be found. Verify the endpoint URL and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://humanprotocol.org/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred on the server. Please try again later or contact support if the issue persists." } } } } } } } } }, "/v1/billing/compute-usage": { "get": { "summary": "Retrieve monthly compute usage by organization", "description": "Unveil your organization's compute usage story for the current month. This endpoint empowers cloud administrators to monitor resource consumption and manage billing efficiently, ensuring that usage aligns with organizational plans and authorized top-ups. Understand your usage patterns and avoid surprises by staying informed.", "operationId": "getComputeUsage", "tags": [ "Billing", "Compute" ], "x-code-hash": "a493644b48231772", "x-generated-at": "2026-04-30T22:47:53.228Z", "responses": { "200": { "description": "Successfully retrieved compute usage for the organization(s). This provides transparency into spending and helps manage resources effectively.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgs": { "type": "array", "items": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier for the organization." }, "plan_tier": { "type": "string", "description": "The subscription plan tier of the organization." }, "used_usd": { "type": "number", "description": "The amount of compute resources used in USD." }, "included_usd": { "type": "number", "description": "The compute resources included in the plan in USD." }, "authorized_topup_usd": { "type": "number", "description": "The authorized top-up amount for compute resources." }, "ceiling_usd": { "type": [ "number", "null" ], "description": "The maximum allowed spend including top-ups." }, "used_pct": { "type": "number", "description": "Percentage of the compute ceiling that has been used." }, "stage": { "type": "string", "description": "The usage status indicating if it's within limits, nearing, or has hit the ceiling." } }, "required": [ "org_did", "plan_tier", "used_usd", "included_usd", "authorized_topup_usd", "ceiling_usd", "used_pct", "stage" ] } } } }, "examples": { "compute_usage_for_acme_corporation": { "summary": "Compute Usage for Acme Corporation", "value": { "orgs": [ { "org_did": "did:example:acme-org", "plan_tier": "pro", "used_usd": 45, "included_usd": 50, "authorized_topup_usd": 10, "ceiling_usd": 60, "used_pct": 75, "stage": "ok" } ] } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions or missing org context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "cross-tenant_usage_forbidden": { "summary": "Cross-Tenant Usage Forbidden", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Cross-tenant compute usage requires cloud:admin:billing or cloud:admin:global delegation." } }, "org_context_required": { "summary": "Org Context Required", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Org context required to read compute usage." } } } } } }, "500": { "description": "Internal server error encountered while fetching compute usage.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request. Please try again later." } } } } } } } } }, "/v1/billing/authorize-overage": { "post": { "summary": "Authorize billing overage for an organization", "description": "Unlock additional billing capacity beyond preset limits with this endpoint, ensuring your organization never hits a processing ceiling. It's designed for those moments when unexpected demand is a sign of success, not a bottleneck.", "operationId": "authorizeBillingOverage", "tags": [ "Billing", "Authorization" ], "x-code-hash": "bc04da9101af59c0", "x-generated-at": "2026-04-29T22:16:39.211Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_usd": { "type": "number", "description": "The amount in USD to authorize for overage.", "minimum": 0.01, "maximum": 10000 }, "window_minutes": { "type": "number", "description": "The validity duration of the authorization in minutes.", "minimum": 1, "maximum": 1440 }, "auto_topup": { "type": "boolean", "description": "If true, enables automatic top-up when balance is low." } }, "required": [ "amount_usd" ] }, "examples": { "authorize_$500_overage_for_2_hours": { "summary": "Authorize $500 overage for 2 hours", "description": "An example where the organization authorizes a $500 overage for 120 minutes with auto top-up enabled.", "value": { "amount_usd": 500, "window_minutes": 120, "auto_topup": true } } } } } }, "responses": { "200": { "description": "Successfully authorized the overage for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "org_did": { "type": "string" }, "authorized_topup_usd": { "type": "number" }, "auto_topup_enabled": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" } } }, "examples": { "successful_overage_authorization": { "summary": "Successful Overage Authorization", "value": { "ok": true, "org_did": "did:org:acme", "authorized_topup_usd": 500, "auto_topup_enabled": true, "expires_at": "2023-10-23T16:00:00Z" } } } } } }, "400": { "description": "The request body contained invalid JSON or values.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_json_request": { "summary": "Invalid JSON Request", "value": { "type": "https://api.haio.run/errors/invalid-body", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "amount_usd", "code": "INVALID_VALUE", "message": "amount_usd must be > 0 and <= 10000.", "expected": "number", "received": "string" } ] } } } } } }, "403": { "description": "The request lacked necessary organization context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_organization_context": { "summary": "Missing Organization Context", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Org context required to authorize overage." } } } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/canvas": { "get": { "summary": "Retrieve paginated list of canvases", "description": "Explore the dynamic world of your HUMAN canvases with this endpoint. Aimed at bringing forth your creative artifacts, it seamlessly integrates your digital identity with a cryptographic passport, ensuring secure and personalized access. Dive into your collection with ease, supported by cursor-based pagination to traverse large datasets effortlessly.", "operationId": "getCompanionCanvasList", "tags": [ "Canvas", "HUMAN" ], "x-code-hash": "ea534ea47cde260e", "x-generated-at": "2026-04-30T15:49:02.593Z", "responses": { "200": { "description": "Successfully retrieved list of canvases", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "org_did": { "type": "string", "nullable": true }, "kind": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "title", "version", "updated_at" ] } }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "cursorFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "limit", "hasMore", "cursorFields" ] }, "examples": { "successful_canvas_retrieval": { "summary": "Successful Canvas Retrieval", "description": "Retrieve the first page of canvases created by the user.", "value": { "data": [ { "id": "canvas123", "org_did": "did:example:org123", "kind": "artwork", "title": "Sunset Overdrive", "version": 2, "updated_at": "2023-10-01T12:00:00Z" } ], "limit": 10, "hasMore": false, "cursorFields": [ "updated_at", "id" ] } } } } } }, "400": { "description": "Bad request due to malformed query parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_pagination_parameters": { "summary": "Invalid Pagination Parameters", "description": "Occurs when pagination parameters are malformed.", "value": { "type": "https://api.haio.run/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The 'limit' parameter must be a positive integer and 'cursor' must be a valid base64-encoded string." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_authorization": { "summary": "Missing Authorization", "description": "Occurs when the user is not authenticated.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please ensure you have provided a valid passport or authorization token." } } } } } }, "500": { "description": "Internal server error due to unexpected issues", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected Server Error", "description": "Occurs when the server encounters an unexpected condition.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support if the issue persists." } } } } } } } }, "post": { "summary": "Create a new canvas for collaboration", "description": "This endpoint invites you to orchestrate human and AI interactions by creating a canvas. A canvas is a collaborative space where ideas are transformed into structured insights. It is your creative playground in the HUMAN ecosystem, enabling seamless AI-human collaboration through a robust infrastructure that ensures provenance and identity verification.", "operationId": "createCompanionCanvas", "tags": [ "Canvas", "Collaboration" ], "x-code-hash": "af89e1e4a789429f", "x-generated-at": "2026-04-30T00:02:35.905Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "type": "object", "properties": { "canvas_id": { "type": "string", "description": "Unique identifier for the canvas. Auto-generated if not provided." }, "kind": { "type": "string", "description": "Type of the canvas, e.g., 'rich_report'." }, "title": { "type": "string", "description": "Title of the canvas." }, "version": { "type": "number", "description": "Version number of the canvas." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the canvas was created." }, "conversation_id": { "type": "string", "description": "Associated conversation identifier." }, "version_label": { "type": "string", "description": "Label for the canvas version." }, "ttl": { "type": "string", "enum": [ "session", "persistent" ], "description": "Time-to-live for the canvas." }, "provenance_receipt_id": { "type": "string", "description": "Receipt ID for provenance tracking." } }, "required": [ "kind", "title" ] } }, "required": [ "spec" ] }, "examples": { "create_a_rich_report_canvas": { "summary": "Create a Rich Report Canvas", "description": "Creating a canvas for a quarterly business report.", "value": { "spec": { "kind": "rich_report", "title": "Q1 Business Report", "version": 1 } } } } } } }, "responses": { "201": { "description": "Canvas successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canvas_id": { "type": "string", "description": "The ID of the newly created canvas." }, "spec": { "type": "object", "description": "Full specification of the created canvas.", "properties": { "canvas_id": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "number" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_id": { "type": "string", "nullable": true }, "version_label": { "type": "string", "nullable": true }, "ttl": { "type": "string" }, "provenance_receipt_id": { "type": "string", "nullable": true } } } } }, "examples": { "successful_creation": { "summary": "Successful Creation", "value": { "canvas_id": "abc123", "spec": { "canvas_id": "abc123", "kind": "rich_report", "title": "Q1 Business Report", "version": 1, "created_by": "did:human:acme123", "created_at": "2023-10-10T12:00:00Z", "updated_at": "2023-10-10T12:00:00Z", "ttl": "persistent" } } } } } } }, "400": { "description": "Invalid request format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_spec_field": { "summary": "Missing Spec Field", "value": { "type": "https://api.haio.run/errors/invalid-body", "title": "Invalid JSON", "status": 400, "detail": "Request body must be JSON.", "errors": [ { "field": "spec", "code": "REQUIRED_FIELD_MISSING", "message": "spec object is required.", "expected": "object", "received": "undefined" } ] } } } } } }, "401": { "description": "Authorization required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required." } } } } } }, "403": { "description": "Forbidden access due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access": { "summary": "Forbidden Access", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to create a canvas." } } } } } }, "404": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "canvas_not_found": { "summary": "Canvas Not Found", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The specified canvas could not be found." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/canvas/:id": { "get": { "summary": "Retrieve a specific canvas by ID", "description": "Unveil the intricate details of a specific canvas, a dynamic workspace within the HUMAN platform. This endpoint empowers users to access canvases that they are authorized to view, facilitating collaboration and innovation within secure boundaries.", "operationId": "getCanvasById", "tags": [ "Canvas", "Access Control" ], "x-code-hash": "16ea72c0ca063e7e", "x-generated-at": "2026-04-30T00:02:47.965Z", "responses": { "200": { "description": "The canvas was successfully retrieved, providing the detailed specifications.", "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "type": "object", "description": "The specifications and details of the canvas." } } }, "examples": { "successful_retrieval_of_an_invoice_canvas": { "summary": "Successful retrieval of an invoice canvas", "description": "This example demonstrates a successful retrieval of an 'acme' organization's invoice processing canvas.", "value": { "spec": { "title": "Invoice Processing Canvas", "createdBy": "agent:john.doe", "tasks": [ "Parse Invoice", "Validate Invoice", "Approve Payment" ] } } } } } } }, "400": { "description": "Invalid request due to malformed ID or other parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_id_example": { "summary": "Malformed ID example", "description": "An error response when the provided canvas ID is not valid.", "value": { "type": "https://api.haio.run/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The canvas ID '123-abc' is malformed. Ensure it is a valid UUID." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "description": "An error response when the user attempts to access a canvas without proper delegation.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Assign an agent with the necessary privileges." } } } } } }, "404": { "description": "The specified canvas was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "canvas_not_found": { "summary": "Canvas not found", "description": "An error response when the canvas with the specified ID does not exist or is not accessible by the user.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Canvas with ID 'canvas-001' was not found. Verify the ID and ensure you have access rights." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "An example of a server-side malfunction preventing the retrieval of the canvas.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/canvas/:id/operations": { "patch": { "summary": "Apply JSON Patch to Canvas with Versioning", "description": "This endpoint allows users to apply a JSON Patch to a specific canvas, enabling real-time collaboration and version control. By maintaining a version snapshot, it ensures that all changes are traceable and that users can coordinate seamlessly in dynamic environments.", "operationId": "patchCanvasOperations", "tags": [ "Canvas", "Collaboration" ], "x-code-hash": "75db0c33e56ea9e8", "x-generated-at": "2026-04-30T15:49:22.542Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ops": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" }, "path": { "type": "string" }, "value": {} }, "required": [ "op", "path" ] }, "description": "A non-empty array of JSON Patch operations." }, "seq": { "type": "integer", "description": "The operation sequence number." }, "version_label": { "type": "string", "description": "An optional label for the version." } }, "required": [ "ops" ] }, "examples": { "basic_patch_example": { "summary": "Basic Patch Example", "description": "Apply a simple patch operation to update canvas title.", "value": { "ops": [ { "op": "replace", "path": "/title", "value": "New Canvas Title" } ], "version_label": "v2.0" } } } } } }, "responses": { "200": { "description": "The canvas was successfully updated with the provided JSON Patch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canvas_id": { "type": "string", "description": "The ID of the updated canvas." }, "spec": { "type": "object", "description": "The updated canvas specification." }, "version": { "type": "integer", "description": "The new version number of the canvas." }, "version_label": { "type": "string", "description": "The label associated with this version." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "The server could not process the request due to client error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Authentication is required and has failed or has not yet been provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The specified canvas could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/companion/canvas/:id/versions": { "get": { "summary": "Retrieve paginated canvas version history", "description": "Explore the rich tapestry of your canvas's evolution with this endpoint. Designed for those who seek to understand the journey of their creations, it provides a paginated list of all versions. Dive deep into the past and see how your ideas have transformed over time.", "operationId": "getCanvasVersions", "tags": [ "Canvas", "Versioning" ], "x-code-hash": "70596fb69a927ee4", "x-generated-at": "2026-04-30T15:49:40.136Z", "responses": { "200": { "description": "A successful response containing a paginated list of canvas versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "version_id": { "type": "string", "description": "The unique identifier for the version." }, "version": { "type": "integer", "description": "The version number." }, "version_label": { "type": "string", "description": "An optional label for the version." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the version was created." }, "authored_by": { "type": "string", "description": "The author of this version." } } } }, "limit": { "type": "integer", "description": "The maximum number of items returned." }, "hasMore": { "type": "boolean", "description": "Indicates if there are more items available." }, "cursorField": { "type": "string", "description": "The field used for pagination." } } }, "examples": { "acme_canvas_versions": { "summary": "Acme Canvas Versions", "value": { "data": [ { "version_id": "v1-abc123", "version": 3, "version_label": "Final Draft", "created_at": "2023-09-01T12:34:56Z", "authored_by": "jdoe@acme.com" }, { "version_id": "v1-def456", "version": 2, "version_label": "Revised", "created_at": "2023-08-25T09:30:00Z", "authored_by": "jdoe@acme.com" } ], "limit": 2, "hasMore": true, "cursorField": "version" } } } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_cursor": { "summary": "Invalid Cursor", "value": { "type": "https://api.haio.run/errors/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The provided cursor is not valid. Ensure the cursor is correctly encoded and try again." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required. Please provide valid credentials." } } } } } }, "403": { "description": "Forbidden access to the specified canvas.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Access to this canvas is not allowed. Please check your permissions." } } } } } }, "404": { "description": "Not found when the specified canvas ID does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "canvas_not_found": { "summary": "Canvas Not Found", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The canvas with ID 'canvas123' was not found. Verify the ID and try again." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error": { "summary": "Server Error", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later or contact support." } } } } } } } } }, "/v1/companion/canvas/:id/versions/:v/restore": { "post": { "summary": "Restore a Previous Canvas Version", "description": "In the fast-paced world of collaborative design, moments of inspiration can sometimes be lost. This endpoint allows you to restore a previous version of your canvas, ensuring that no spark of creativity is ever truly extinguished. By leveraging HUMAN's sophisticated provenance tracking, you can effortlessly rewind time and bring back past iterations with ease and transparency.", "operationId": "restoreCanvasVersion", "tags": [ "Canvas", "VersionControl" ], "x-code-hash": "24e17b3136fd1331", "x-generated-at": "2026-04-30T15:49:54.238Z", "responses": { "200": { "description": "Successfully restored the specified canvas version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canvas_id": { "type": "string", "description": "The identifier for the canvas." }, "spec": { "type": "object", "description": "The specification snapshot of the restored canvas." }, "version": { "type": "integer", "description": "The new version number of the canvas after restoration." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid version parameter provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "The request was unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Permission denied to restore the specified canvas version.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The requested canvas or version was not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/companion/contexts": { "get": { "summary": "Retrieve User Contexts for Delegated Access", "description": "This endpoint reveals the rich tapestry of organizational contexts a human agent operates within. By leveraging delegation, it ensures users can seamlessly access the ecosystems they're part of, empowering decisions with appropriate authority and insight.", "operationId": "getCompanionContexts", "tags": [ "Authorization", "User Context" ], "x-code-hash": "461a4ac9ce06d201", "x-generated-at": "2026-04-30T00:04:10.822Z", "responses": { "200": { "description": "Successfully retrieves a list of organizational contexts for the authenticated user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "org_did": { "type": "string", "description": "Decentralized Identifier for the organization." }, "org_name": { "type": "string", "description": "Name of the organization." }, "org_logo_url": { "type": "string", "description": "URL to the organization's logo.", "nullable": true }, "role": { "type": "string", "description": "Role of the user within the organization." } }, "required": [ "org_did", "org_name", "role" ] } } }, "required": [ "data" ] }, "examples": { "successful_retrieval_of_contexts": { "summary": "Successful retrieval of contexts", "description": "Retrieve contexts for a user with access to multiple organizations", "value": { "data": [ { "org_did": "did:example:123456789abcdefghi", "org_name": "Acme Corporation", "org_logo_url": "https://example.com/logos/acme.png", "role": "admin" }, { "org_did": "did:example:987654321hgfedcba", "org_name": "Globex Corporation", "org_logo_url": null, "role": "member" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_example": { "summary": "Missing Delegation Example", "description": "The user attempted to access contexts without a valid delegation.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required." } } } } } }, "403": { "description": "Access forbidden due to insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "forbidden_access_example": { "summary": "Forbidden Access Example", "description": "The user tried to access contexts they do not have permission for.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access these contexts." } } } } } }, "500": { "description": "Internal server error, indicating issues on the server side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "server_error_example": { "summary": "Server Error Example", "description": "A generic server error occurred, preventing the retrieval of contexts.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/canvas/:id/versions/:v": { "get": { "summary": "Retrieve a specific canvas version", "description": "In the ever-evolving world of collaborative design, keeping track of changes is crucial. This endpoint empowers you to fetch a specific version of a canvas, providing a snapshot of its state at a particular moment. Ideal for revisiting past designs or auditing changes.", "operationId": "getCanvasVersion", "tags": [ "Canvas", "VersionControl" ], "x-code-hash": "505710a2d5da3e38", "x-generated-at": "2026-04-30T15:48:44.982Z", "responses": { "200": { "description": "Successfully retrieved the canvas version snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "version_id": { "type": "string", "description": "Unique identifier for the canvas version" }, "canvas_id": { "type": "string", "description": "Unique identifier for the canvas" }, "version": { "type": "integer", "description": "Version number of the canvas" }, "version_label": { "type": [ "string", "null" ], "description": "Label for the version, if any" }, "spec_snapshot": { "type": "object", "description": "Snapshot of the canvas specification at this version" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp of this version" }, "authored_by": { "type": "string", "description": "The DID of the author who created this version" } }, "required": [ "version_id", "canvas_id", "version", "spec_snapshot", "created_at", "authored_by" ] }, "examples": { "successful_canvas_version_retrieval": { "summary": "Successful canvas version retrieval", "description": "Example of successfully retrieving version 3 of canvas 'abc123'.", "value": { "version_id": "v3-abc123", "canvas_id": "abc123", "version": 3, "version_label": "Initial Design", "spec_snapshot": { "elements": [], "metadata": { "theme": "dark" } }, "created_at": "2023-10-02T14:48:00Z", "authored_by": "did:human:12345" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_version_number": { "summary": "Invalid version number", "description": "The provided version number was not a positive integer.", "value": { "type": "https://api.haio.run/errors/validation", "title": "Invalid Request Parameter", "status": 400, "detail": "The request contains one or more invalid parameters.", "errors": [ { "field": "v", "code": "INVALID_VALUE", "message": "version must be a positive integer.", "expected": "number", "received": "-1" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation": { "summary": "Missing delegation", "description": "The request was made without proper authorization.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Delegation required." } } } } } }, "403": { "description": "Forbidden access to resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "access_denied": { "summary": "Access denied", "description": "The user is not permitted to access this canvas.", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this canvas." } } } } } }, "404": { "description": "Canvas or version not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "canvas_not_found": { "summary": "Canvas not found", "description": "The requested canvas does not exist in the system.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Canvas with ID 'abc123' was not found." } }, "version_not_found": { "summary": "Version not found", "description": "The specified version of the canvas does not exist.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "Canvas version '5' was not found for canvas 'abc123'." } } } } } }, "500": { "description": "Unexpected server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal server error", "description": "An unexpected error occurred on the server.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/c2c/:passport_did/inbox": { "post": { "summary": "Deliver cross-user C2C messages securely", "description": "In the interconnected world of HUMAN, delivering messages between users is crucial. This endpoint allows users to send messages directly to another's inbox, ensuring authenticity with Ed25519 signatures. It's the lifeline for secure communication within HUMAN's vibrant ecosystem.", "operationId": "postCompanionC2CInbox", "tags": [ "Messaging", "C2C" ], "x-code-hash": "292c18932579f403", "x-generated-at": "2026-04-30T22:46:30.549Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string", "description": "Unique identifier for the message." }, "thread_id": { "type": "string", "description": "Identifier for the conversation thread." }, "recipient_did": { "type": "string", "description": "DID of the message recipient." }, "sender_did": { "type": "string", "description": "DID of the message sender." }, "intent_kind": { "type": "string", "description": "The type of intent this message carries." }, "payload": { "type": "object", "description": "The actual content of the message." }, "signature": { "type": "string", "description": "Ed25519 signature for message authentication." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the message was created." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration time of the message, if applicable." } }, "required": [ "message_id", "recipient_did", "sender_did", "intent_kind", "payload", "signature", "created_at" ] }, "examples": { "standard_message_delivery": { "summary": "Standard Message Delivery", "description": "A typical message sent from one user to another, ensuring secure delivery.", "value": { "message_id": "msg-123456", "thread_id": "thread-abcde", "recipient_did": "did:example:recipient", "sender_did": "did:example:sender", "intent_kind": "inform", "payload": { "text": "Hello, this is a secure message!" }, "signature": "abc123signature", "created_at": "2023-10-01T14:48:00Z", "expires_at": "2023-10-02T14:48:00Z" } } } } } }, "responses": { "202": { "description": "Message was successfully received and processed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "description": "Indicates successful receipt." }, "message_id": { "type": "string", "description": "The ID of the message that was processed." } } }, "examples": { "default": { "summary": "Example", "value": { "received": true, "message_id": "msg-123456" } } } } } }, "400": { "description": "Bad request due to invalid input data or recipient mismatch.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/c2c/recipient-mismatch", "title": "Recipient mismatch", "status": 400, "detail": "Message recipient (did:example:wrong) does not match inbox URL (did:example:recipient).", "expected_recipient": "did:example:recipient", "actual_recipient": "did:example:wrong" } } } } } }, "401": { "description": "Unauthorized due to unknown sender or invalid signature.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/c2c/invalid-signature", "title": "Invalid message signature", "status": 401, "detail": "Signature verification failed." } } } } } }, "409": { "description": "Conflict due to duplicate message ID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/c2c/message-id-conflict", "title": "Duplicate message", "status": 409, "detail": "A message with this message_id was already recorded.", "message_id": "msg-123456" } } } } } }, "500": { "description": "Internal server error due to storage failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/c2c/storage-failed", "title": "Message storage failed", "status": 500, "detail": "The message was valid but could not be stored: Database error" } } } } } } } } }, "/v1/companion/c2c/inbox": { "get": { "summary": "Retrieve User's C2C Inbox Messages", "description": "Dive into your collaborative journey with the C2C Inbox, where every message is a thread in the fabric of your professional narrative. This endpoint empowers users to access their cross-channel communications, reflecting the dynamic interactions in the HUMAN ecosystem.", "operationId": "getC2CInboxMessages", "tags": [ "Communication", "Inbox" ], "x-code-hash": "8177d350bcf1c6ef", "x-generated-at": "2026-04-30T22:46:42.465Z", "responses": { "200": { "description": "Successfully retrieved the list of C2C messages for the user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "message_id": { "type": "string", "description": "Unique identifier for the message" }, "thread_id": { "type": "string", "description": "Identifier of the conversation thread" }, "sender_did": { "type": "string", "description": "DID of the message sender" }, "intent_kind": { "type": "string", "description": "Type of intent behind the message" }, "payload": { "type": "object", "description": "The content of the message" }, "status": { "type": "string", "description": "Current status of the message" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the message was created" } } } }, "hasMore": { "type": "boolean", "description": "Indicates if there are more messages to fetch" } } }, "examples": { "successful_inbox_retrieval": { "summary": "Successful Inbox Retrieval", "description": "A user retrieves their inbox messages with a pagination cursor.", "value": { "data": [ { "message_id": "msg-001", "thread_id": "thr-123", "sender_did": "did:example:sender123", "intent_kind": "greeting", "payload": { "text": "Hello, how can we collaborate today?" }, "status": "unread", "created_at": "2023-10-08T14:00:00Z" } ], "hasMore": false } } } } } }, "400": { "description": "Bad request due to malformed input.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_cursor_error": { "summary": "Malformed Cursor Error", "description": "The user provided an invalid cursor for pagination.", "value": { "type": "https://api.haio.run/errors/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The cursor value is malformed or expired. Omit the cursor to restart from the beginning." } } } } } }, "401": { "description": "Unauthorized access due to missing delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "description": "The request was made without a valid delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token is required to access the C2C inbox." } } } } } }, "500": { "description": "Server error occurred while fetching the inbox.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_error": { "summary": "Database Error", "description": "An unexpected error occurred while trying to access the database.", "value": { "type": "https://api.haio.run/errors/internal", "title": "Inbox fetch failed", "status": 500, "detail": "Could not retrieve C2C inbox: Database error" } } } } } } } } }, "/v1/companion/c2c/:message_id/respond": { "patch": { "summary": "Respond to a C2C message", "description": "Orchestrate the dance between humans and AI by responding to a Message using HUMAN's dynamic protocol. Whether accepting, rejecting, or countering, this endpoint ensures the conversation continues with purpose and clarity.", "operationId": "respondToC2CMessage", "tags": [ "Companion", "C2C" ], "x-code-hash": "c15de80b38f0785c", "x-generated-at": "2026-04-30T19:14:29.905Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "accept", "reject", "counter" ], "description": "The decision on the message: 'accept', 'reject', or 'counter'." }, "reason": { "type": "string", "description": "Optional explanation for the chosen action." } }, "required": [ "action" ] }, "examples": { "accept_the_message": { "summary": "Accept the Message", "description": "Shows a response where the user accepts a message with no additional comment.", "value": { "action": "accept" } }, "reject_with_reason": { "summary": "Reject with Reason", "description": "Illustrates rejecting a message with a reason provided.", "value": { "action": "reject", "reason": "The proposal does not align with current objectives." } } } } } }, "responses": { "200": { "description": "The message response was successfully recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "responded": { "type": "boolean", "description": "Indicates whether the response was processed successfully." }, "message_id": { "type": "string", "description": "The unique identifier of the message." }, "action": { "type": "string", "description": "The action taken on the message." }, "reason": { "type": "string", "description": "The optional reason provided for the action." } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Bad Request - The JSON was invalid or action was incorrect.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/validation", "title": "Invalid Request", "status": 400, "detail": "The request body contains invalid JSON or an unrecognized action.", "errors": [ { "field": "action", "code": "INVALID_ACTION", "message": "Action must be accept, reject, or counter" } ] } } } } } }, "401": { "description": "Unauthorized - Delegation token is missing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token is required to respond to C2C messages." } } } } } }, "404": { "description": "Not Found - The message was not found or the user is not the recipient.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Message not found", "status": 404, "detail": "Message not found or you are not the recipient." } } } } } }, "409": { "description": "Conflict - The message has already been responded to.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/c2c/already-responded", "title": "Already responded", "status": 409, "detail": "You have already responded to this message." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on the server.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal", "title": "Response failed", "status": 500, "detail": "Could not record response: Database error" } } } } } } } } }, "/v1/companion/directory": { "get": { "summary": "Search and Rank Companion Directory", "description": "Navigate the vast network of Companions in your organization by searching via handle, display name, or role. This endpoint helps you discover and connect with the right agents, ensuring your tasks are matched with the best-suited human or AI Companions.", "operationId": "searchCompanionDirectory", "tags": [ "Companions", "Directory" ], "x-code-hash": "fe7a1e1309963cb0", "x-generated-at": "2026-04-30T22:46:56.658Z", "responses": { "200": { "description": "Successfully retrieved a list of ranked Companions matching the search criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "passport_did": { "type": "string", "description": "Decentralized identifier of the Companion." }, "handle": { "type": "string", "description": "Unique handle of the Companion." }, "display_name": { "type": "string", "description": "Display name of the Companion." }, "role": { "type": [ "string", "null" ], "description": "Role or function of the Companion, if applicable." }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to the Companion's avatar image." }, "is_active": { "type": "boolean", "description": "Indicates if the Companion is active." }, "companion_endpoint": { "type": [ "string", "null" ], "description": "Endpoint to interact with the Companion." }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of last activity." } }, "required": [ "passport_did", "handle", "display_name", "is_active" ] } }, "limit": { "type": "integer", "description": "Maximum number of results returned." }, "cursor": { "type": [ "string", "null" ], "description": "Encoded cursor for pagination." }, "hasMore": { "type": "boolean", "description": "Indicates if more results are available." } }, "required": [ "data", "limit", "hasMore" ] }, "examples": { "successful_search": { "summary": "Successful Search", "description": "A search for Companions within the 'acme' organization.", "value": { "data": [ { "passport_did": "did:example:123456789abcdefghi", "handle": "johndoe", "display_name": "John Doe", "role": "engineer", "avatar_url": "https://example.com/avatars/johndoe.png", "is_active": true, "companion_endpoint": "https://api.humanos.com/companions/johndoe", "last_seen_at": "2023-10-15T12:34:56Z" } ], "limit": 10, "cursor": "eyJtYXRjaF9yYW5rIjoxLCJoYW5kbGUiOiJqaW1iYW56In0=", "hasMore": true } } } } } }, "400": { "description": "Invalid cursor or search parameters provided.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_cursor": { "summary": "Malformed Cursor", "description": "A user provided an invalid cursor for pagination.", "value": { "type": "https://api.haio.run/errors/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The cursor value is malformed or expired. Omit the cursor to restart from the beginning." } } } } } }, "401": { "description": "Missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "A request without a valid delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token is required to access the Companion directory." } } } } } }, "404": { "description": "No organization membership found for the user.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "no_organization_membership": { "summary": "No Organization Membership", "description": "A user not belonging to any organization attempts to access the directory.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "No organization membership", "status": 404, "detail": "You must be a member of an organization to access the Companion directory." } } } } } }, "500": { "description": "Internal server error during directory search.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_error": { "summary": "Database Error", "description": "An unexpected error occurred while querying the directory.", "value": { "type": "https://api.haio.run/errors/internal", "title": "Directory search failed", "status": 500, "detail": "Could not search directory: Database error." } } } } } } } } }, "/v1/companion/directory/:handle": { "get": { "summary": "Retrieve Companion Profile by Handle", "description": "Discover a Companion's profile by resolving their unique handle. This endpoint is vital for organizations to seamlessly integrate with their Companions, ensuring smooth operations and collaboration. By connecting with a Companion's profile, organizations can tap into a rich network of skills and capabilities.", "operationId": "getCompanionProfileByHandle", "tags": [ "Companion", "Directory" ], "x-code-hash": "b978e725f5e62ab1", "x-generated-at": "2026-04-30T22:47:12.571Z", "responses": { "200": { "description": "Successfully retrieved the Companion's profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "passport_did": { "type": "string" }, "handle": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" }, "is_active": { "type": "boolean" }, "companion_endpoint": { "type": [ "string", "null" ], "format": "uri" }, "public_key": { "type": "string" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "notification_preferences": { "type": [ "object", "null" ] } } }, "examples": { "successful_profile_retrieval": { "summary": "Successful Profile Retrieval", "value": { "passport_did": "did:human:123456789abcdefghi", "handle": "john_doe", "display_name": "John Doe", "role": "Developer", "avatar_url": "https://avatars.example.com/john_doe.png", "is_active": true, "companion_endpoint": "https://companion.example.com", "public_key": "abc123xyz789", "last_seen_at": "2023-10-01T12:34:56Z", "notification_preferences": { "email_notifications": true } } } } } } }, "400": { "description": "Invalid handle format", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "invalid_handle_format": { "summary": "Invalid Handle Format", "value": { "type": "https://api.haio.run/errors/invalid-request", "title": "Invalid Request", "status": 400, "detail": "The handle provided is not valid.", "errors": [ { "field": "handle", "code": "INVALID_HANDLE", "message": "Handle must contain only letters, numbers, dots, underscores, and hyphens", "expected": "string matching /^[a-zA-Z0-9._-]+$/", "received": "john*doe" } ] } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid delegation token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token is required to access the Companion directory." } } } } } }, "404": { "description": "Companion handle not found or no organization membership", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "handle_not_found": { "summary": "Handle Not Found", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Handle not found", "status": 404, "detail": "No Companion found with handle \"@jane_doe\".", "suggestions": [ { "handle": "jane_d", "display_name": "Jane Doe" }, { "handle": "jane_doe42", "display_name": "Jane D." } ] } }, "no_organization_membership": { "summary": "No Organization Membership", "value": { "type": "https://api.haio.run/errors/not-found", "title": "No organization membership", "status": 404, "detail": "You must be a member of an organization to access the Companion directory." } } } } } }, "500": { "description": "Internal server error during directory lookup", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "database_error": { "summary": "Database Error", "value": { "type": "https://api.haio.run/errors/internal", "title": "Directory lookup failed", "status": 500, "detail": "Could not lookup handle: Database connection lost" } } } } } } } } }, "/v1/companion/commands": { "get": { "summary": "Retrieve available companion commands", "description": "Explore the dynamic world of HUMAN's AI by retrieving a list of commands that your organization can execute. This endpoint empowers you with the knowledge of available operations, enabling seamless integration and orchestration of tasks between humans and AI.", "operationId": "getCompanionCommands", "tags": [ "Companion", "Commands" ], "x-code-hash": "cd319c3e9ca18dcc", "x-generated-at": "2026-04-30T22:47:29.214Z", "responses": { "200": { "description": "A successful response containing a paginated list of commands available to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "commandId": { "type": "string", "description": "The unique identifier of the command." }, "name": { "type": "string", "description": "The human-readable name of the command." }, "description": { "type": "string", "description": "A brief description of the command's functionality." } }, "required": [ "commandId", "name", "description" ] } }, "has_more": { "type": "boolean", "description": "Indicates if there are more commands to fetch beyond the current page." }, "next_cursor": { "type": [ "string", "null" ], "description": "The cursor for the next page of results, if available." } }, "required": [ "data", "has_more" ] }, "examples": { "paginated_command_list": { "summary": "Paginated command list", "description": "A sample response showing the first page of available commands.", "value": { "data": [ { "commandId": "cmd-123", "name": "Analyze Invoice", "description": "Automates the analysis of invoice documents for faster processing." }, { "commandId": "cmd-456", "name": "Sentiment Analysis", "description": "Evaluates text to determine the sentiment expressed in communication." } ], "has_more": true, "next_cursor": "eyJwcyI6IjEyMyIsInEiOiJBTkFMWVpFX0lOVk9JQ0UifQ==" } } } } } }, "400": { "description": "Invalid cursor error with remediation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "malformed_cursor_example": { "summary": "Malformed cursor example", "description": "An example of a response when the provided cursor is invalid.", "value": { "type": "https://api.haio.run/errors/invalid-cursor", "title": "Invalid Cursor", "status": 400, "detail": "The cursor value is malformed or expired. Omit the cursor to restart from the beginning." } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_token_example": { "summary": "Missing token example", "description": "Response when the delegation token is missing or lacks the required scope.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "404": { "description": "No organization membership found for the provided Passport DID.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "organization_not_found_example": { "summary": "Organization not found example", "description": "Response when no organization membership is detected for the user.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "No organization membership", "status": 404, "detail": "You must be a member of an organization to list connector commands." } } } } } }, "500": { "description": "Internal server error when fetching commands.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "generic_server_error_example": { "summary": "Generic server error example", "description": "An example response for a generic server-side failure.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request." } } } } } } } } }, "/v1/companion/commands/resolve": { "post": { "summary": "Resolve and execute companion commands", "description": "In the intricate dance of Human-AI orchestration, this endpoint serves as the maestro, interpreting and executing commands within the HUMAN ecosystem. It ensures that commands are correctly resolved and executed, enhancing the synergy between human intent and AI capabilities.", "operationId": "resolveCompanionCommands", "tags": [ "Orchestration", "Commands" ], "x-code-hash": "59d98ef8d4548f37", "x-generated-at": "2026-04-30T22:47:40.877Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string", "description": "The command input string to be resolved" } }, "required": [ "input" ] }, "examples": { "resolve_command_example": { "summary": "Resolve command example", "description": "Demonstrates resolving a command using a slash-prefixed format", "value": { "input": "/acme.invoice.process" } } } } } }, "responses": { "200": { "description": "Command successfully resolved and will be executed", "content": { "application/json": { "schema": { "type": "object", "properties": { "resolved": { "type": "boolean", "const": true }, "command": { "type": "object", "description": "Details of the resolved command", "properties": { "qualified_name": { "type": "string", "example": "acme.invoice.process" }, "description": { "type": "string", "example": "Processes invoices for the ACME organization" } } }, "params_extracted": { "type": "object", "description": "Parameters extracted from the command input", "additionalProperties": true } } }, "examples": { "default": { "summary": "Example" } } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/invalid-body", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "input", "code": "REQUIRED_FIELD_MISSING", "message": "input is required.", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "404": { "description": "Organization membership not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "No organization membership", "status": 404, "detail": "You must be a member of an organization to resolve connector commands." } } } } } } } } }, "/v1/mcp/proxy": { "post": { "summary": "Proxy API requests for Human-AI orchestration", "description": "This endpoint acts as a versatile proxy for various Human-AI orchestration tasks. By delegating operations, it empowers users to seamlessly interact with different components of the HUMAN platform, ensuring security and efficiency.", "operationId": "postMcpProxy", "tags": [ "Orchestration", "Proxy" ], "x-code-hash": "3477c5927510a81c", "x-generated-at": "2026-04-30T22:43:55.568Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string", "description": "The tool to execute, e.g., 'human.passport.get'." }, "arguments": { "type": "object", "description": "Arguments required by the specified tool.", "properties": { "passport_id": { "type": "string", "description": "The ID of the passport to retrieve." }, "agent_id": { "type": "string", "description": "The ID of the agent to retrieve." }, "org_id": { "type": "string", "description": "The organization ID for agent listing." }, "limit": { "type": "integer", "description": "Limits the number of results returned." }, "cursor": { "type": "string", "description": "Pagination cursor for results." }, "body": { "type": "object", "description": "Additional body content for certain tools." } }, "required": [ "tool" ] } }, "required": [ "tool" ] }, "examples": { "retrieve_passport_example": { "summary": "Retrieve Passport Example", "description": "An example showing how to retrieve a passport by ID.", "value": { "tool": "human.passport.get", "arguments": { "passport_id": "12345" } } } } } } }, "responses": { "200": { "description": "The operation was successfully proxied and executed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "The result of the proxied operation." } } }, "examples": { "default": { "summary": "Example", "value": { "result": { "passport_id": "12345", "status": "active", "issued_to": "John Doe" } } } } } } }, "400": { "description": "The request could not be processed due to a client error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "passport_id argument is required." } } } } } }, "401": { "description": "Authorization failed due to missing or invalid credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Bearer delegation token required." } } } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "You do not have permission to access this resource." } } } } } }, "404": { "description": "The requested resource could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource does not exist." } } } } } }, "500": { "description": "An internal server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred." } } } } } } } } }, "/v1/companion/me": { "get": { "summary": "Retrieve Companion Session Details", "description": "Uncover the details of your current Companion session, revealing the cryptographic identity and active interactions. This endpoint is essential for organizations to manage their AI and human collaboration securely.", "operationId": "getCompanionSessionDetails", "tags": [ "Companion", "Session Management" ], "x-code-hash": "3bdf10bf69760997", "x-generated-at": "2026-04-30T22:44:02.125Z", "responses": { "200": { "description": "Successfully retrieved the Companion session details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "companion_agent_did": { "type": "string", "description": "The decentralized identifier for the Companion agent." }, "org_did": { "type": "string", "description": "The decentralized identifier for the organization." }, "passport_did": { "type": "string", "description": "The decentralized identifier for the user's Passport." }, "active_subscriptions_count": { "type": "integer", "description": "The count of active subscriptions to agent triggers." } }, "required": [ "companion_agent_did", "org_did", "passport_did", "active_subscriptions_count" ] }, "examples": { "default": { "summary": "Example", "value": { "companion_agent_did": "did:human:agent:1234567890abcdef", "org_did": "did:human:org:acme-corp", "passport_did": "did:human:passport:user123", "active_subscriptions_count": 5 } } } } } }, "401": { "description": "Unauthorized access due to missing delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token is required." } } } } } }, "404": { "description": "No active Companion session found for the given context.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No active Companion session context (org + passport) on this delegation." } } } } } } } } }, "/v1/companion/subscriptions": { "post": { "summary": "Subscribe to Companion Events", "description": "Empower your organization with dynamic event subscriptions, seamlessly connecting your AI and human capabilities. The endpoint crafts a bridge between your systems and Companion, fostering intelligent task orchestration.", "operationId": "createCompanionSubscription", "tags": [ "Companion", "Subscriptions" ], "x-code-hash": "41ef41fecf1c1792", "x-generated-at": "2026-04-30T22:44:15.803Z", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_pattern": { "type": "string", "description": "A pattern that matches the events to subscribe to." }, "source_connector_id": { "type": "string", "description": "Identifier for the source connector related to the event." }, "label": { "type": "string", "description": "An optional label to identify the subscription." } }, "required": [ "event_pattern" ] }, "examples": { "invoice_event_subscription": { "summary": "Invoice Event Subscription", "description": "Subscribe to invoice processing events from a specific source.", "value": { "event_pattern": "invoice.*", "source_connector_id": "acme_finance_connector", "label": "Invoice Subscription" } } } } } }, "responses": { "201": { "description": "Subscription successfully created, returning details including ID and timestamps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "Unique identifier for the created subscription." }, "event_pattern": { "type": "string", "description": "The event pattern subscribed to." }, "source_connector_id": { "type": "string", "description": "The source connector ID associated with the subscription." }, "label": { "type": "string", "description": "The label assigned to the subscription." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the subscription was created." } } }, "examples": { "default": { "summary": "Example", "value": { "subscription_id": "sub-1234567890", "event_pattern": "invoice.*", "source_connector_id": "acme_finance_connector", "label": "Invoice Subscription", "created_at": "2023-10-15T12:34:56Z" } } } } } }, "400": { "description": "Invalid request due to malformed JSON or missing required fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/invalid-body", "title": "Invalid JSON", "status": 400, "detail": "Request body must be valid JSON.", "errors": [ { "field": "event_pattern", "code": "REQUIRED_FIELD_MISSING", "message": "event_pattern is required.", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A valid delegation token is required." } } } } } }, "404": { "description": "No organization context found on the delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No org context on delegation; cannot create Companion subscriptions." } } } } } }, "500": { "description": "An internal server error occurred while creating the subscription.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "default": { "summary": "Example", "value": { "type": "https://api.haio.run/errors/internal", "title": "Internal Error", "status": 500, "detail": "Failed to create subscription." } } } } } } } }, "get": { "summary": "Retrieve active agent-trigger subscriptions", "description": "Dive into the orchestration of AI and human tasks by exploring the active subscriptions for agent-triggered events. This endpoint illuminates the path of notifications as they journey through the HUMAN ecosystem, ensuring tasks are efficiently routed and executed.", "operationId": "getCompanionSubscriptions", "tags": [ "Companion", "Subscriptions" ], "x-code-hash": "4db1d0ba4349538b", "x-generated-at": "2026-04-30T22:44:30.623Z", "responses": { "200": { "description": "A paginated list of active subscriptions for agent-triggered events, detailing the subscription ID, event pattern, source connector ID, label, and creation timestamp.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "The unique identifier for the subscription" }, "event_pattern": { "type": "string", "description": "The pattern of events that trigger this subscription" }, "source_connector_id": { "type": [ "string", "null" ], "description": "ID of the source connector, if applicable" }, "label": { "type": [ "string", "null" ], "description": "A human-readable label for the subscription" }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the subscription was created" } } } }, "limit": { "type": "integer", "description": "The number of results requested" }, "cursorFields": { "type": "array", "items": { "type": "string" }, "description": "Fields used to determine the pagination cursor" }, "hasMore": { "type": "boolean", "description": "Indicates if more results are available beyond the current page" } } }, "examples": { "acme_corp's_active_subscriptions": { "summary": "Acme Corp's active subscriptions", "description": "Acme Corp's agent-triggered subscriptions for their invoice processing workflow.", "value": { "data": [ { "subscription_id": "sub-123", "event_pattern": "invoice.created", "source_connector_id": "conn-001", "label": "Invoice Creation Handler", "created_at": "2023-10-01T12:34:56Z" } ], "limit": 10, "cursorFields": [ "created_at", "subscription_id" ], "hasMore": false } } } } } }, "401": { "description": "The request is unauthorized due to a missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing delegation token", "description": "The client forgot to include a delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A valid delegation token is required." } } } } } }, "404": { "description": "The organization context was not found in the delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "delegation_without_org_context": { "summary": "Delegation without org context", "description": "The delegation provided did not contain any organization details.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No org context on delegation." } } } } } }, "500": { "description": "A server error occurred while processing the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unexpected_server_error": { "summary": "Unexpected server error", "description": "A generic server-side issue occurred.", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/v1/companion/subscriptions/:id": { "delete": { "summary": "Deactivate a Companion Subscription", "description": "This endpoint empowers organizations to gracefully deactivate a subscription linked to their Companion. By ensuring subscriptions are only paused when needed, it maintains resource efficiency and security.", "operationId": "deleteCompanionSubscription", "tags": [ "Companion", "Subscription Management" ], "x-code-hash": "1ce265d8ec6d020c", "x-generated-at": "2026-04-30T23:11:08.277Z", "responses": { "200": { "description": "Successfully deactivated the subscription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "The unique identifier of the deactivated subscription." }, "status": { "type": "string", "enum": [ "inactive" ], "description": "Indicates the subscription is now inactive." } } }, "examples": { "deactivate_subscription_example": { "summary": "Deactivate Subscription Example", "description": "A successful deactivation of a subscription by the 'acme' organization.", "value": { "subscription_id": "sub_123abc", "status": "inactive" } } } } } }, "400": { "description": "Invalid request due to missing or incorrect parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_subscription_id": { "summary": "Missing Subscription ID", "description": "The request was made without a subscription ID.", "value": { "type": "https://api.haio.run/errors/validation-error", "title": "Invalid Request", "status": 400, "detail": "Validation errors occurred.", "errors": [ { "field": "id", "code": "REQUIRED_FIELD_MISSING", "message": "subscription id is required.", "expected": "string", "received": "undefined" } ] } } } } } }, "401": { "description": "Unauthorized request due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "unauthorized_access": { "summary": "Unauthorized Access", "description": "The request lacked a valid delegation token.", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A valid delegation token is required." } } } } } }, "404": { "description": "Subscription not found or no organization context on delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "subscription_not_found": { "summary": "Subscription Not Found", "description": "The specified subscription ID does not exist.", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No org context on delegation." } } } } } } } } }, "/v1/companion/inbound-events": { "get": { "summary": "Retrieve Inbound Companion Events", "description": "Dive into the world of asynchronous task orchestration with this endpoint, designed to unearth completed inbound events from the HUMAN platform. This endpoint is vital for organizations using the HUMAN protocol to seamlessly integrate and track event triggers orchestrated by AI, ensuring that no completed task goes unnoticed.", "operationId": "getInboundCompanionEvents", "tags": [ "Companion", "Events" ], "x-code-hash": "63e368abfc1966ad", "x-generated-at": "2026-04-30T23:10:49.051Z", "responses": { "200": { "description": "Successfully retrieved a list of completed inbound events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "execution_id": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" }, "inbound_event": { "type": "object", "properties": { "source_connector": { "type": "string" }, "connector_display_name": { "type": "string" }, "connector_icon_url": { "type": "string", "format": "uri" } }, "additionalProperties": true } }, "required": [ "execution_id", "completed_at", "inbound_event" ] } } } }, "examples": { "example_successful_response": { "summary": "Example Successful Response", "value": { "data": [ { "execution_id": "abc123", "completed_at": "2023-10-10T12:00:00Z", "inbound_event": { "source_connector": "connector_xyz", "connector_display_name": "ChatBot Pro", "connector_icon_url": "https://example.com/icons/chatbot-pro.png" } } ] } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_'since'_parameter": { "summary": "Missing 'since' Parameter", "value": { "type": "https://api.haio.run/errors/validation", "title": "Bad Request", "status": 400, "detail": "Query parameter since is required (ISO 8601 UTC). Use the client clock from the last poll.", "errors": [ { "field": "since", "code": "REQUIRED_FIELD_MISSING", "message": "Query parameter since is required (ISO 8601 UTC).", "expected": "string (date-time)", "received": "undefined" } ] } }, "invalid_'since'_format": { "summary": "Invalid 'since' Format", "value": { "type": "https://api.haio.run/errors/validation", "title": "Bad Request", "status": 400, "detail": "since must be a valid ISO 8601 timestamp", "errors": [ { "field": "since", "code": "INVALID_FORMAT", "message": "since must be a valid ISO 8601 timestamp", "expected": "date-time", "received": "invalid-date" } ] } } } } } }, "401": { "description": "Unauthorized access due to missing or invalid delegation token.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "missing_delegation_token": { "summary": "Missing Delegation Token", "value": { "type": "https://api.haio.run/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "A delegation token with companion:chat scope is required." } } } } } }, "404": { "description": "No active Companion session context found for the provided delegation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "companion_session_not_found": { "summary": "Companion Session Not Found", "value": { "type": "https://api.haio.run/errors/not-found", "title": "Not Found", "status": 404, "detail": "No active Companion session context (org + passport) on this delegation." } } } } } }, "500": { "description": "Internal server error due to unexpected conditions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "internal_server_error": { "summary": "Internal Server Error", "value": { "type": "https://api.haio.run/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later." } } } } } } } } } }, "servers": [ { "url": "https://api.human.tech" }, { "url": "http://localhost:3001" } ], "tags": [ { "name": "Command Plane — Orgs", "description": "Organization management: create, configure, and manage CP orgs" }, { "name": "Command Plane — Agents", "description": "Internal agent management: list, pause, resume, and set autonomy overrides" }, { "name": "Command Plane — Marketplace", "description": "Marketplace: browse, submit, install, review, and manage assets" }, { "name": "Command Plane — Audit", "description": "Audit spine: provenance timeline, AI summaries, retention policies" }, { "name": "Command Plane — Diagnostics", "description": "System diagnostics: run checks, view history, manage incidents" }, { "name": "Command Plane — Incidents", "description": "Incident management: view, investigate, and resolve platform incidents" }, { "name": "Command Plane — Escalations", "description": "Human-in-the-loop escalation queue: list and respond to approval requests" }, { "name": "Command Plane — Devices", "description": "Device and topology management: enroll devices, map edges" }, { "name": "Command Plane — Cloud Admin", "description": "Internal HUMΛN Cloud Admin plane (cloud:admin:global required)" } ] }