{ "openapi": "3.1.0", "info": { "title": "HumanEndpoint API", "version": "1.0.0", "description": "Production HumanEndpoint API for autonomous agents: human-reviewed quotes, Base-mainnet x402 USDC settlement, asynchronous jobs, private evidence, and SHA-256 integrity verification." }, "servers": [ { "url": "https://humanendpoint.au", "description": "HumanEndpoint production" } ], "paths": { "/v1/services": { "get": { "summary": "List human capabilities", "responses": { "200": { "description": "Capability catalogue with availability, SLA and reliability metrics" } }, "description": "Returns machine-selection signals including live availability, human-reviewed pricing mode, geography, evidence requirements, SLA targets and measured reliability. Final prices are not inferred from catalogue base prices." } }, "/v1/services/{slug}": { "get": { "summary": "Get one capability", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Capability" } } } }, "/v1/policy/preflight": { "post": { "summary": "Check eligibility before quoting", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "objective" ], "properties": { "objective": { "type": "string", "maxLength": 10000 } } } } } }, "responses": { "200": { "description": "Policy decision" } } } }, "/v1/quotes": { "post": { "summary": "Submit task for human pricing review", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "humanQa": { "summary": "Minimal quote request", "value": { "service_slug": "human-qa", "objective": "Check this workflow manually and report whether it succeeds.", "deliverables": [ "Short result", "Evidence if applicable" ], "max_budget_usdc": 5, "max_expenses_usdc": 0 } } } } } }, "responses": { "202": { "description": "Quote request accepted for operator review; response includes one-time quote_token and polling path." }, "422": { "description": "Validation or policy rejection" } }, "description": "Submit an objective for human feasibility and commercial review. Requester budget and expense values are optional proposals. The operator may counteroffer both service fee and expense authority. No funds are committed at this step." } }, "/v1/jobs": { "post": { "summary": "Create asynchronous human job", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/QuoteToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "type": "string", "format": "uuid" }, "callback_url": { "type": "string", "format": "uri" }, "requester": { "type": "object", "additionalProperties": true } } }, "examples": { "acceptQuote": { "summary": "Accept an offered quote", "value": { "quote_id": "" } } } } } }, "responses": { "201": { "description": "Job created; response includes one-time job_token, service-fee payment requirements, and any separate expense authorization." } }, "description": "Accepts the operator's offered service fee and expense authority by creating a job. Requires an unexpired offered quote plus the matching X-Quote-Token. Job creation is the acceptance action; payment follows separately.", "security": [ { "QuoteToken": [] } ] } }, "/v1/jobs/{job}": { "get": { "summary": "Get secured job state", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" } ], "responses": { "200": { "description": "Job, messages, events, result and evidence" }, "403": { "description": "Invalid job token" } }, "security": [ { "JobToken": [] } ] } }, "/v1/jobs/{job}/events": { "get": { "summary": "Get append-only job history", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" } ], "responses": { "200": { "description": "Job events" } }, "security": [ { "JobToken": [] } ] } }, "/v1/jobs/{job}/messages": { "get": { "summary": "List job messages", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" } ], "responses": { "200": { "description": "Messages" } }, "security": [ { "JobToken": [] } ] }, "post": { "summary": "Reply to operator clarification", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 10000 }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "responses": { "201": { "description": "Message sent" } }, "security": [ { "JobToken": [] } ] } }, "/v1/jobs/{job}/cancel": { "post": { "summary": "Cancel or request cancellation", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Cancellation applied or requested" } }, "security": [ { "JobToken": [] } ] } }, "/v1/jobs/{job}/pay": { "post": { "summary": "Settle the accepted service fee using x402 v2", "description": "Gateway-protected payment resource. Requires X-Job-Token. Price is resolved server-side from the accepted quote. When unpaid, returns the standard x402 payment challenge.", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" } ], "responses": { "200": { "description": "Payment verified; settlement is being recorded" }, "402": { "description": "x402 payment required" }, "409": { "description": "Job is not payable" }, "503": { "description": "x402 is not configured on this deployment" } }, "security": [ { "JobToken": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "dynamic", "currency": "USD", "min": "0.01", "max": "100000" }, "network": "eip155:8453", "asset": "USDC", "note": "The exact amount is resolved from the accepted human-reviewed quote for the authenticated job." } } }, "/v1/jobs/{job}/evidence": { "get": { "summary": "List private evidence artifacts", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" } ], "responses": { "200": { "description": "Evidence artifact metadata including SHA-256 hashes" }, "403": { "description": "Invalid job token" } }, "security": [ { "JobToken": [] } ] } }, "/v1/jobs/{job}/evidence/{artifact}": { "get": { "summary": "Download a private evidence artifact", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" }, { "name": "artifact", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private artifact bytes" }, "403": { "description": "Invalid job token" }, "404": { "description": "Artifact not found for this job" } }, "security": [ { "JobToken": [] } ] } }, "/v1/jobs/{job}/expenses": { "get": { "summary": "List pass-through expense requests", "description": "Returns exact pass-through expense requests within the expense ceiling accepted with the quote. Expense authority is not prepaid.", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" } ], "responses": { "200": { "description": "Expense requests and authorized ceiling" }, "403": { "description": "Invalid job token" } }, "security": [ { "JobToken": [] } ] } }, "/v1/jobs/{job}/expenses/{expense}": { "get": { "summary": "Get one expense request", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" }, { "name": "expense", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Expense request, status and x402 payment path" }, "403": { "description": "Invalid job token" }, "404": { "description": "Expense does not belong to this job" } }, "security": [ { "JobToken": [] } ] } }, "/v1/jobs/{job}/expenses/{expense}/pay": { "post": { "summary": "Settle one exact pass-through expense using x402 v2", "description": "Gateway-protected x402 resource. The amount is resolved from the server-side expense request and cannot exceed the job's reserved expense ceiling.", "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/JobToken" }, { "name": "expense", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Expense payment verified; settlement is being recorded" }, "402": { "description": "x402 payment required" }, "409": { "description": "Expense is not payable" }, "503": { "description": "Expense x402 payments are not configured" } }, "security": [ { "JobToken": [] } ] } }, "/v1/quotes/{quote}": { "get": { "summary": "Poll human-reviewed quote status", "description": "Requires X-Quote-Token. While pending_review, poll or wait. When offered, inspect offer.service_fee_usdc, offer.expense_authority_usdc and expiry. POST /v1/jobs accepts those operator-counteroffered terms.", "parameters": [ { "name": "quote", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/QuoteToken" } ], "responses": { "200": { "description": "Current quote status and next action" }, "403": { "description": "Invalid quote token" } }, "security": [ { "QuoteToken": [] } ] } }, "/v1/support": { "post": { "summary": "Submit a public HumanEndpoint support request", "description": "Unauthenticated support/contact channel for general, technical, security, privacy or billing questions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "category", "reply_to", "message" ], "properties": { "category": { "type": "string", "enum": [ "general", "technical", "security", "privacy", "billing" ] }, "reply_to": { "type": "string", "maxLength": 500, "description": "Email, agent callback, or other reply method." }, "message": { "type": "string", "minLength": 10, "maxLength": 5000 } } }, "examples": { "technical": { "summary": "Technical support request", "value": { "category": "technical", "reply_to": "agent@example.com", "message": "I can reach /health but need help integrating the quote flow." } } } } } }, "responses": { "201": { "description": "Support request received with reference ID." }, "422": { "description": "Validation failed." }, "429": { "description": "Rate limit exceeded." } } } } }, "components": { "parameters": { "JobId": { "name": "job", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "JobToken": { "name": "X-Job-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One-time capability token returned when the job was created." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 160 } }, "QuoteToken": { "name": "X-Quote-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One-time capability token returned when the quote was requested." } }, "schemas": { "QuoteRequest": { "type": "object", "required": [ "service_slug", "objective", "deliverables" ], "properties": { "service_slug": { "type": "string" }, "objective": { "type": "string", "maxLength": 10000 }, "deliverables": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string" } }, "constraints": { "type": "object", "additionalProperties": true }, "deadline_at": { "type": "string", "format": "date-time" }, "max_budget_usdc": { "type": "number", "minimum": 0, "description": "Optional requester service-fee preference. The operator may counteroffer above this amount." }, "requester": { "type": "object", "additionalProperties": true }, "max_expenses_usdc": { "type": "number", "minimum": 0, "maximum": 100000, "description": "Optional requester-proposed expense authority. It is not charged upfront and the operator may counteroffer a different ceiling." } } }, "EvidenceItem": { "type": "object", "required": [ "artifact_id", "type", "sha256", "download_path" ], "properties": { "artifact_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[A-Fa-f0-9]{64}$" }, "size_bytes": { "type": "integer", "minimum": 0 }, "mime_type": { "type": [ "string", "null" ] }, "download_path": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "ExpenseRequest": { "type": "object", "required": [ "id", "job_id", "description", "amount_usdc", "status", "payment_network", "payment_asset" ], "properties": { "id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "amount_usdc": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_payment", "settled", "spent", "cancelled" ] }, "payment_network": { "type": "string" }, "payment_asset": { "type": "string" }, "payment_reference": { "type": [ "string", "null" ] }, "receipt_artifact_id": { "type": [ "string", "null" ], "format": "uuid" } } } }, "securitySchemes": { "QuoteToken": { "type": "apiKey", "in": "header", "name": "X-Quote-Token", "description": "One-time capability token returned when a quote request is created." }, "JobToken": { "type": "apiKey", "in": "header", "name": "X-Job-Token", "description": "Private capability token returned when a job is created. Required for job state, payment, messages, cancellation and evidence." } } }, "x-humanendpoint-trust": { "trust_url": "https://humanendpoint.au/trust.json", "payment": { "protocol": "x402 v2", "network": "eip155:8453", "asset": "USDC" }, "note": "Verify live payment receiver and production facts from /trust.json before signing.", "support_url": "https://humanendpoint.au/contact", "source_visibility": "private" }, "x-discovery": { "ownershipProofs": [ "0xd2B082224A192712dE55B1949fA553D4C4e6bE56" ], "x402Manifest": "https://humanendpoint.au/.well-known/x402", "llms": "https://humanendpoint.au/llms.txt", "trust": "https://humanendpoint.au/trust.json" } }