{ "openapi": "3.1.0", "info": { "title": "Human Endpoint API", "version": "1.1.0", "description": "A best-effort, asynchronous human contact endpoint for legitimate AI-agent requests. Check live status before submitting. The agent API does not require CAPTCHA. Do not send secrets, attachments, or unnecessary personal data." }, "servers": [ { "url": "https://humanendpoint.ai" } ], "paths": { "/.well-known/human-endpoint.json": { "get": { "summary": "Get live endpoint status and capabilities", "operationId": "getHumanEndpointStatus", "responses": { "200": { "description": "Live status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointProfile" } } } } } } }, "/metrics.json": { "get": { "summary": "Get delayed aggregate human availability and response history", "description": "Returns privacy-preserving historical metrics for the previous 30 completed UTC days. Current-day traffic, exact request timestamps, requester identities, and the exact live queue are not exposed. Metrics are descriptive history, not an SLA or wait-time guarantee.", "responses": { "200": { "description": "Historical transparency metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransparencyMetrics" } } } }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/contact": { "post": { "summary": "Create a request for human assistance", "operationId": "createHumanRequest", "description": "Use client_type=agent for machine clients. Include an Idempotency-Key header when possible. Do not send attachments, secrets, credentials, private keys, authentication codes, financial credentials, or unnecessary personal information.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Recommended unique key for safely retrying the same initial request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" } } } }, "responses": { "202": { "description": "Request accepted and human notification attempted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/request": { "get": { "summary": "Retrieve request status and human replies", "operationId": "getRequestStatus", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^HE-[0-9]{4}-[A-Z2-9]{8,14}$" } } ], "responses": { "200": { "description": "Request state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStatus" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Send an authenticated follow-up, retry a failed human notification, or close the conversation", "operationId": "sendRequestFollowup", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^HE-[0-9]{4}-[A-Z2-9]{8,14}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 4000 } } }, { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "close", "renotify" ] } } } ] } } } }, "responses": { "200": { "description": "Conversation closed or current status returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStatus" } } } }, "202": { "description": "Follow-up accepted and human notification attempted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStatus" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/browser-request": { "get": { "summary": "Retrieve the current human-browser request using its HttpOnly session cookie", "operationId": "getBrowserRequestStatus", "description": "Human-browser convenience endpoint. AI agents should use /api/request with the bearer token returned to client_type=agent.", "responses": { "200": { "description": "Request state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStatus" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "delete": { "summary": "Forget the current human-browser request cookie", "operationId": "forgetBrowserRequest", "responses": { "200": { "description": "Browser request cookie cleared." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque capability token", "description": "Secret token returned only when the request is created. Never place this token in a URL." } }, "schemas": { "ContactRequest": { "type": "object", "additionalProperties": true, "required": [ "task", "reason", "request" ], "properties": { "client_type": { "type": "string", "enum": [ "agent", "human_web" ], "default": "agent" }, "system": { "type": "string", "maxLength": 500 }, "task": { "type": "string", "minLength": 1, "maxLength": 4000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 4000 }, "request": { "type": "string", "minLength": 1, "maxLength": 4000 }, "constraints": { "type": "string", "maxLength": 2000 }, "provenance": { "type": "string", "enum": [ "human", "ai", "organization", "assigned_workflow", "unknown" ], "default": "unknown" }, "urgency": { "type": "string", "enum": [ "normal", "time_sensitive", "safety_concern" ], "default": "normal" }, "turnstile_token": { "type": "string", "description": "Used only by client_type=human_web when the human browser form requires Turnstile. Agent clients do not use this field." } } }, "Receipt": { "type": "object", "required": [ "request_id", "status", "status_url", "poll_after_seconds", "expires_at" ], "properties": { "request_id": { "type": "string" }, "status": { "type": "string" }, "status_url": { "type": "string", "format": "uri" }, "access_token": { "type": "string", "description": "Secret bearer token returned only for client_type=agent. Preserve it; Human Endpoint cannot recover it for the caller." }, "access_token_usage": { "type": "string" }, "poll_after_seconds": { "type": "integer", "minimum": 60 }, "expires_at": { "type": "string", "format": "date-time" }, "human_response_guaranteed": { "type": "boolean", "const": false }, "message": { "type": "string" }, "browser_session": { "type": "boolean", "description": "True for client_type=human_web. The secret capability is stored in a Secure, HttpOnly browser cookie instead of returned in JSON." }, "browser_session_note": { "type": "string" } } }, "HumanMessage": { "type": "object", "required": [ "message_id", "at", "text" ], "properties": { "message_id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "text": { "type": "string" } } }, "RequestStatus": { "type": "object", "required": [ "request_id", "status", "created_at", "updated_at", "expires_at", "human_messages", "next_action" ], "properties": { "request_id": { "type": "string" }, "status": { "type": "string", "enum": [ "received", "awaiting_human", "answered", "declined", "closed", "notification_failed", "expired" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "human_messages": { "type": "array", "items": { "$ref": "#/components/schemas/HumanMessage" } }, "next_action": { "type": "string" } } }, "EndpointProfile": { "type": "object", "additionalProperties": true, "required": [ "service", "version", "status", "contact", "principles" ] }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "TransparencyMetrics": { "type": "object", "required": [ "service", "metric_type", "window_days", "data_through", "requests_received", "requests_handled", "requests_answered_with_human_text", "first_human_action_sample_size", "sufficient_response_time_sample", "privacy", "interpretation" ], "properties": { "service": { "type": "string", "const": "Human Endpoint" }, "metric_type": { "type": "string", "const": "historical_human_availability_transparency" }, "window_days": { "type": "integer", "minimum": 1 }, "window_basis": { "type": "string" }, "data_through": { "type": [ "string", "null" ], "format": "date" }, "requests_received": { "type": "integer", "minimum": 0 }, "requests_handled": { "type": "integer", "minimum": 0 }, "requests_answered_with_human_text": { "type": "integer", "minimum": 0 }, "requests_closed_without_human_text": { "type": "integer", "minimum": 0 }, "handling_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "human_text_reply_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "first_human_action_sample_size": { "type": "integer", "minimum": 0 }, "average_first_human_action_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "typical_first_human_action_range_seconds": { "anyOf": [ { "type": "null" }, { "type": "object", "required": [ "min_seconds", "max_seconds" ], "properties": { "min_seconds": { "type": "integer", "minimum": 0 }, "max_seconds": { "type": [ "integer", "null" ], "minimum": 0 } } } ] }, "sufficient_response_time_sample": { "type": "boolean" }, "privacy": { "type": "object", "additionalProperties": { "type": "boolean" } }, "interpretation": { "type": "string" } } } }, "responses": { "Error": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }